Description of ASMGrpcJsonTranscoder fields - Alibaba Cloud Service Mesh

ASMGrpcJsonTranscoder is a Custom Resource Definition (CRD) in Alibaba Cloud Service Mesh (ASM) that transcodes between HTTP/JSON and gRPC/Protobuf. Deploy this CRD to expose gRPC services as RESTful HTTP endpoints, so HTTP clients can call them without a dedicated gRPC client.

Full configuration

The following YAML shows all configurable fields in an ASMGrpcJsonTranscoder resource:

workloadSelector:
  <label-key>: <label-value>        # Required. Labels to select target pods.
isGateway: false                     # Optional. Apply to gateway instead of sidecars.
portNumber: <service-port>           # Required. Service port for transcoding.
services:                            # Required. gRPC services in {package}.{service} format.
  - '<package-name>.<service-name>'
protoDescriptorBin: <base64-string>  # Required. Base64-encoded proto descriptor set.
transcodeFirst: false                # Optional. Transcode before other filter processing.
convertGrpcStatus: false             # Optional. Convert gRPC errors to JSON responses.
ignoredQueryParameters:              # Optional. Specific query params to skip.
  - <param-name>
ignoreUnknownQueryParameters: <bool>  # Optional. Skip all unmapped query params.

Fields

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	Labels that select the pods where this configuration takes effect. The label scope is limited to the namespace of the resource. For more information, see Workload Selector.
isGateway	bool	No	Whether to apply the configuration to a gateway. Default: `false`.
portNumber	int	Yes	The service port to transcode. If `isGateway` is `true`, this specifies the service port (such as `8080`) that performs transcoding on the gateway.
services	string[]	Yes	The gRPC services declared in the proto file, in `{package name}.{service name}` format. See the Services format section below.
protoDescriptorBin	string	Yes	The Base64-encoded content of the proto descriptor set file. See the Generate a proto descriptor section below.
transcodeFirst	bool	No	Whether to transcode HTTP requests before other processing. Default: `false`. See the Transcode order section below.
convertGrpcStatus	bool	No	Whether to convert gRPC error status to a JSON response body. Default: `false`. See the gRPC status conversion section below.
ignoredQueryParameters	[]string	No	Query parameters to skip during transcoding method mapping. Use this when you know exactly which parameters to ignore. See the Query parameter handling section below.
ignoreUnknownQueryParameters	bool	No	Whether to ignore all query parameters that cannot be mapped to protobuf fields. Use this when you cannot predict which query parameters the request will contain. See the Query parameter handling section below.

Field details

Services format

Specify each gRPC service in {package name}.{service name} format, matching the definitions in your proto file:

services:
  - 'helloworld.Greeter'

Generate a proto descriptor

The protoDescriptorBin field requires a Base64-encoded proto descriptor set. Generate one as follows:

Clone the googleapis repository, which contains the required proto annotations:

   git clone https://github.com/googleapis/googleapis
   GOOGLEAPIS_DIR=<path-to-local-googleapis-folder>

Run protoc to generate the descriptor set:

   protoc -I${GOOGLEAPIS_DIR} -I. \
     --include_imports \
     --include_source_info \
     --descriptor_set_out=proto.pb \
     your_service.proto

Base64-encode the output file and use the result as the protoDescriptorBin value:
```
   base64 -w 0 proto.pb
```

Transcode order

When transcodeFirst is set to true, inbound HTTP requests are transcoded to gRPC before any other filter processing. This affects request-based traffic control features such as external authorization.

For example, when a request passes through a custom external authorization service:

transcodeFirst: true -- The authorization service receives a gRPC request.
transcodeFirst: false (default) -- The authorization service receives an HTTP request.

gRPC status conversion

When convertGrpcStatus is set to true and a gRPC error is returned from the upstream service with no HTTP body, the transcoder converts the gRPC status to a JSON response:

The transcoder checks for the grpc-status-details-bin header, which contains a Base64-encoded google.rpc.Status protobuf message.
If the header exists, the message is decoded and returned as the JSON body.
If the header does not exist, a google.rpc.Status message is generated from the grpc-status and grpc-message headers.

Example:

An upstream service returns the following gRPC headers:

grpc-status: 5
grpc-status-details-bin: CAUaMwoqdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUucnBjLlJlcXVlc3RJbmZvEgUKA3ItMQ

The transcoder converts this to the following HTTP/JSON response:

HTTP/1.1 404 Not Found
content-type: application/json

{
  "code": 5,
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.RequestInfo",
      "requestId": "r-1"
    }
  ]
}

Query parameter handling

By default, the transcoder rejects requests that contain unknown or invalid query parameters. Two fields control this behavior:

Field	When to use
`ignoredQueryParameters`	You know exactly which extra parameters to allow. List them explicitly.
`ignoreUnknownQueryParameters`	You cannot predict which extra parameters the request will contain. Set to `true` to allow all unmapped parameters.

Important

If both ignoredQueryParameters and ignoreUnknownQueryParameters are configured, ignoredQueryParameters is ignored. Use one or the other, not both.

Alibaba Cloud Service Mesh:ASMGrpcJsonTranscoder field reference