Description of ASMGrpcJsonTranscoder fields - Alibaba Cloud Service Mesh

ASMGrpcJsonTranscoder es una Custom Resource Definition (CRD) de Alibaba Cloud Service Mesh (ASM) que transcodifica entre HTTP/JSON y gRPC/Protobuf. Despliegue esta CRD para exponer servicios gRPC como endpoints HTTP RESTful. De este modo, los clientes HTTP pueden invocarlos sin necesidad de un cliente gRPC dedicado.

Configuración completa

A continuación se muestra el YAML con todos los campos configurables en un recurso ASMGrpcJsonTranscoder:

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.

Campos

Campo	Tipo	Obligatorio	Descripción
workloadSelector	map<string, string>	Sí	Etiquetas que seleccionan los pods donde surte efecto esta configuración. El alcance de las etiquetas se limita al namespace del recurso. Para más información, consulte Workload Selector.
isGateway	bool	No	Indica si la configuración se aplica a un gateway. Valor predeterminado: `false`.
portNumber	int	Sí	Puerto del servicio que se va a transcodificar. Si `isGateway` es `true`, este valor especifica el puerto del servicio (por ejemplo, `8080`) que ejecuta la transcodificación en el gateway.
services	string[]	Sí	Servicios gRPC declarados en el archivo proto, con el formato `{nombre del paquete}.{nombre del servicio}`. Consulte la sección Formato de los servicios más adelante.
protoDescriptorBin	string	Sí	Contenido codificado en Base64 del archivo del conjunto de descriptores proto. Consulte la sección Generar un descriptor proto más adelante.
transcodeFirst	bool	No	Indica si las solicitudes HTTP se transcodifican antes de cualquier otro procesamiento. Valor predeterminado: `false`. Consulte la sección Orden de transcodificación más adelante.
convertGrpcStatus	bool	No	Indica si el estado de error de gRPC se convierte en un cuerpo de respuesta JSON. Valor predeterminado: `false`. Consulte la sección Conversión de estados gRPC más adelante.
ignoredQueryParameters	[]string	No	Parámetros de consulta que se omiten durante el mapeo del método de transcodificación. Utilice esta opción cuando conozca exactamente qué parámetros ignorar. Consulte la sección Manejo de parámetros de consulta más adelante.
ignoreUnknownQueryParameters	bool	No	Indica si se ignoran todos los parámetros de consulta que no se pueden mapear a campos de protobuf. Úsela cuando no pueda predecir qué parámetros de consulta contendrá la solicitud. Consulte la sección Manejo de parámetros de consulta más adelante.

Detalles de los campos

Formato de los servicios

Especifique cada servicio gRPC con el formato {nombre del paquete}.{nombre del servicio}. Este formato debe coincidir con las definiciones de su archivo proto:

services:
  - 'helloworld.Greeter'

Generar un descriptor proto

El campo protoDescriptorBin requiere un conjunto de descriptores proto codificado en Base64. Genérelo de la siguiente manera:

Clone el repositorio googleapis, ya que contiene las anotaciones proto obligatorias:

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

Ejecute protoc para generar el conjunto de descriptores:

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

Codifique el archivo resultante en Base64 y utilice ese valor para protoDescriptorBin:
```
   base64 -w 0 proto.pb
```

Orden de transcodificación

Cuando transcodeFirst se establece en true, las solicitudes HTTP entrantes se transcodifican a gRPC antes de que se procese cualquier otro filtro. Esto afecta funciones de control de tráfico basadas en solicitudes, como la autorización externa.

Por ejemplo, cuando una solicitud pasa por un servicio personalizado de autorización externa:

transcodeFirst: true -- El servicio de autorización recibe una solicitud gRPC.
transcodeFirst: false (valor predeterminado) -- El servicio de autorización recibe una solicitud HTTP.

Conversión de estados gRPC

Si convertGrpcStatus se establece en true y el servicio ascendente devuelve un error gRPC sin cuerpo HTTP, el transcodificador convierte el estado gRPC en una respuesta JSON:

El transcodificador busca el encabezado grpc-status-details-bin, que contiene un mensaje protobuf google.rpc.Status codificado en Base64.
Si el encabezado existe, decodifica el mensaje y lo devuelve como cuerpo JSON.
Si el encabezado no existe, genera un mensaje google.rpc.Status a partir de los encabezados grpc-status y grpc-message.

Ejemplo:

Un servicio ascendente devuelve los siguientes encabezados gRPC:

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

El transcodificador convierte esto en la siguiente respuesta HTTP/JSON:

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

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

Manejo de parámetros de consulta

De forma predeterminada, el transcodificador rechaza las solicitudes que contienen parámetros de consulta desconocidos o no válidos. Dos campos controlan este comportamiento:

Campo	Cuándo usarlo
`ignoredQueryParameters`	Cuando conoce exactamente qué parámetros adicionales permitir. Enliste cada uno de forma explícita.
`ignoreUnknownQueryParameters`	Cuando no puede predecir qué parámetros adicionales contendrá la solicitud. Establézcalo en `true` para permitir todos los parámetros no mapeados.

Importante

Si configura tanto ignoredQueryParameters como ignoreUnknownQueryParameters, el sistema ignora ignoredQueryParameters. Utilice solo uno de los dos.

Alibaba Cloud Service Mesh:ASMGrpcJsonTranscoder field reference