Déployer le backend de l'API

OpenAPI | gRPC

Cette page explique comment déployer le code backend de votre API et Extensible Service Proxy (ESP) sur Google Kubernetes Engine, Compute Engine et l'environnement flexible App Engine.

Même si les étapes de déploiement varient en fonction de la plate-forme qui héberge l'API, vous devez toujours indiquer à ESP le nom de service et une option lui permettant d'utiliser la dernière configuration de service Cloud Endpoints déployée. À l'aide de ces informations, ESP peut obtenir la configuration Endpoints de l'API et servir de proxy pour les requêtes et les réponses, afin que Cloud Endpoints puisse gérer l'API.

Remarque : Extensible Service Proxy V2 (ESPv2) peut également être déployé sur GKE et Kubernetes. ESPv2 n'est pas compatible avec l'environnement flexible App Engine.

Prérequis

Pour commencer, cette page suppose que vous avez :

• créé un projet Google Cloud ;
• Configuré Endpoints ;
• déployé la configuration Endpoints.

Préparer le déploiement

App Engine

Avec une petite étape de configuration en plus (décrite dans les étapes suivantes), déployer votre API de sorte qu'elle soit gérée par Cloud Endpoints équivaut à déployer une application dans l'environnement flexible App Engine. Consultez la documentation d'App Engine pour effectuer les opérations suivantes :

• Organiser les fichiers de configuration.
• Créer le fichier de configuration app.yaml
• Si votre application est basée sur des microservices, consultez la documentation sur le déploiement de plusieurs applications de service pour plus d'informations sur la configuration des fichiers app.yaml pour chaque service.

Déployez l'API sur App Engine à l'aide de la commande gcloud app deploy. Cette commande crée automatiquement une image de conteneur à l'aide du service Container Builder, puis déploie cette image dans l'environnement flexible App Engine.

Avant de procéder au déploiement :

• Le propriétaire du projet Google Cloud doit créer l'application App Engine.
• Votre compte utilisateur doit inclure les privilèges requis.

Compute Engine

Pour que Cloud Endpoints gère l'API, vous devez installer et configurer ESP, ainsi que le code du serveur backend pour l'API. Vous devez installer Docker sur votre instance de VM Compute Engine pour pouvoir exécuter l'image ESP Docker, disponible gratuitement dans Container Registry.

Avant de procéder au déploiement :

La procédure ci-dessous décrit dans les grandes lignes les étapes à suivre avant de pouvoir déployer l'API et ESP sur Compute Engine. En règle générale, il suffit d'effectuer toutes les étapes que vous suivez en temps normal pour exécuter le code du serveur backend sur Compute Engine.

1. Créez, configurez et démarrez votre instance de VM. Consultez la documentation de Compute Engine.
2. Installez Docker Enterprise Edition (EE) ou Docker Community Edition (CE) sur votre instance de VM. Consultez la section Installer Docker.
3. Créez un conteneur Docker pour le code du serveur backend. Consultez la documentation Cloud Build.
4. Transférez le conteneur dans Container Registry ou dans un autre registre.
5. Vérifiez que vous pouvez bien :
   • Vous connecter à l'instance de VM.
   • Exécuter l'image Docker pour démarrer le serveur backend sur l'instance de VM. Consultez le document de référence sur l'exécution de Docker.
   • envoyer des requêtes à l'API.

GKE

Lorsque vous créez un cluster dans la console Google Cloud, les champs d'application OAuth accordés au compte de service du cluster incluent par défaut les champs d'application requis par Endpoints:

• Service Control : activé
• Service Management : lecture seule

Lorsque vous créez un cluster à l'aide de la commande gcloud container clusters create ou d'un fichier de configuration tiers, veillez à spécifier les champs d'application suivants :

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

Pour plus d'informations, consultez la section Que sont les champs d'application d'accès ?

Avant de procéder au déploiement :

En ajoutant une petite section au fichier manifeste de déploiement, vous pouvez exécuter l'image ESP Docker sur les clusters de conteneurs à l'aide de votre application conteneurisée. La procédure ci-dessous décrit dans les grandes lignes les étapes à suivre pour pouvoir déployer l'API et ESP sur GKE. En règle générale, il suffit d'effectuer toutes les étapes que vous suivez en temps normal pour exécuter le code du serveur backend sur GKE.

1. Déployez votre application conteneurisée sur les clusters de conteneurs. Les étapes générales décrites dans la documentation de GKE sont les suivantes :
   1. Empaquetez l'application dans une image Docker.
   2. Importez l'image dans un registre.
   3. Créez un cluster de conteneurs.
   4. Déployez l'application sur le cluster.
   5. Exposez l'application sur Internet.
2. Vérifiez que vous pouvez bien :
   • Démarrer le serveur de l'API.
   • Envoyer des requêtes à l'API.

Déployer l'API et ESP

App Engine

Pour déployer les API et ESP sur App Engine, procédez comme suit :

1. Obtenez le nom de service de l'API. Il s'agit du nom que vous avez spécifié dans le champ host du document OpenAPI.
2. Modifiez le fichier app.yaml et ajoutez une section appelée endpoints_api_service contenant le nom du service. Vous pouvez utiliser le fichier app.yaml du tutoriel comme modèle :
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Remplacez ENDPOINTS-SERVICE-NAME par le nom de service de l'API. Exemple :

   endpoints_api_service:
     name: example-project-12345.appspot.com
     rollout_strategy: managed
     

   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.

   Si l'application est basée sur des microservices, vous devez inclure la section endpoints_api_service dans chaque fichier app.yaml.

3. Enregistrez le ou les fichiers app.yaml.
4. Déployez le code backend et ESP sur App Engine comme suit :

   gcloud app deploy
   

Étant donné que vous avez ajouté la section endpoints_api_service au fichier app.yaml, la commande gcloud app deploy déploie et configure ESP dans un conteneur séparé de votre environnement flexible App Engine. L'intégralité du trafic des requêtes est acheminée via ESP, qui sert de proxy pour les requêtes et les réponses envoyées et reçues par le conteneur qui exécute le code du serveur backend.

Pour indiquer à ESP d'utiliser un ID de configuration spécifique, procédez comme suit:

1. Dans la section endpoints_api_service du fichier app.yaml, ajoutez le champ config_id et définissez-le avec un ID de configuration spécifique.
2. Supprimez l'option rollout_strategy: managed ou définissez rollout_strategy sur fixed. L'option fixed indique à ESP d'utiliser la configuration de service que vous avez spécifiée dans config_id.
3. Redéployez l'API et le proxy ESP : gcloud app deploy

Nous vous recommandons de ne pas laisser ESP configuré de manière à utiliser un ID de configuration spécifique de manière prolongée, car si vous déployez une configuration de service mise à jour, vous devez redémarrer ESP pour utiliser la nouvelle configuration.

Pour supprimer l'ID de configuration spécifique :

1. Supprimez l'option config_id du fichier app.yaml.
2. Ajoutez l'option rollout_strategy: managed.
3. Exécutez la commande gcloud app deploy.

Lorsque vous utilisez l'option rollout_strategy: managed, n'incluez pas config_id: YOUR_SERVICE_CONFIG_ID dans le fichier app.yaml. Si vous le faites, gcloud app deploy échoue avec l'erreur suivante :

config_id is forbidden when rollout_strategy is set to "managed".

Lorsque vous déployez l'API dans l'environnement flexible App Engine pour la première fois, un délai peut s'écouler lors de la configuration de votre machine virtuelle (VM) et d'une autre infrastructure. Pour plus d'informations, consultez la section Garantir la réussite d'un déploiement dans la documentation App Engine.

Compute Engine

Pour déployer l'API et ESP sur Compute Engine avec Docker, procédez comme suit :

1. Connectez-vous à l'instance de VM. Remplacez INSTANCE_NAME par le nom de l'instance de VM :

   gcloud compute ssh INSTANCE_NAME

2. Créez votre propre réseau de conteneurs appelé esp_net :

   sudo docker network create --driver bridge esp_net

3. Exécutez une instance de l'image du code de serveur backend et connectez-la au réseau de conteneurs esp_net:

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • Remplacez YOUR_API_CONTAINER_NAME par le nom du conteneur.
   • Remplacez YOUR_PROJECT_ID par l'ID du projet Google Cloud que vous avez utilisé lors du stockage de l'image.
   • Remplacez YOUR_IMAGE par le nom de l'image.
4. Obtenez le nom de service de l'API. Il s'agit du nom que vous avez spécifié dans le champ host du document OpenAPI.
5. Exécutez une instance de l'image ESP Docker :

   sudo docker run \
       --name=esp \
       --detach \
       --publish=80:8080 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --backend=YOUR_API_CONTAINER_NAME:8080

   • Remplacez SERVICE_NAME par le nom du service.
   • Remplacez YOUR_API_CONTAINER_NAME par le nom du conteneur de l'API.

   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.

Pour indiquer à ESP d'utiliser un ID de configuration spécifique, procédez comme suit:

1. Incluez l'option --version et définissez-la sur un ID de configuration spécifique.
2. Supprimez l'option --rollout_strategy=managed ou définissez --rollout_strategy sur fixed. L'option fixed indique à ESP d'utiliser la configuration de service que vous avez spécifiée dans --version.
3. Exécutez à nouveau la commande docker run.

Si vous spécifiez à la fois l'option --rollout_strategy=managed et l'option --version, ESP démarre avec la configuration que vous avez spécifiée dans --version, mais il s'exécute ensuite en mode géré et obtient la dernière configuration.

Nous vous recommandons de ne pas laisser ESP configuré de manière à utiliser un ID de configuration spécifique de manière prolongée, car si vous déployez une configuration de service mise à jour, vous devez redémarrer ESP pour utiliser la nouvelle configuration.

Pour supprimer l'ID de configuration spécifique :

1. Dans les indicateurs ESP pour docker run, supprimez l'option --version.
2. Ajoutez l'option --rollout_strategy=managed.
3. Exécutez la commande docker run pour redémarrer ESP.

Consultez la section Options de démarrage du proxy Extensible Service Proxy pour obtenir la liste complète des options que vous pouvez spécifier au démarrage d'ESP.

GKE

Pour déployer ESP vers GKE :

1. Obtenez le nom de service de l'API (il s'agit du nom que vous avez spécifié dans le champ host du document OpenAPI).
2. Ouvrez le fichier manifeste de déploiement (appelé deployment.yaml), puis ajoutez les éléments suivants à la section "Conteneurs" :

   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"
     ]

   Remplacez SERVICE_NAME par le nom de service de l'API.

   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.

3. Démarrez le service Kubernetes à l'aide de la commande  :

   kubectl create -f deployment.yaml

Pour indiquer à ESP d'utiliser un ID de configuration spécifique, procédez comme suit:

1. Dans le fichier manifeste de déploiement, ajoutez l'option --version et définissez-la sur un ID de configuration spécifique.
2. Supprimez l'option --rollout_strategy=managed ou définissez --rollout_strategy sur fixed. L'option fixed indique à ESP d'utiliser la configuration de service que vous avez spécifiée dans --version.
3. Démarrez le service Kubernetes : kubectl create -f deployment.yaml.

Si vous spécifiez à la fois l'option --rollout_strategy=managed et l'option --version, ESP démarre avec la configuration que vous avez spécifiée dans --version, mais il s'exécute ensuite en mode géré et obtient la dernière configuration.

Nous vous recommandons de ne pas laisser ESP configuré de manière à utiliser un ID de configuration spécifique de manière prolongée, car si vous déployez une configuration de service mise à jour, vous devez redémarrer ESP pour utiliser la nouvelle configuration.

Pour supprimer l'ID de configuration spécifique :

1. Dans le fichier manifeste de déploiement, supprimez l'option --version.
2. Ajoutez --rollout_strategy=managed.
3. Démarrez le service Kubernetes : kubectl create -f deployment.yaml .

Consultez la section Options de démarrage du proxy Extensible Service Proxy pour obtenir la liste complète des options que vous pouvez spécifier au démarrage d'ESP.

Suivre l'activité de l'API

Après avoir déployé ESP et le backend de l'API, vous pouvez utiliser des outils tels que curl ou Postman pour envoyer des requêtes à l'API. Si vous ne recevez pas de réponse positive, consultez la page Dépanner des erreurs de réponse.

Après avoir envoyé quelques requêtes, vous pouvez :

• Affichez les graphiques d'activité de votre API sur Endpoints > Services.
  

  Accédez à la page Services Endpoints

  
  Il peut s'écouler quelques instants avant que la requête ne soit reflétée dans les graphiques.

• Consulter les journaux de requêtes de votre API sur la page Cloud Logging.
  

  Accéder à la page "Explorateur de journaux"

Étapes suivantes

• Résoudre des problèmes de déploiement de l'environnement flexible App Engine.
• Résoudre les problèmes liés à Cloud Endpoints sur Compute Engine.
• Dépannage des ordinateurs d'extrémité dans Google Kubernetes Engine .