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 Cloud Functions pour OpenAPI, Cloud Run pour OpenAPI ou Cloud Run pour gRPC pour plus d'informations 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
gcloud_build_imagecomme 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_imagepour créer l'image.
Options de configuration d'ESPv2
Les options de configuration d'ESPv2 peuvent être regroupées dans les catégories suivantes :
- Configuration autre que sans serveur
- Logging
- Traçage
- Vérification de l'état
- Débogage
- Tester en local
- Déploiement en dehors de Google Cloud
- Extraction d'adresses IP clientes
- Compatibilité avec le CORS
- Compatibilité avec TLS
- Délais avant expiration et nouvelles tentatives
- Transcodage gRPC
- Modification des requêtes et des réponses
- Options de sécurité
- Authentification JWT
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 de service 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 connexions HTTP/1.x, HTTP/2 et 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. |
Journalisation
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 :
Si les valeurs des en-têtes "foo" et "bar" sont disponibles dans la requête, le journal Endpoints contient:
|
--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 :
Si les valeurs des en-têtes "baz" et "bing" sont disponibles dans la réponse, le journal des points de terminaison contient ce qui suit:
|
--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 :
Si les valeurs sont disponibles dans la charge utile JWT, le journal Endpoints contient la ligne suivante :
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_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 d'instance Google Cloud au démarrage.
Si ESPv2 est déployé en dehors de Google Cloud (à l'aide de l'indicateur |
--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 équivaut à 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 Si cette option est omise, les en-têtes 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 Si cette option est omise, les en-têtes 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 au niveau du débogage et ajoutez des en-têtes de débogage. |
Déploiement en dehors de 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 l'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 vous définissez l'indicateur sur auto, un comportement équivalent à 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 hors 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 :
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
La configuration de service par opération
Activez cette option si vous souhaitez que l'option
Remarque : Seule l'adresse sera ignorée.
Tous les autres composants de |
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
OPTIONSjusqu'à 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_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
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 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 \ dans la chaîne. Exemple:
"--cors_preset","cors_with_regex",
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 : |
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_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_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_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_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
|
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 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 nouveau délimiteur de ligne pour séparer les messages diffusés en continu de réponse. Si la valeur est "false", tous les messages de réponse en streaming sont transcodés dans un tableau JSON. |
--transcoding_case_insensitive_enum_parsing
|
Normalement, les valeurs d'énumération proto doivent être en majuscules lorsqu'elles sont utilisées au format JSON. Définissez cet indicateur sur "true" si votre requête JSON utilise des valeurs d'énumération non 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_query_parameters_disable_unescape_plus
|
Par défaut, les signes plus |
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 : |
--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 : |
--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 : |
--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 : |
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 |
--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
Le tableau suivant fournit des exemples de requête
-----------------------------------------------------------------
| 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 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
Le tableau suivant fournit des exemples de requête
-----------------------------------------------------------------
| 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 :
Lorsque l'option est activée, le comportement dépend du protocole utilisé :
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 du cache de la clé publique JWT, en secondes. Si elle n'est pas configurée, la valeur par défaut est de 5 minutes. |
--jwks_async_fetch_fast_listener
|
S'applique uniquement lorsque l'option |
--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é. Cette option limite l'utilisation de la mémoire pour le cache JWT. La mémoire cache utilisée est d'environ (taille de jeton + 64 octets) par jeton. Si aucune valeur n'est spécifiée, la valeur par défaut est 100000. |
--disable_jwt_audience_service_name_check
|
Généralement, le champ JWT |
Étapes suivantes
Apprenez-en davantage sur les points suivants :