ASMGrpcJsonTranscoder CRD field reference - Alibaba Cloud Service Mesh

ASMGrpcJsonTranscoder is a custom resource (CR) used for transcoding between HTTP/JSON and gRPC/Protobuf. This topic describes the fields of ASMGrpcJsonTranscoder.

Field description

Field	Type	Required	Description
workloadSelector	map<string, string>	Yes	Labels that select the pods where transcoding takes effect. The label scope is limited to the namespace where the ASMGrpcJsonTranscoder resource resides. For more information, see Workload Selector.
isGateway	bool	No	Whether to apply transcoding at the gateway. Default: `false`.
portNumber	int	Yes	The corresponding service port. When `isGateway` is `true`, this specifies the service port (for example, `8080`) that performs transcoding on the gateway.
services	string[]	Yes	gRPC service names declared in the proto file, in `{package name}.{service name}` format. See the services field example section below.
protoDescriptorBin	string	Yes	Base64-encoded content of the proto descriptor file. The value of this field must be Base64-encoded.
transcodeFirst	bool	No	Whether to transcode the HTTP request before other processing in the filter chain. Default: `false`. This may affect the request-based traffic control features. When `true`, if the request sent to custom external authorization services is transcoded first, the service receives a gRPC request. Otherwise, it receives an HTTP request.
convertGrpcStatus	bool	No	Whether to convert `grpc-status` headers to a JSON response body. Default: `false`. See the gRPC status conversion section below for details.
ignoredQueryParameters	\[\]string	No	Query parameters to skip during proto field mapping. By default, the transcoder does not transcode requests that contain unknown or invalid query parameters. Parameters listed here are ignored during mapping, allowing the request to be transcoded.
ignoreUnknownQueryParameters	bool	No	Whether to ignore all query parameters that cannot be mapped to proto fields. Default: `false`. Use this when you cannot predict which query parameters clients will send. Otherwise, use `ignoredQueryParameters` to list specific parameters. Important When both `ignoredQueryParameters` and `ignoreUnknownQueryParameters` are set, `ignoredQueryParameters` has no effect.

services field example

Specify each gRPC service as {package name}.{service name}:

services:
  - 'helloworld.Greeter'

gRPC status conversion

When convertGrpcStatus is true and a gRPC error is returned without an HTTP response body, the transcoder converts the error to a JSON response as follows:

If the grpc-status-details-bin header exists, the transcoder decodes the Base64-encoded google.rpc.Status protobuf message and returns it as the JSON body.
If the header does not exist, the transcoder constructs a google.rpc.Status message from the grpc-status and grpc-message headers.

Example

The upstream service returns the following gRPC headers:

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

The grpc-status-details-bin header contains a Base64-encoded google.rpc.Status protobuf message. The transcoder converts this to the following HTTP response:

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

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

Alibaba Cloud Service Mesh:ASMGrpcJsonTranscoder field reference

Field description

services field example

gRPC status conversion

Related topics