Options de démarrage Extensible Service Proxy

Extensible Service Proxy (ESP) est un proxy basé sur NGINX qui permet à Cloud Endpoints de fournir des fonctionnalités de gestion des API. Pour configurer ESP, vous spécifiez des options au moment du démarrage de son conteneur Docker. Lorsque le conteneur ESP démarre, il exécute un script appelé start_esp, qui écrit le fichier de configuration NGINX à l'aide des options que vous avez spécifiées, puis lance ESP.

Les options de démarrage d'ESP sont à spécifier dans la commande docker run, comme dans l'exemple suivant :

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

Si vous déployez ESP sur Kubernetes, spécifiez les options de démarrage dans le champ args du fichier manifeste de déploiement, comme dans l'exemple suivant :

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

Le tableau suivant décrit les options de démarrage d'ESP.

Option courte Option longue Description
-s SERVICE_NAME --service SERVICE_NAME Définit le nom du service Endpoints.
-R ROLLOUT_STRATEGY --rollout_strategy ROLLOUT_STRATEGY

Disponible dans la version ESP 1.7.0 et ultérieure. Indiquez managed ou fixed. L'option --rollout_strategy=managed configure ESP pour qu'il utilise la dernière configuration de service déployée. Si cette option est spécifiée, jusqu'à 5 minutes après le déploiement d'une nouvelle configuration de service, ESP détecte la modification et commence à l'utiliser automatiquement. Nous vous recommandons de spécifier cette option plutôt qu'un ID de configuration spécifique à utiliser par ESP. Vous n'avez pas besoin de spécifier l'option --version lorsque vous définissez --rollout_strategy sur managed.
-v CONFIG_ID --version CONFIG_ID Définit l'ID de configuration du service que doit utiliser ESP. Pour obtenir les informations nécessaires à la définition de cette option, consultez la page Obtenir le nom du service et l'ID de configuration. Lorsque vous spécifiez --rollout_strategy=fixed ou que vous n'indiquez pas l'option --rollout_strategy, vous devez inclure l'option --version et spécifier un ID de configuration. Dans ce cas, chaque fois que vous déployez une nouvelle configuration Endpoints, vous devez redémarrer ESP avec le nouvel ID de configuration.
-p HTTP1_PORT --http_port HTTP1_PORT Définit les ports exposés par ESP pour les connexions HTTP/1.x1.
-P HTTP2_PORT --http2_port HTTP2_PORT Définit les ports exposés par ESP pour les connexions HTTP/21.
-S SSL_PORT --ssl_port SSL_PORT Définit les ports exposés par ESP pour les connexions HTTPS1.
-a BACKEND --backend BACKEND Définit l'adresse du serveur backend de l'application HTTP/1.x. La valeur par défaut de l'adresse du backend est http://127.0.0.1:8081.
Vous pouvez spécifier un préfixe de protocole, par exemple :
--backend=https://127.0.0.1:8000
Si vous ne spécifiez pas de préfixe de protocole, la valeur par défaut est http.
Si le serveur backend est exécuté sur Compute Engine dans un conteneur, vous pouvez spécifier le nom du conteneur et le port, par exemple :
--backend=my-api-container:8000
Pour spécifier que le backend accepte le trafic gRPC, ajoutez le préfixe grpc://. Par exemple :
--backend=grpc://127.0.0.1:8000
Si votre serveur backend est exécuté sur Compute Engine dans un conteneur et qu'il accepte le trafic gRPC, vous pouvez spécifier le nom du conteneur et le port, par exemple :
--backend=grpc://my-api-container:8000
-N STATUS_PORT --status_port STATUS_PORT Définit le port d'état (par défaut : 8090).
non applicable --disable_cloud_trace_auto_sampling Par défaut, l'échantillonnage par ESP d'une requête sur 1 000 ou d'une requête toutes les 10 secondes est activé avec Cloud Trace. Définissez cette option pour désactiver ce type d'échantillonnage automatique. Cloud Trace peut toujours être activé à partir des en-têtes HTTP de requête avec le contexte de trace, quelle que soit la valeur de cette option. Consultez la section Traçage de votre API pour plus d'informations.
-n NGINX_CONFIG --nginx_config NGINX_CONFIG Définit l'emplacement du fichier de configuration NGINX personnalisé. Si vous spécifiez cette option, ESP récupère le fichier de configuration spécifié, puis lance immédiatement NGINX avec ce fichier personnalisé. Pour en savoir plus, consultez la page Utiliser une configuration nginx personnalisée pour GKE.
-k SERVICE_ACCOUNT_KEY --service_account_key SERVICE_ACCOUNT_KEY Définit le fichier JSON contenant les identifiants du compte de service. Si celui-ci est fourni, ESP utilise le compte de service pour générer un jeton d'accès permettant d'appeler les API Service Infrastructure. Vous ne devez spécifier cette option que si ESP s'exécute sur des plates-formes autres que Google Cloud, telles que votre ordinateur local, Kubernetes ou un autre fournisseur cloud. Pour en savoir plus, consultez la section Créer un compte de service.
-z HEALTHZ_PATH --healthz HEALTHZ_PATH Définissez un point de terminaison de vérification d'état sur les mêmes ports que l'application backend. Par exemple, -z healthz crée le code de retour ESP 200 pour l'emplacement /healthz, au lieu de transférer la requête au backend. Par défaut : non utilisé.
non applicable --dns DNS_RESOLVER Spécifiez un résolveur DNS. Par exemple, --dns 169.254.169.254 utilise le serveur de métadonnées GCP en tant que résolveur DNS. S'il n'est pas spécifié, la valeur par défaut est 8.8.8.8.

1 Ces ports sont facultatifs et doivent être distincts les uns des autres. Si vous ne spécifiez aucune option de port, ESP accepte les connexions HTTP/1.x sur le port 8080. Pour les connexions HTTPS, ESP s'attend à ce que les secrets TLS soient situés dans /etc/nginx/ssl/nginx.crt et /etc/nginx/ssl/nginx.key.

Exemples d'appels de ligne de commande

Les exemples suivants montrent comment utiliser certains des arguments de ligne de commande :

Pour démarrer ESP afin qu'il traite les requêtes entrant sur les ports HTTP/1.x 80 et HTTPS 443 et qu'il envoie les requêtes au backend de l'API à 127.0.0.1:8000 :

sudo docker run \
    --detach \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1
     --service=echo-api.endpoints.example-project-12345.cloud.goog \
        --rollout_strategy=managed \
        --http_port=80 \
        --ssl_port=443 \
        --backend=127.0.0.1:8000

Pour démarrer ESP avec une configuration NGINX personnalisée à l'aide du fichier d'identifiants du compte de service, afin de récupérer la configuration du service et de vous connecter à Service Control :

sudo docker run \
    --detach \
    --volume=$HOME/Downloads:/esp \
    DOCKER_ARGUMENTS \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=echo-api.endpoints.example-project-12345.cloud.goog \
    --rollout_strategy=managed \
    --service_account_key=/esp/serviceaccount.json \
    --nginx_config=/esp/nginx.conf

Notez que vous devez utiliser les options Docker --volume ou --mount pour installer le fichier JSON contenant la clé privée du compte de service et le fichier de configuration NGINX personnalisé en tant que volumes dans le conteneur Docker d'ESP. L'exemple ci-dessus mappe le répertoire $HOME/Downloads de l'ordinateur local au répertoire esp du conteneur. Lorsque vous enregistrez le fichier de clé privée du compte de service, il est généralement téléchargé dans le répertoire Downloads. Vous pouvez copier le fichier de clé privée dans un autre répertoire si vous le souhaitez. Pour en savoir plus, consultez la page Gérer les données dans Docker.

Ajouter la compatibilité du CORS à ESP

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 ESP compatibles avec le CORS.

Pour activer la compatibilité du CORS dans ESP, incluez l'option --cors_preset et définissez-la sur basic ou cors_with_regex. Lorsque vous incluez --cors_preset=basic ou --cors_preset=cors_with_regex, cela entraîne les réactions suivantes pour ESP :

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

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 Inclut l'en-tête Access-Control-Allow-Credentials avec la 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

Si les options de démarrage CORS ESP ne répondent pas aux besoins de votre application, vous pouvez créer un fichier nginx.conf personnalisé avec la compatibilité CORS requise par votre application. Pour plus d'informations, consultez la page Créer un fichier nginx.conf personnalisé compatible avec le CORS.

Étapes suivantes

Apprenez-en davantage sur les points suivants :