Description of ASMGrpcJsonTranscoder fields - Alibaba Cloud Service Mesh

ASMGrpcJsonTranscoder est une définition de ressource personnalisée (CRD) dans Alibaba Cloud Service Mesh (ASM) qui assure la transcodification entre HTTP/JSON et gRPC/Protobuf. Déployez cette CRD pour exposer les services gRPC sous forme d'endpoints HTTP RESTful, permettant ainsi aux clients HTTP de les appeler sans client gRPC dédié.

Configuration complète

Le fichier YAML suivant présente l'ensemble des champs configurables d'une ressource 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.

Champs

Champ	Type	Obligatoire	Description
workloadSelector	map<string, string>	Oui	Libellés permettant de sélectionner les pods sur lesquels cette configuration s'applique. La portée des libellés est limitée au namespace de la ressource. Pour plus d'informations, consultez la section Workload Selector.
isGateway	bool	Non	Indique si la configuration doit s'appliquer à une passerelle. Valeur par défaut : `false`.
portNumber	int	Oui	Port du service à transcoder. Si `isGateway` est défini sur `true`, ce champ spécifie le port du service (par exemple `8080`) utilisé pour la transcodification sur la passerelle.
services	string[]	Oui	Services gRPC déclarés dans le fichier proto, au format `{nom du package}.{nom du service}`. Consultez la section Format des services ci-dessous.
protoDescriptorBin	string	Oui	Contenu encodé en Base64 du fichier descriptor set proto. Consultez la section Générer un descripteur proto ci-dessous.
transcodeFirst	bool	Non	Indique si les requêtes HTTP doivent être transcodées avant tout autre traitement. Valeur par défaut : `false`. Consultez la section Ordre de transcodification ci-dessous.
convertGrpcStatus	bool	Non	Indique si les statuts d'erreur gRPC doivent être convertis en corps de réponse JSON. Valeur par défaut : `false`. Consultez la section Conversion des statuts gRPC ci-dessous.
ignoredQueryParameters	[]string	Non	Paramètres de requête à ignorer lors du mappage des méthodes de transcodification. Utilisez cette option lorsque vous connaissez exactement les paramètres à ignorer. Consultez la section Gestion des paramètres de requête ci-dessous.
ignoreUnknownQueryParameters	bool	Non	Indique si tous les paramètres de requête qui ne peuvent pas être mappés aux champs protobuf doivent être ignorés. Utilisez cette option lorsque vous ne pouvez pas prédire quels paramètres de requête la demande contiendra. Consultez la section Gestion des paramètres de requête ci-dessous.

Détails des champs

Format des services

Spécifiez chaque service gRPC au format {nom du package}.{nom du service}, en respectant les définitions de votre fichier proto :

services:
  - 'helloworld.Greeter'

Générer un descripteur proto

Le champ protoDescriptorBin nécessite un descriptor set proto encodé en Base64. Générez-en un comme suit :

Clonez le dépôt googleapis, qui contient les annotations proto requises :

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

Exécutez protoc pour générer le descriptor set :

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

Encodez le fichier de sortie en Base64 et utilisez le résultat comme valeur pour protoDescriptorBin :
```
   base64 -w 0 proto.pb
```

Ordre de transcodification

Lorsque transcodeFirst est défini sur true, les requêtes HTTP entrantes sont transcodées en gRPC avant tout autre traitement de filtre. Cela affecte les fonctionnalités de contrôle du trafic basées sur les requêtes, telles que l'autorisation externe.

Par exemple, lorsqu'une requête traverse un service d'autorisation externe personnalisé :

transcodeFirst: true : le service d'autorisation reçoit une requête gRPC.
transcodeFirst: false (valeur par défaut) : le service d'autorisation reçoit une requête HTTP.

Conversion des statuts gRPC

Lorsque convertGrpcStatus est défini sur true et qu'une erreur gRPC est renvoyée par le service amont sans corps HTTP, le transcodeur convertit le statut gRPC en réponse JSON :

Le transcodeur vérifie la présence de l'en-tête grpc-status-details-bin, qui contient un message protobuf google.rpc.Status encodé en Base64.
Si l'en-tête existe, le message est décodé et renvoyé sous forme de corps JSON.
Si l'en-tête n'existe pas, un message google.rpc.Status est généré à partir des en-têtes grpc-status et grpc-message.

Exemple :

Un service amont renvoie les en-têtes gRPC suivants :

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

Le transcodeur convertit ces informations en la réponse HTTP/JSON suivante :

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

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

Gestion des paramètres de requête

Par défaut, le transcodeur rejette les requêtes contenant des paramètres de requête inconnus ou invalides. Deux champs contrôlent ce comportement :

Champ	Cas d'utilisation
`ignoredQueryParameters`	Vous connaissez exactement les paramètres supplémentaires à autoriser. Liste explicite requise.
`ignoreUnknownQueryParameters`	Vous ne pouvez pas prédire quels paramètres supplémentaires la requête contiendra. Définissez la valeur sur `true` pour autoriser tous les paramètres non mappés.

Important

Si ignoredQueryParameters et ignoreUnknownQueryParameters sont tous deux configurés, ignoredQueryParameters est ignoré. Utilisez l'un ou l'autre, mais pas les deux simultanément.

Alibaba Cloud Service Mesh:ASMGrpcJsonTranscoder field reference