Premiers pas avec Endpoints pour Compute Engine avec ESP

---

OpenAPI | gRPC

Cette page vous explique comment déployer un exemple de service gRPC simple avec Extensible Service Proxy (ESP) dans un conteneur Docker sur Compute Engine.

Cette page utilise la version Python de l'exemple bookstore-grpc. Consultez la section Étapes suivantes pour obtenir des exemples gRPC dans d'autres langages.

Pour obtenir une présentation de Cloud Endpoints, consultez les pages À propos de Cloud Endpoints et Présentation de l'architecture Cloud Endpoints.

Objectifs

Tout au long du tutoriel, reportez-vous au récapitulatif des étapes présenté ci-dessous. Toutes les tâches sont nécessaires pour envoyer des requêtes à l'API.

1. Configurez un projet Google Cloud et téléchargez le logiciel requis. Consultez la section Avant de commencer.
2. Créez une instance de VM Compute Engine. Consultez la section Créer une instance Compute Engine.
3. Copiez et configurez les fichiers figurant dans l'exemple bookstore-grpc. Consultez la section Configurer Endpoints.
4. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
5. Déployez l'API et ESP sur la VM Compute Engine. Consultez la section Déployer le backend de l'API.
6. Envoyez une requête à l'API. Consultez la section Envoyer des requêtes à l'API.
7. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Nettoyer.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Compute Engine
• Points de terminaison

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

4. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

5. Vérifiez que la facturation est activée pour votre projet Google Cloud.

6. Notez l'ID de projet, car il sera nécessaire ultérieurement.
7. Installez et initialisez Google Cloud CLI.
8. Mettez à jour la gcloud CLI et installez les composants Cloud Endpoints:

   gcloud components update

9. Assurez-vous que la Google Cloud CLI (gcloud) est autorisée à accéder à vos données et services sur Google Cloud:

   gcloud auth login

   Dans le nouvel onglet de navigateur, choisissez un compte.
10. Définissez le projet par défaut sur votre ID de projet.

    gcloud config set project YOUR_PROJECT_ID

    Remplacez YOUR_PROJECT_ID par l'ID du projet. Si vous avez d'autres projets Google Cloud et que vous souhaitez les gérer à l'aide de gcloud, consultez la page Gérer les configurations de gcloud CLI.

11. Suivez les étapes figurant sur la page gRPC Python Quickstart pour installer gRPC et les outils gRPC.

Créer une instance Compute Engine

Pour créer une instance Compute Engine, procédez comme suit :

1. Accédez à la page Créer une instance dans la console Google Cloud.

   Accéder à la page Créer une instance

2. Dans la section Pare-feu, sélectionnez Autoriser le trafic HTTP et Autoriser le trafic HTTPS.
3. Pour créer la VM, cliquez sur Créer.



Patientez un court instant le temps que l'instance démarre. Une fois l'instance prête, elle est répertoriée sur la page Instances de VM avec une icône d'état verte.

4. Assurez-vous que vous pouvez vous connecter à votre instance de machine virtuelle.
   1. Dans la liste des instances de machine virtuelle, cliquez sur SSH sur la ligne de l'instance à laquelle vous souhaitez vous connecter.
   2. Vous pouvez maintenant utiliser le terminal pour exécuter des commandes Linux sur votre instance Debian.
   3. Tapez exit pour vous déconnecter de l'instance.
5. Notez le nom, la zone et l'adresse IP externe de l'instance, car vous en aurez besoin ultérieurement.

Configurer Endpoints

Clonez l'exemple de dépôt bookstore-grpc depuis GitHub.

Pour configurer Endpoints :

1. Créez un fichier de descripteur protobuf autonome à partir de votre fichier de service .proto :
   1. Enregistrez une copie du fichier bookstore.proto à partir de l'exemple de dépôt. Ce fichier définit l'API du service Bookstore.
   2. Créez le répertoire suivant : mkdir generated_pb2.
   3. Créez le fichier descripteur api_descriptor.pb à l'aide du compilateur de tampons de protocole protoc. Exécutez la commande suivante dans le répertoire où vous avez enregistré bookstore.proto :

      python -m grpc_tools.protoc \
          --include_imports \
          --include_source_info \
          --proto_path=. \
          --descriptor_set_out=api_descriptor.pb \
          --python_out=generated_pb2 \
          --grpc_python_out=generated_pb2 \
          bookstore.proto
      

      Dans la commande ci-dessus, --proto_path est défini sur le répertoire de travail actuel. Dans votre environnement de compilation gRPC, si vous utilisez un autre répertoire pour les fichiers d'entrée .proto, modifiez --proto_path pour que le compilateur recherche le répertoire dans lequel vous avez enregistré votre fichier bookstore.proto.

2. Créez un fichier YAML de configuration de l'API gRPC :
   1. Enregistrez une copie du fichier api_config.yaml. Ce fichier définit la configuration d'API gRPC pour le service Bookstore.
   2. Remplacez MY_PROJECT_ID dans votre fichier api_config.yaml par votre ID de projet Google Cloud. Exemple :

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Notez que la valeur du champ apis.name dans ce fichier correspond exactement au nom d'API complet du fichier .proto. À défaut, le déploiement échouera. Le service Bookstore est défini dans bookstore.proto dans le package endpoints.examples.bookstore. Son nom d'API complet est endpoints.examples.bookstore.Bookstore, tel qu'il apparaît dans le fichier api_config.yaml

      apis:
        - name: endpoints.examples.bookstore.Bookstore
      

Pour en savoir plus, consultez la page Configurer Endpoints.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, exécutez la commande gcloud endpoints services deploy. Cette commande crée un service géré à l'aide de Service Management.

1. Vérifiez que vous êtes bien dans le répertoire où se trouvent les fichiers api_descriptor.pb et api_config.yaml.
2. Vérifiez que le projet par défaut actuellement utilisé par l'outil de ligne de commande gcloud est bien le projet Google Cloud vers lequel vous souhaitez déployer la configuration Endpoints. Validez l'ID de projet renvoyé par la commande suivante, afin de vous assurer que le service est créé dans le bon projet.

   gcloud config list project
   

   Si vous devez modifier le projet par défaut, exécutez la commande suivante :

   gcloud config set project YOUR_PROJECT_ID
   

3. Déployez le fichier proto descriptor et le fichier de configuration à l'aide de Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Une fois le déploiement terminé, un message semblable au suivant s'affiche :

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID correspond à l'ID unique de configuration du service Endpoints créé par le déploiement. Exemple :

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   Dans l'exemple précédent, 2017-02-13r0 correspond à l'ID de configuration du service et bookstore.endpoints.example-project.cloud.goog au nom du service. L'ID de configuration du service se compose d'un horodatage suivi d'un numéro de révision. Si vous déployez à nouveau la configuration Endpoints le même jour, le numéro de révision est incrémenté dans l'ID de configuration du service.

Vérifier les services requis

Cloud Endpoints et ESP nécessitent au minimum l'activation des services Google suivants:

Nom	Title (Titre)
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control
endpoints.googleapis.com	Google Cloud Endpoints

Dans la plupart des cas, la commande gcloud endpoints services deploy permet d'activer ces services requis. Toutefois, bien que la commande gcloud ait abouti, elle n'active pas les services requis dans les cas suivants :

• Vous avez utilisé une application tierce telle que Terraform et vous n'incluez pas ces services.

• Vous avez déployé la configuration Endpoints dans un projet Google Cloud existant dans lequel ces services étaient explicitement désactivés.

Utilisez la commande suivante pour vérifier que les services nécessaires sont activés :

gcloud services list

Si les services requis ne sont pas répertoriés, activez-les :

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Activez également votre service Endpoints :

gcloud services enable ENDPOINTS_SERVICE_NAME

Pour déterminer la valeur de ENDPOINTS_SERVICE_NAME, vous pouvez effectuer l'une des opérations suivantes :

• Après avoir déployé la configuration des points de terminaison, accédez à la page Points de terminaison de la console Cloud. La liste des valeurs ENDPOINTS_SERVICE_NAME possibles s'affiche dans la colonne Nom du service.

• Pour OpenAPI, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ host de votre spécification OpenAPI. Pour gRPC, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ name de votre configuration Endpoints gRPC.

Pour en savoir plus sur les commandes gcloud, consultez la page Services gcloud.

Si vous recevez un message d'erreur, consultez la page Dépannage du déploiement de la configuration Cloud Endpoints.

Pour en savoir plus, consultez la page Déployer la configuration Endpoints.

Déployer le backend de l'API

Vous avez déployé la configuration de l'API sur Service Management, mais vous n'avez pas encore déployé le code qui diffuse le backend de l'API. Cette section vous guide tout au long de la configuration de Docker sur votre instance de VM et de l'exécution du code de backend de l'API et d'ESP dans un conteneur Docker.

Installer Docker sur l'instance de VM

Pour installer Docker sur l'instance de VM :

1. Définissez la zone du projet en exécutant la commande suivante :

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Remplacez YOUR_INSTANCE_ZONE par la zone où l'instance est en cours d'exécution.

2. Connectez-vous à l'instance à l'aide de la commande suivante :

   gcloud compute ssh INSTANCE_NAME
   

   Remplacez INSTANCE_NAME par le nom de votre instance de VM.

3. Consultez la documentation de Docker pour configurer le dépôt Docker. Veillez à suivre les étapes correspondant à la version et à l'architecture de votre instance de VM :
   • Jessie ou plus récent
   • x86_64/amd64

Exécuter l'exemple d'API et ESP dans un conteneur Docker

Pour exécuter l'exemple de service gRPC avec ESP dans un conteneur Docker afin que les clients puissent l'utiliser :

1. Sur l'instance de VM, créez votre propre réseau de conteneurs nommé esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Exécutez l'exemple de serveur Bookstore qui diffuse l'exemple d'API :

   sudo docker run \
       --detach \
       --name=bookstore \
       --net=esp_net \
       gcr.io/endpointsv2/python-grpc-bookstore-server:1
   

3. Exécutez le conteneur Docker ESP pré-empaqueté. Dans les options de démarrage ESP, remplacez SERVICE_NAME par le nom du service. Il s'agit du nom que vous avez configuré dans le champ name du fichier api_config.yaml. Par exemple : bookstore.endpoints.example-project-12345.cloud.goog

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:1 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --http2_port=9000 \
       --backend=grpc://bookstore:8000
   

   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 en savoir plus sur les arguments ESP, consultez la page Options de démarrage ESP.

Si vous avez activé le transcodage, veillez à configurer un port pour le trafic SSL ou HTTP1.1.

Si vous recevez un message d'erreur, consultez la page Résoudre les problèmes liés à Cloud Endpoints sur Compute Engine.

Envoyer une requête à l'API

Si vous envoyez la requête à partir de l'instance dans laquelle les conteneurs Docker sont en cours d'exécution, vous pouvez remplacer $SERVER_IP par localhost. Sinon, remplacez $SERVER_IP par l'adresse IP externe de l'instance.

Vous pouvez trouver l'adresse IP externe en exécutant la commande suivante :

gcloud compute instances list

Pour envoyer des requêtes à l'exemple d'API, vous pouvez utiliser un exemple de client gRPC écrit en Python.

1. Clonez le dépôt Git dans lequel le code client gRPC est hébergé :

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
      

2. Modifiez votre répertoire de travail :

   cd python-docs-samples/endpoints/bookstore-grpc/
     

3. Installez les dépendances :

   pip install virtualenv
   virtualenv env
   source env/bin/activate
   python -m pip install -r requirements.txt
   

4. Envoyez une requête à l'exemple d'API :

   python bookstore_client.py --host SERVER_IP --port 80
   

   • Examinez les graphiques d'activité de l'API dans la page 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.

   • Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux.
     

     Accéder à la page "Explorateur de journaux"

Si vous ne recevez pas de réponse positive, consultez la page Résoudre des problèmes concernant les erreurs de réponse.

Vous venez de déployer et de tester une API dans Endpoints.

Remarque : Si vous souhaitez nous donner votre avis sur ce tutoriel, n'hésitez pas à nous faire part de vos commentaires au bas de cette page. Ils nous sont utiles pour améliorer nos tutoriels.
Si vous rencontrez une erreur, rejoignez le groupe Google google-cloud-endpoints et faites-nous part de ce qui n'a pas fonctionné. Ce groupe reçoit les réponses d'autres utilisateurs Endpoints et d'ingénieurs Google qui supervisent le groupe.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

1. Supprimez l'API :

   gcloud endpoints services delete SERVICE_NAME
   

   Remplacez SERVICE_NAME par le nom de votre service.

2. Dans la console Google Cloud, accédez à la page Instances de VM.

   Accéder à la page Instances de VM

3. Cochez la case correspondant à instance que vous souhaitez supprimer.
4. Pour supprimer l'instance, cliquez sur Autres actions , cliquez sur Supprimer, puis suivez les instructions.

Étapes suivantes

• Découvrez comment configurer votre propre API gRPC pour Endpoints.
• Consultez l'exemple Bookstore sur GitHub plus en détail. Le client et le serveur sont disponibles dans les langages Python et Java.
• L'exemple getting-started-grpc est disponible sur GitHub dans les langages suivants :
  • Java
  • Python
  • Ruby
  • Go
  • Node.js