Options de démarrage d'Extensible Service Proxy v2

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

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

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.

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

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.

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.

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 l'option --non_gcp), le traçage est automatiquement désactivé, à moins que cette option ne soit définie explicitement.

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.

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.

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.

Spécifie le fichier JSON de clé de compte de service utilisé pour accéder aux services Google. Si cet élément n'est pas spécifié, le proxy contacte le serveur de métadonnées Google Cloud pour récupérer un jeton d'accès.

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.

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.).

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.

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 :

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]

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.

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.

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 :

• x-envoy-retry-on
• x-envoy-retry-grpc-on

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.

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.

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

Normalement, les valeurs d'énumération proto doivent être en majuscules lorsqu'elles sont utilisées dans JSON. Définissez cette option sur "true" si votre requête JSON utilise des valeurs d'énumération non en majuscules.

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.

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.

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.

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é.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

Normalement, le champ aud du jeton JWT est comparé aux audiences spécifiées dans le champ x-google-audiences d'OpenAPI. 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 aud du JWT ne sera pas vérifié.