Cette page a été traduite par l'API Cloud Translation.
Switch to English

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 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 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 :

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

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 GCP au démarrage. Si ESPv2 est déployé en dehors de GCP (à l'aide de l'option --non_gcp), le traçage est automatiquement désactivé, à moins que cette option ne soit définie explicitement.

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

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

Si cette option est omise, l'en-tête traceparent est vérifié.

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, l'en-tête traceparent est envoyé.

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

Débogage

Utilisez ces options pour configurer les vérifications d'état et le débogage pour ESPv2. Ces options peuvent être utilisées pour configurer un gestionnaire d'état pour répondre aux appels de vérification d'état, un port d'administration Envoy pour extraire la configuration et les statistiques, ou pour exécuter Envoy en mode débogage pour écrire des informations de débogage dans le journal.

Option 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.
--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 sur des plates-formes autres que GCP

Si ESPv2 est déployé dans un environnement autre que Google Cloud Platform (GCP), 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 cet élément n'est pas spécifié, le proxy contacte le serveur de métadonnées GCP 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 et v6only. La valeur par défaut est auto.
--non_gcp Par défaut, le proxy tente de se connecter au serveur de métadonnées GCP pour obtenir l'emplacement de la VM dans les premières requêtes. Pour ignorer cette étape, définissez cette option sur true.

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
    

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"

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_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_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 du backend local. Non valide pour les backends à distance.
--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.

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

Options de sécurité

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

Option Description
--underscores_in_headers

Les noms des en-têtes contenant des traits de soulignement doivent être transmis. Valeur par défaut : false.

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

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.

Étape suivante

Apprenez-en davantage sur les points suivants :