Alibaba Cloud Service Mesh:Transcode HTTP/JSON requests to gRPC with ASMGrpcJsonTranscoder

How it works

The ingress gateway handles all transcoding. No application-level changes are required beyond the .proto annotation.

Prerequisites

Before you begin, make sure that you have:

• An ASM instance of Enterprise Edition or Ultimate Edition. See Create an ASM instance

• A cluster added to the ASM instance

• A gRPC sample service deployed in the cluster. See Use an ingress gateway to access a gRPC service in an ASM instance

• Protocol Buffers (protoc) installed locally

Add HTTP annotations and generate a proto descriptor

To map an HTTP endpoint to a gRPC method, add a google.api.http annotation in the .proto file and compile it into a .proto-descriptor file that the Envoy filter reads at runtime.

option(google.api.http) = {
    get: "/sayHello/{name}"
};

// Copyright 2015 gRPC authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

option java_multiple_files = true;
option java_package = "io.grpc.examples.helloworld";
option java_outer_classname = "HelloWorldProto";
option objc_class_prefix = "HLW";

package helloworld;
import "google/api/annotations.proto";

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {
    option(google.api.http) = {
        get: "/sayHello/{name}"
    };
  }

  rpc SayHelloStreamReply (HelloRequest) returns (stream HelloReply) {}

  rpc SayHelloBidiStream (stream HelloRequest) returns (stream HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings.
message HelloReply {
  string message = 1;
}

Create the ASMGrpcJsonTranscoder resource

The ASMGrpcJsonTranscoder CRD instructs the ASM control plane to configure gRPC-JSON transcoding on the ingress gateway.

1. Save the following YAML as grpcjsontranscoder-helloworld.yaml:

      apiVersion: istio.alibabacloud.com/v1beta1
      kind: ASMGrpcJsonTranscoder
      metadata:
        name: grpcjsontranscoder-helloworld
        namespace: istio-system
      spec:
        isGateway: true                    # Apply the transcoder to the ingress gateway
        portNumber: 8080                   # Port for HTTP/JSON requests
        workloadSelector:
          labels:
            istio: ingressgateway          # Target the default ingress gateway
        printOptions:
          addWhitespace: true              # Pretty-print JSON responses
          alwaysPrintEnumsAsInts: false     # Print enum names instead of integer values
          alwaysPrintPrimitiveFields: false # Omit fields with default values from responses
          preserveProtoFieldNames: false    # Use camelCase field names (protobuf default)
        priority: 0
        services:
          - helloworld.Greeter             # Fully qualified gRPC service name (<package>.<service>)

2. Review the key fields:

   Field	Description	Default
   isGateway	Set to true to apply the transcoder on the ingress gateway rather than on sidecar proxies.	false
   portNumber	The port on the ingress gateway that accepts HTTP/JSON requests.	--
   workloadSelector.labels	Label selector that identifies which gateway workload receives the Envoy filter.	--
   services	List of fully qualified gRPC service names (<package>.<service>) to transcode.	--
   printOptions.addWhitespace	Pretty-print JSON responses with indentation.	false
   printOptions.alwaysPrintEnumsAsInts	Print enum values as integers instead of names.	false
   printOptions.alwaysPrintPrimitiveFields	Include fields with default values (e.g., an int32 set to 0) in the JSON response. When false, these fields are omitted.	false
   printOptions.preserveProtoFieldNames	Use the original proto field names in JSON output instead of converting to camelCase.	false

   For the full field reference, see ASMGrpcJsonTranscoder field descriptions.

3. Apply the resource:

      kubectl apply -f grpcjsontranscoder-helloworld.yaml

Verify transcoding

After you apply the ASMGrpcJsonTranscoder resource, the ingress gateway accepts HTTP/JSON requests and transcodes them to gRPC.

1. Get the ingress gateway IP address:

      kubectl -n istio-system get svc istio-ingressgateway \
          -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

2. Send a test request to port 8080:

      curl http://<ingress-gateway-ip>:8080/sayHello/Mark

   Replace <ingress-gateway-ip> with the IP address from step 1.

3. Verify the response. A successful response looks like this:

      {
       "message": "Hello, Mark! I'm from grpc-helloworld-py-v1-79b5dc9654-cg4dq!"
      }

   A JSON response from the backend gRPC service confirms that HTTP-to-gRPC transcoding is working.

What's next

• ASMGrpcJsonTranscoder field descriptions: full CRD field reference.

• Use an ingress gateway to access a gRPC service in an ASM instance: set up direct gRPC access without HTTP transcoding.