Options de démarrage Extensible Service Proxy

OpenAPI | gRPC

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 le proxy ESP de sorte 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.x.¹
`-P HTTP2_PORT`	`--http2_port HTTP2_PORT`	Définit les ports exposés par ESP pour les connexions HTTP/2.¹
`-S SSL_PORT`	`--ssl_port SSL_PORT`	Définit les ports exposés par ESP pour les connexions HTTPS.¹
`-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`.

¹ 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 Manage data in Docker (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 :

Déployer ESP et le backend d'une API sur Google Cloud
Exécuter ESP en local ou sur une autre plate-forme
Le script start_esp sur GitHub