Options de démarrage d'Extensible Service Proxy v2

Extensible Service Proxy v2 (ESPv2) est un proxy basé sur Envoy qui permet à Cloud Endpoints de fournir des fonctionnalités de gestion des API. Pour configurer ESPv2, vous pouvez spécifier des options de configuration lors du déploiement du service ESPv2.

Définir des options de configuration

La méthode de définition des options de configuration d'ESPv2 varie en fonction de la plate-forme de déploiement, comme indiqué dans les sections suivantes.

VM Compute Engine

Les options de configuration d'ESPv2 pour Compute Engine sont spécifiés dans la commande docker run. Exemple :

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:2 \
    --service=SERVICE_NAME \
    --rollout_strategy=managed \
    --backend=YOUR_API_CONTAINER_NAME:8080

Dans cet exemple, --service, --rollout_strategy et --backend sont les options de configuration d'ESPv2.

GKE et Kubernetes

Vous pouvez spécifier des options de configuration pour GKE et Kubernetes dans le champ args de votre fichier manifeste de déploiement. Exemple :

containers:
- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:2
  args: [
    "--listener_port=8081",
    "--backend=127.0.0.1:8080",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed"
  ]

Dans cet exemple, --listener_port, --backend, --service et --rollout_strategy sont les options de configuration d'ESPv2.

Cloud Run pour les plates-formes sans serveur

Pour spécifier des options de démarrage de Cloud Run pour les plates-formes sans serveur, utilisez la variable d'environnement ESPv2_ARGS. Cette variable peut être définie dans la commande gcloud run deploy à l'aide de l'option --set-env-vars.

Exemple :

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--enable_debug

Dans cet exemple, --enable_debug correspond à l'option de configuration d'ESPv2.

Consultez la page Cloud Functions pour OpenAPI. Cloud Run pour OpenAPI, ou Cloud Run pour gRPC pour en savoir plus sur la commande gcloud run deploy.

Pour définir plusieurs arguments dans la variable d'environnement ESPv2_ARGS, spécifiez un délimiteur personnalisé et utilisez ce délimiteur pour séparer plusieurs arguments. N'utilisez pas de virgule comme séparateur. Placez le délimiteur personnalisé au début de la variable d'environnement ESPv2_ARGS, en l'entourant de carets (^).

L'exemple suivant utilise ++ comme délimiteur :

gcloud run deploy CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=^++^--cors_preset=basic++--cors_allow_origin=your_host.com

Si l'option que vous définissez contient des virgules, vous devez définir la variable d'environnement ESPv2_ARGS dans le script gcloud_build_image.

Par exemple, pour ajouter l'option --cors_allow_methods=PUT,POST,GET :

  • Téléchargez le script gcloud_build_image.
  • Modifiez le fichier gcloud_build_image comme indiqué ci-dessous :
    cat <<EOF > Dockerfile
      FROM BASE_IMAGE
    
      ENV ENDPOINTS_SERVICE_PATH /etc/endpoints/service.json
      COPY service.json \ENDPOINTS_SERVICE_PATH
    
      ENV ESPv2_ARGS ^++^--cors_preset=basic++--cors_allow_method="GET,PUT,POST"++--cors_allow_credentials
    
      ENTRYPOINT ["/env_start_proxy.py"]
      EOF
  • Exécutez le script gcloud_build_image pour créer l'image.

Options de configuration d'ESPv2

Les options de configuration d'ESPv2 peuvent être regroupées dans les catégories suivantes :

Des exemples génériques supplémentaires et du texte d'aide pour les options d'ESPv2 sont disponibles dans le dépôt GitHub.

Configuration autre que sans serveur

Ces options sont requises pour exécuter ESPv2 sur des plates-formes autres que sans serveur telles que GKE, Compute Engine et Kubernetes. Elles ne peuvent pas être définies lorsqu'elles sont déployées dans Cloud Run pour les plates-formes sans serveur.

``

Option Description
--service Définit le nom du service Endpoints.
--version Définit l'ID de configuration du service Endpoints.
--rollout_strategy Spécifie la stratégie de déploiement de la configuration de service, [fixe|gérée]. La valeur par défaut est fixe.
--listener_port Identifie le port destiné à accepter les connexions en aval. Il prend en charge les protocoles HTTP/1.x, HTTP/2, et des connexions gRPC. La valeur par défaut est 8080.
--backend Spécifie l'adresse du serveur de l'application backend locale. Les schémas valides sont http, https, grpc et grpcs, le cas échéant. Le schéma par défaut est http.

Logging

Utilisez ces options pour configurer ESPv2 afin d'écrire des informations supplémentaires dans le journal Stackdriver.

Option Description
--log_request_headers

Consigne les valeurs des en-têtes de requête spécifiés, séparées par des virgules et sans espaces. Par exemple, définissez cette option comme suit :

--log_request_headers=foo,bar

Si les valeurs des en-têtes "foo" et "bar" sont disponibles dans la requête, le journal Endpoints contient la ligne suivante :

request_headers: foo=foo_value;bar=bar_value

--log_response_headers

Consigne les valeurs des en-têtes de réponse spécifiés, séparées par des virgules et sans espaces. Par exemple, définissez cette option comme suit :

--log_response_headers=baz,bing

Si les valeurs des en-têtes "baz" et "bing" sont disponibles dans la réponse, le journal Endpoints contient la ligne suivante :

response_headers: baz=baz_value;bing=bing_value

--log_jwt_payloads

Consigne les valeurs des champs primitifs de la charge utile JWT spécifiés, séparées par des virgules et sans espaces. Par exemple, définissez cette option comme suit :

--log_jwt_payload=sub,project_id,foo.foo_name

Si les valeurs sont disponibles dans la charge utile JWT, le journal Endpoints contient la ligne suivante :

jwt_payloads: sub=sub_value;project_id=project_id_value; foo.foo_name=foo.foo_name_value

Les valeurs de la charge utile JWT doivent être des champ primitifs (chaîne, entier). Les objets et les tableaux JSON ne sont pas consignés.

--access_log

Si spécifiés, le chemin d'accès au fichier local où les entrées du journal d'accès seront écrites.

--access_log_format

Format de chaîne permettant de spécifier le format du journal d'accès. Si cette option n'est pas définie, la chaîne de format par défaut est utilisée. Pour en savoir plus sur la grammaire du format, consultez la documentation de référence sur les chaînes de format.

Traçage

Utilisez ces options pour configurer les données de traçage d'ESPv2 envoyées à Stackdriver. Ces options ne s'appliquent que lorsque le traçage est activé.

Option Description
--disable_tracing

Désactive le traçage. Par défaut, le traçage est activé.

Quand le traçage est activé, ESPv2 échantillonne chaque seconde un petit nombre de requêtes adressées à l'API, afin d'obtenir des traces qu'il envoie à Stackdriver Trace. Par défaut, une demande sur 1 000 est échantillonnée. Spécifiez l'option --tracing_sample_rate pour modifier le taux d'échantillonnage.

--tracing_project_id

ID de projet Google pour le traçage Stackdriver.

Le traçage est un service payant. Les frais liés au traçage sont facturés sur le projet spécifié.

Par défaut, l'ID de projet du service ESPv2 déployé est facturé.

L'ID du projet est déterminé en appelant le serveur de métadonnées de l'instance Google Cloud au démarrage. Si ESPv2 est déployé en dehors de Google Cloud (à l'aide de --non_gcp ), le traçage sera automatiquement désactivé, sauf si cet indicateur est explicitement définies.

--tracing_sample_rate

Définissez le taux d'échantillonnage des traces sur une valeur comprise entre 0,0 et 1,0. Cette valeur spécifie la fraction des requêtes échantillonnées.

La valeur par défaut est 0,001, ce qui correspond à 1 requête sur 1 000.

--tracing_incoming_context

Cette option spécifie les en-têtes HTTP à vérifier par le contexte de trace, avec des valeurs d'options séparées par des virgules et sans espaces. Notez que l'ordre est important : le contexte de trace est dérivé du premier en-tête correspondant.

Les valeurs possibles sont traceparent, x-cloud-trace-context et grpc-trace-bin.

Si cette option est omise, les en-têtes traceparent et x-cloud-trace-context sont vérifiés (dans l'ordre).

Consultez la page Générer des traces pour votre API pour plus d'informations.

--tracing_outgoing_context

Définit l'en-tête du contexte de trace dans la requête envoyée au service de backend.

Cette option spécifie l'en-tête HTTP à définir, avec des valeurs d'option séparées par des virgules et sans espaces.

Les valeurs possibles sont traceparent, x-cloud-trace-context et grpc-trace-bin.

Si cette option est omise, les en-têtes traceparent et x-cloud-trace-context sont envoyés.

Consultez la page Générer des traces pour votre API pour plus d'informations.

Vérification de l'état

Utilisez ces options pour configurer les vérifications d'état pour ESPv2. La première option permet de configurer un gestionnaire d'état pour répondre aux appels de vérification d'état. Les autres options peuvent être utilisées pour activer la vérification d'état du backend gRPC.

/tbody>
Drapeau Description
-z, --healthz Définissez un point de terminaison de vérification d'état. Par exemple, avec -z healthz, ESPv2 renvoie le code 200 pour le chemin d'accès /healthz.
--health_check_grpc_backend Activez ESPv2 pour vérifier régulièrement le service d'état gRPC d'un backend spécifié par l'option --backend. Le backend doit utiliser le protocole gRPC et implémenter le protocole de vérification d'état gRPC. Le point de terminaison de la vérification d'état activé par l'option --healthz reflète le résultat de la vérification d'état du backend.
--health_check_grpc_backend_service Indiquez le nom du service lorsque vous appelez le protocole de vérification d'état gRPC du backend. La valeur de cette option n'est appliquée que lorsque l'option --health_check_grpc_backend est utilisée. Cette option est facultative. Si vous ne la définissez pas, la valeur par défaut est vide. Un nom de service vide consiste à interroger l'état de fonctionnement global du serveur gRPC.
--health_check_grpc_backend_interval Spécifiez l'intervalle de vérification et le délai avant expiration de la requête lorsque vous appelez le service d'état gRPC du backend. La valeur de cette option n'est appliquée que lorsque l'option --health_check_grpc_backend est utilisée. La valeur par défaut est d'une seconde. Le format accepté est une séquence de nombres décimaux, chacun pouvant comprendre une fraction facultative et un suffixe d'unité, tel que "5s", "100ms" ou "2m". Les unités de temps valides sont "m" pour les minutes, "s" pour les secondes et "ms" pour les millisecondes.

Débogage

Configurez le débogage pour ESPv2 à l'aide des options ci-dessous. Ces options peuvent être utilisées pour configurer un port d'administration Envoy afin de récupérer la configuration et les statistiques, ou pour exécuter Envoy en mode débogage afin d'écrire des informations sur le niveau de débogage dans le journal.

Drapeau Description
--status_port, --admin_port Activer l'administration d'Envoy pour ESPv2 sur ce port. Pour en savoir plus, consultez la documentation de référence sur l'interface d'administration d'Envoy. Le port d'administration est désactivé par défaut.
--enable_debug Activez les journaux de débogage et ajoutez des en-têtes de débogage.

Déploiement autre que Google Cloud

Si ESPv2 est déployé dans un environnement autre que Google Cloud, les options suivantes peuvent être requises.

Option Description
--service_account_key

Spécifie le fichier JSON de clé de compte de service utilisé pour accéder aux services Google. Si cette option est omise, le proxy contacte le serveur de métadonnées Google Cloud pour récupérer un jeton d'accès.

--dns_resolver_addresses Adresses des résolveurs DNS. Chaque adresse doit être au format IP_ADDR ou IP_ADDR:PORT, et être séparée par un point-virgule (;). Pour IP_ADDR, le port DNS 52 par défaut sera utilisé. Par exemple : --dns_resolver_addresses=127.0.0.1;127.0.0.2;127.0.0.3:8000. Si elle n'est pas définie, ESPv2 utilise le résolveur par défaut configuré dans /etc/resolv.conf.
--backend_dns_lookup_family Définissez la famille de résolution DNS pour tous les backends. Les options sont auto, v4only, v6only, v4preferred et all. La valeur par défaut est v4preferred. Notez que auto est une ancienne valeur. Si cette option est définie sur auto, le comportement est équivalent à celui de v6preferred.
--non_gcp Par défaut, le proxy tente de se connecter au serveur de métadonnées Google Cloud. pour obtenir l'emplacement de la VM dès les premières requêtes. Pour ignorer cette étape, définissez cette option sur true.

Tester en local

ESPv2 peut être déployé localement sur votre poste de travail à des fins de test. Consultez la section Exécuter ESP en local ou sur une autre plate-forme pour en savoir plus.

Utilisez ces options avec les options de déploiement autres que Google Cloud pour faciliter le déploiement local et les tests dans l'intégration continue.

Option Description
--service_json_path

Spécifiez un chemin d'accès pour ESPv2 afin de charger la configuration de service de point de terminaison. Avec cette option, ESPv2 utilise une stratégie de déploiement "fixe" et les options suivantes sont ignorées :

  • --service
  • --version
  • --rollout_strategy

Cette option empêche ESPv2 d'utiliser le quota de l'API Service Management.

--enable_backend_address_override

Les adresses de backend peuvent être spécifiées à l'aide de l'option --backend ou du champ backend.rule.address dans la configuration de service. Pour les utilisateurs d'OpenAPI, notez que le champ backend.rule.address est défini par le champ address dans l'extension x-google-backend.

La configuration de service par opération backend.rule.address est généralement spécifiée pour le routage sans serveur. Par défaut, backend.rule.address est prioritaire sur l'option --backend pour chaque opération.

Activez cette option si vous souhaitez que l'option --backend soit prioritaire. Cette fonctionnalité est utile si vous développez sur un poste de travail local. Vous pouvez ensuite utiliser la même configuration de service de production, mais remplacez l'adresse de backend via l'option --backend pour les tests locaux.

Remarque : Seule l'adresse sera ignorée. Tous les autres composants de backend.rule s'appliqueront toujours (délais, authentification backend, traduction de chemin d'accès, etc.).

Extraction d'adresses IP clientes

Utilisez ces options pour configurer l'extraction d'adresses IP client pour ESPv2.

Option Description
--envoy_use_remote_address

Pour en savoir plus sur la configuration d'Envoy HttpConnectionManager, consultez la documentation de référence d'Envoy. Cette option est désactivée par défaut.

--envoy_xff_num_trusted_hops Pour en savoir plus sur la configuration d'Envoy HttpConnectionManager, consultez la documentation de référence d'Envoy. La valeur par défaut est "2".

Compatibilité avec le CORS

Consultez la section Compatibilité avec le CORS pour obtenir une description des options disponibles de compatibilité avec le CORS. Cette section décrit l'utilisation des options de démarrage ESPv2 pour assurer la compatibilité avec CORS.

Pour activer la compatibilité avec CORS dans ESPv2, incluez l'option --cors_preset et définissez-la avec l'une des options suivants :

  • --cors_preset=basic
  • --cors_preset=cors_with_regex

Lorsque vous incluez --cors_preset=basic ou --cors_preset=cors_with_regex, ESPv2 se comporte comme suit :

  • Il suppose que tous les chemins d'accès aux emplacements suivent la même règle CORS.
  • Il répond aux requêtes simples et aux requêtes préliminaires HTTP OPTIONS.
  • Il garde en cache le résultat de la requête préliminaire OPTIONS jusqu'à 20 jours (1 728 000 secondes).
  • Il définit les en-têtes de réponse sur les valeurs suivantes :

    Access-Control-Allow-Origin: *
    Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
    Access-Control-Allow-Headers: DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization
    Access-Control-Expose-Headers: Content-Length,Content-Range
    Access-Control-Max-Age: 1728000

Pour ignorer la valeur par défaut de Access-Control-Allow-Origin, spécifiez l'une des options suivantes :

Option Description
--cors_allow_origin Utilisez cette option avec --cors_preset=basic pour définir Access-Control-Allow-Origin sur une origine spécifique.
Exemple :
--cors_preset=basic
--cors_allow_origin=http://example.com
--cors_allow_origin_regex Utilisez cette option avec --cors_preset=cors_with_regex. Elle permet d'utiliser une expression régulière pour définir Access-Control-Allow-Origin.
Exemple :
--cors_preset=cors_with_regex
--cors_allow_origin_regex=^https?://.+\.example\.com$

L'expression régulière de l'exemple précédent accepte une origine avec http ou https et n'importe quel sous-domaine de example.com.

Lorsque vous définissez cette option dans un fichier de configuration Kubernetes, vous devez ajouter une barre oblique inverse supplémentaire pour échapper les deux instances de \. Par exemple :

"--cors_preset","cors_with_regex",
"--cors_allow_origin_regex","^https?://.+\\.example\\.com$"

Lorsque vous définissez cette option dans le script gcloud_build_image pour Cloud Run, essayez d'éviter d'utiliser des caractères échappés et des barres obliques inverses, car ils peuvent ne pas être transmis correctement du script bash au proxy au démarrage. Utilisez des classes de caractères plutôt que des métaséquences. Par exemple : Original: \d Recommended: [0-9]

Après avoir défini --cors_preset=basic ou --cors_preset=cors_with_regex pour activer le CORS, vous pouvez ignorer les valeurs par défaut des autres en-têtes de réponse en spécifiant une ou plusieurs des options suivantes :

Option Description
--cors_allow_methods Définit Access-Control-Allow-Methods sur les méthodes HTTP spécifiées. Spécifiez les méthodes HTTP sous forme de chaîne ; séparez chaque méthode HTTP par une virgule.
Exemple :
--cors_preset=basic
--cors_allow_methods=GET,POST,PUT,OPTIONS
--cors_allow_headers Définit Access-Control-Allow-Headers sur les en-têtes HTTP spécifiés. Spécifiez les en-têtes HTTP sous forme de chaîne ; séparez chaque en-tête HTTP par une virgule.
Exemple :
--cors_preset=basic
--cors_allow_headers=Origin,Content-Type,Accept
--cors_allow_credentials Il inclut l'en-tête Access-Control-Allow-Credentials de valeur true dans les réponses. Par défaut, l'en-tête Access-Control-Allow-Credentials n'est pas inclus dans les réponses.
Exemple :
--cors_preset=basic
--cors_allow_credentials
--cors_expose_headers Définit Access-Control-Expose-Headers sur les en-têtes spécifiés. Spécifiez les en-têtes pouvant être exposés dans la réponse sous forme de chaîne ; séparez chaque en-tête par une virgule.
Exemple :
--cors_preset=basic
--cors_expose_headers=Content-Length
--cors_max_age Définit Access-Control-Max-Age sur la durée spécifiée. Le format acceptable est une séquence de nombres décimaux, chacun avec une valeur fractionnaire facultative et un suffixe d'unité, tel que "300m", "1.5h" ou "2h45m". Les unités de temps valides sont "m" pour les minutes et "h" pour les heures. La valeur par défaut est "480h" si elle n'est pas définie.
Exemple :
--cors_preset=basic
--cors_max_age=24h

Compatibilité avec TLS

Utilisez ces options pour configurer ESPv2 de manière à utiliser les connexions TLS.

Option Description
--ssl_server_cert_path Chemin d'accès au certificat de serveur du proxy. Une fois configuré, ESPv2 n'accepte que les connexions sécurisées HTTP/1.x et HTTP/2 sur écouteur_port. Nécessite les fichiers de certificat et de clé "server.crt" et "server.key" sur ce chemin d'accès.
--ssl_server_cipher_suites Suites de chiffrement à utiliser pour les connexions en aval, spécifiées sous forme de liste séparée par des virgules. Veuillez consulter la page Configuration de la suite de chiffrement.
--ssl_backend_client_cert_path Chemin d'accès au certificat de client du proxy. Une fois configuré, ESPv2 permet l'authentification mutuelle TLS pour les backends HTTPS. Nécessite les fichiers de certificat et de clé "client.crt" et "client.key" sur ce chemin d'accès.
--ssl_backend_client_root_certs_file Chemin d'accès des certificats racine qu'ESPv2 utilise pour valider le certificat du serveur backend. Si cette option n'est pas spécifiée, ESPv2 utilise "/etc/ssl/certs/ca-certificates.crt" par défaut.
--ssl_backend_client_cipher_suites Suites de chiffrement à utiliser pour les backends HTTPS, spécifiées sous forme de liste séparée par des virgules. Veuillez consulter la page Configuration de la suite de chiffrement.
--ssl_minimum_protocol Version minimale du protocole TLS pour la connexion côté client. Pour en savoir plus, consultez cette page.
--ssl_maximum_protocol Version maximale du protocole TLS pour la connexion côté client. Pour en savoir plus, consultez cette page.
--enable_strict_transport_security Activez le mécanisme HSTS (HTTP Strict Transport Security). L'en-tête de réponse "Strict-Transport-Security" avec la valeur "max-age3325000; includeSubdomains" est ajouté pour toutes les réponses.
--generate_self_signed_cert Générez au départ un certificat et une clé autosignés, puis stockez-les dans "/tmp/ssl/endpoints/server.crt" et "/tmp/ssl/endpoints/server.key". Cette fonctionnalité est utile lorsqu'un certificat autosigné aléatoire est nécessaire pour répondre aux requêtes HTTPS. Le certificat généré porte le nom commun "localhost" et est valide pendant 10 ans.

Délais avant expiration et nouvelles tentatives

Utilisez ces options pour configurer le délai avant expiration de l'appel HTTP distant et les nouvelles tentatives pour ESPv2.

Option Description
--http_request_timeout_s

Définissez le délai avant expiration en secondes pour les requêtes adressées à des services externes, à l'exception de Backend et de Google Service Control. Ceci inclut Google Service Management, un serveur de métadonnées et un serveur Google IAM. Cette valeur doit être supérieure à 0 et la valeur par défaut est de 30 secondes si elle n'est pas définie.

--service_control_network_fail_open

En cas de défaillance du réseau lors de la connexion à Google Service Control, les requêtes seront autorisées si cette option est activée. La valeur par défaut est on.

--service_control_check_timeout_ms Définissez en millisecondes le délai avant expiration de la requête de vérification de contrôle de service. Cette valeur doit être supérieure à 0, et la valeur par défaut est de 1 000 si elle n'est pas définie.
--service_control_report_timeout_ms Définissez en millisecondes le délai avant expiration de la requête de rapport de contrôle de service. Cette valeur doit être supérieure à 0, et la valeur par défaut est de 1 000 si elle n'est pas définie.
--service_control_quota_timeout_ms Définissez en millisecondes le délai avant expiration de la requête de quota de contrôle de service. Cette valeur doit être supérieure à 0, et la valeur par défaut est de 1 000 si elle n'est pas définie.
--service_control_check_retries Définissez les délais avant nouvelle tentative pour la requête de vérification de contrôle de service. Cette valeur doit être supérieure ou égale à 0, et la valeur par défaut est de 3 si elle n'est pas définie.
--service_control_report_retries Définissez les délais avant nouvelle tentative pour la requête de rapport de contrôle de service. Cette valeur doit être supérieure ou égale à 0, et la valeur par défaut est de 5 si elle n'est pas définie.
--service_control_quota_retries Définissez les délais avant nouvelle tentative pour la requête de quota de contrôle de service. Cette valeur doit être supérieure ou égale à 0, et la valeur par défaut est de 1 si elle n'est pas définie.
--backend_retry_ons

Conditions dans lesquelles ESPv2 effectue une nouvelle tentative sur les backends. Vous pouvez spécifier une ou plusieurs conditions retryOn en utilisant une liste séparée par des virgules. La valeur par défaut est reset,connect-failure,refused-stream. Pour désactiver les tentatives, définissez cette option sur vide.

Consultez les liens suivants pour connaître les conditions acceptées :

--backend_retry_num Nombre de tentatives autorisées. Cette valeur doit être supérieure ou égale à 0, et la valeur par défaut est 1.

Transcodage gRPC

Utilisez ces options pour configurer ESPv2 pour le transcodage HTTP/JSON vers gRPC.

Option Description
--transcoding_always_print_primitive_fields

Spécifie s'il faut imprimer des champs primitifs lors du transcodage de gRPC vers JSON. Par défaut, les champs primitifs avec des valeurs par défaut sont omis dans la sortie JSON. Par exemple, un champ "int32" défini sur 0 est omis. La définition de cette option sur true remplace le comportement par défaut et imprime les champs primitifs, quelle que soit leur valeur. Valeur par défaut : false.

--transcoding_always_print_enums_as_ints

Spécifie si les énumérations doivent être imprimées en tant qu'entiers lors du transcodage de gRPC vers JSON. Par défaut, celles-ci sont affichées sous forme de chaînes. Valeur par défaut : false.

--transcoding_stream_newline_delimited

Si la valeur est "true", utilisez un délimiteur de nouvelle ligne pour séparer les messages de streaming de réponse. Si la valeur est "false", tous les messages de streaming de réponse sont transcodés dans un tableau JSON.

--transcoding_case_insensitive_enum_parsing

Normalement, les valeurs enum proto doivent être en majuscules lorsqu'elles sont utilisées dans JSON. Définissez cet indicateur sur "true" si votre requête JSON utilise des valeurs enum qui ne sont pas en majuscules.

--transcoding_preserve_proto_field_names

Spécifie si les noms de champ proto doivent être conservés lors du transcodage grpc-json. Par défaut, protobuf génère les noms de champ JSON à l'aide de l'option json_name, ou selon la notation "lower camel case", dans cet ordre. La définition de cette option conserve les noms des champs d'origine. Valeur par défaut : false.

--transcoding_ignore_query_parameters

Liste des paramètres de requête séparés par une virgule à ignorer lors du mappage des méthodes de transcodage dans le cadre du transcodage de gRPC vers JSON. Par défaut, le filtre du transcodeur ne transcode pas une requête comportant des paramètres de requête inconnus/invalides.

--transcoding_ignore_unknown_query_parameters

Spécifie s'il faut ignorer les paramètres de requête qui ne peuvent pas être mappés à un champ protobuf correspondant lors du transcodage de gRPC vers JSON. À utiliser si vous ne pouvez pas contrôler les paramètres de requête et si vous ne les connaissez pas auparavant. Sinon, utilisez --transcoding_ignore_query_parameters. Valeur par défaut : false.

--transcoding_query_parameters_disable_unescape_plus

Par défaut, les signes plus "+" dans les paramètres de requête sont sans échappement dans l'espace " " lors du transcodage grpc-json afin de pouvoir utiliser HTML 2.0. Si ce n'est pas votre souhait, définissez cette option sur "true" pour désactiver cette fonctionnalité.

Modification des requêtes et des réponses

Utilisez ces options pour configurer ESPv2 de manière à modifier partiellement les requêtes et les réponses.

Drapeau Description
--add_request_header

Ajoutez un en-tête HTTP à la requête avant de l'envoyer au backend en amont. Si l'en-tête est déjà présent dans la requête, sa valeur sera remplacée par la nouvelle.

Il est compatible avec les variables personnalisées Envoy.

Cet argument peut être répété plusieurs fois pour spécifier plusieurs en-têtes. Exemples :
--add_request_header=key1=value1
--add_request_header=key2=value2
.

--append_request_header

Ajoutez un en-tête HTTP à la requête avant de l'envoyer au backend en amont. Si l'en-tête est déjà présent dans la requête, la nouvelle valeur est ajoutée.

Il est compatible avec les variables personnalisées Envoy.

Cet argument peut être répété plusieurs fois pour spécifier plusieurs en-têtes. Exemples :
--append_request_header=key1=value1
--append_request_header=key2=value2
.

--add_response_header

Ajoutez un en-tête HTTP à la réponse avant de l'envoyer au client en aval. Si l'en-tête figure déjà dans la réponse, il sera remplacé par le nouveau.

Il est compatible avec les variables personnalisées Envoy.

Cet argument peut être répété plusieurs fois pour spécifier plusieurs en-têtes. Exemples :
--add_response_header=key1=value1
--add_response_header=key2=value2
.

--append_response_header

Ajoutez un en-tête HTTP à la réponse avant de l'envoyer au client en aval. Si l'en-tête figure déjà dans la réponse, le nouveau sera ajouté.

Il est compatible avec les variables personnalisées Envoy.

Cet argument peut être répété plusieurs fois pour spécifier plusieurs en-têtes. Exemples :
--append_response_header=key1=value1
--append_response_header=key2=value2
.

Options de sécurité

Utilisez ces options pour affiner les requêtes autorisées par ESPv2.

Drapeau Description
--underscores_in_headers

Autorise les noms d'en-tête contenant des traits de soulignement. Valeur par défaut : false.

Le trait de soulignement est autorisé dans les noms d'en-têtes par la norme RFC-7230. Toutefois, ce comportement est mis en œuvre comme mesure de sécurité, car certains systèmes considèrent _ et - comme interchangeables.

--envoy_connection_buffer_limit_bytes

Configurez la quantité maximale de données mises en mémoire tampon pour chaque corps de requête/réponse, en octets. Si ce champ n'est pas défini, la valeur par défaut est déterminée par Envoy. Consultez la page Configuration de l'écouteur d'Envoy.

--disable_normalize_path

Désactivez la normalisation de l'en-tête HTTP path conformément à la norme RFC 3986. Nous vous recommandons de laisser cette option activée si votre backend effectue une normalisation du chemin par défaut.

Le tableau suivant fournit des exemples de requête path que le backend recevra d'ESPv2 en fonction de la configuration de cette option.

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello/../world  | Rejected              | /world             |
        | /%4A             | /%4A                  | /J                 |
        | /%4a             | /%4a                  | /J                 |
        -----------------------------------------------------------------
     

Par défaut, ESPv2 normalise les chemins d'accès. Désactivez la fonctionnalité uniquement si votre trafic est affecté par le comportement.

Remarque : Conformément à la norme RFC 3986, cette option ne permet pas de procéder à l'échappement des barres obliques encodées en pourcentage. Consultez la section sur l'option --disallow_escaped_slashes_in_path pour activer ce comportement non conforme.

Remarque : La normalisation de la casse selon la RFC 3986 n'est pas acceptée, même si cette option est activée.

Pour en savoir plus, consultez la page Comprendre la modélisation des chemins d'accès.

--disable_merge_slashes_in_path

Désactivez la fusion des barres obliques adjacentes dans l'en-tête HTTP path. Nous vous recommandons de laisser cette option activée si votre backend effectue la fusion par défaut.

Le tableau suivant fournit des exemples de requête path que le backend recevra d'ESPv2 en fonction de la configuration de cette option.

        -----------------------------------------------------------------
        | Request Path     | Without Normalization | With Normalization |
        -----------------------------------------------------------------
        | /hello//world    | Rejected              | /hello/world       |
        | /hello///        | Rejected              | /hello             |
        -----------------------------------------------------------------
     

Par défaut, ESPv2 fusionne les barres obliques. Désactivez la fonctionnalité uniquement si votre trafic est affecté par le comportement.

Pour en savoir plus, consultez la page Comprendre la modélisation des chemins d'accès.

--disallow_escaped_slashes_in_path

Interdit les requêtes contenant des barres obliques encodées en pourcentage :

  • %2F ou %2f est traité comme un /
  • %5C ou %5c est traité comme un \

Lorsque l'option est activée, le comportement dépend du protocole utilisé :

  • Pour les backends OpenAPI, les chemins de requête comportant des barres obliques encodées en pourcentage seront automatiquement échappés via une redirection.
  • Pour les backends gRPC, les chemins de requêtes comportant des barres obliques encodées en pourcentage seront refusés (gRPC n'est pas compatible avec les redirections).

Cette option n'est pas conforme à la norme RFC 3986. Elle est donc désactivée par défaut. Si votre backend n'est pas conforme à la norme RFC 3986 et échappe les barres obliques, vous devez activer cette option dans ESPv2. Vous éviterez ainsi les attaques par confusion de chemin pouvant entraîner un défaut d'application des exigences de sécurité.

Pour en savoir plus, consultez la page Comprendre la modélisation des chemins d'accès.

Authentification JWT

Utilisez ces options pour configurer ESPv2 afin d'extraire le JWKS distant avec de nouvelles tentatives.

Drapeau Description
--jwks_fetch_num_retries

Spécifiez le nombre de tentatives dans la stratégie de nouvelle tentative d'extraction du JWKS distant. La valeur par défaut est 0, pas de nouvelle tentative.

--jwks_fetch_retry_back_off_base_interval_ms

Spécifiez la valeur de l'intervalle exponentiel de base entre les tentatives d'extraction du JWKS, en millisecondes. La valeur par défaut est 200 ms, si elle n'est pas définie.

--jwks_fetch_retry_back_off_max_interval_ms

Spécifiez la valeur de l'intervalle exponentiel maximum entre les tentatives d'extraction du JWKS, en millisecondes. La valeur par défaut est 32 s, si elle n'est pas définie.

--jwks_cache_duration_in_s

Spécifiez la durée de vie du cache de la clé publique JWT, en secondes. Si la valeur n'est pas définie, la valeur par défaut est de 5 minutes.

--jwks_async_fetch_fast_listener

Ne s'applique que lorsque l'option --disable_jwks_async_fetch n'est pas définie. Cette option détermine si ESPv2 attendra la récupération initiale jwks avant de lier le port d'écouteur. Si elle est définie sur "false", elle attend. La valeur par défaut est "false".

--jwt_cache_size

Spécifiez le nombre de jetons JWT uniques comme taille maximale du cache JWT. Le cache ne stocke que les jetons validés. Si la valeur est 0, le cache JWT est désactivé. Cet indicateur limite l'utilisation de la mémoire pour le cache JWT. La mémoire utilisée par le cache est d'environ (taille du jeton + 64 octets) par jeton. Si aucune valeur n'est spécifiée, la valeur par défaut est 100 000.

--disable_jwt_audience_service_name_check

Normalement, le champ JWT aud est vérifié par rapport aux audiences spécifiées dans le champ OpenAPI x-google-audiences. Cet indicateur modifie le comportement lorsque le champ x-google-audiences n'est pas spécifié. Lorsque le champ x-google-audiences n'est pas spécifié et que cet indicateur n'est pas utilisé, le nom du service est utilisé pour vérifier le champ aud du jeton JWT. Si cette option est utilisée, le champ JWT aud ne sera pas coché.

Étape suivante

Apprenez-en davantage sur les points suivants :