Premiers pas avec Cloud Endpoints gRPC pour le groupe d'instances géré avec ESPv2

Ce tutoriel explique comment déployer un exemple de service gRPC simple avec Extensible Service Proxy V2 (ESPv2) dans un groupe d'instances géré.

Ce tutoriel utilise la version Python bookstore-grpc échantillon. 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. Copiez et configurez les fichiers à partir du bookstore-grpc échantillon. Consultez la section Configurer Endpoints.
  3. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
  4. Déployez l'API et ESPv2 sur le backend du groupe d'instances géré. Consultez la section Déployer le backend de l'API.
  5. Envoyez une requête à l'API. Consultez la section Envoyer des requêtes à l'API.
  6. 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 :

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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  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 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 qui s'ouvre, sélectionnez 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.

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.

Configurer Endpoints

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

Pour configurer Endpoints :

  1. Créez un fichier 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 d'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 contenant 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éployer le fichier proto descriptor et le fichier de configuration à l'aide de la commande 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

Endpoints et ESP requièrent au minimum l'activation des services Google suivants :
Nom 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 Endpoints, 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 groupe d'instances géré et de l'exécution du code de backend de l'API et d'ESPv2 dans un conteneur Docker.

Créer un modèle d'instance

Créez un modèle que vous utiliserez pour créer un groupe d'instances de VM. Chaque instance créée à partir du modèle lance ESPv2 et un serveur d'application backend.

  1. Dans Google Cloud Console, accédez à la page Modèles d'instances.

    Accéder à la page Modèles d'instances

  2. Cliquez sur Create instance template (Créer un modèle d'instance).

  3. Dans le champ Nom, saisissez load-balancing-espv2-template.

  4. Sous Configuration de la machine, définissez le type de machine sur e2-micro.

  5. Sous Disque de démarrage, définissez l'image sur Container Optimized OS stable version.

  6. Sous Pare-feu, sélectionnez Autoriser le trafic HTTP.

  7. Cliquez sur Gestion, sécurité, disques, réseau et location unique pour afficher les paramètres avancés.

  8. Cliquez sur l'onglet Gestion. Sous Automatisation, saisissez le script de démarrage ci-dessous. N'oubliez pas de mettre à jour ENDPOINTS_SERVICE_NAME.

    sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=bookstore \
  --net=esp_net \
  gcr.io/endpointsv2/python-grpc-bookstore-server:1
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=grpc://bookstore:8000

    Le script récupère, installe et lance le serveur d'applications Echo et le serveur proxy ESPv2 au démarrage de l'instance.

  9. Cliquez sur Create (Créer).

Attendez que le modèle ait été créé avant de continuer.

Créer un groupe d'instances géré régional

Pour exécuter l'application, utilisez le modèle d'instance pour créer un groupe d'instances géré régional. Procédez comme suit :

  1. Dans Google Cloud Console, accédez à la page Groupes d'instances.

    Accéder à la page "Groupes d'instances"

  2. Cliquez sur Créer un groupe d'instances.

  3. Dans le champ Nom, saisissez load-balancing-espv2-group.

  4. Sous Emplacement, sélectionnez Plusieurs zones.

  5. Sous Région, sélectionnez us-central1.

  6. Cliquez sur le menu déroulant Configurer les zones pour afficher les zones. Sélectionnez les zones suivantes :

    • us-central1-b
    • us-central1-c
    • us-central1-f

  7. Pour le paramètre Modèle d'instance, sélectionnez load-balancing-espv2-template.

  8. Sous Mode autoscaling, sélectionnez Ne pas procéder à un autoscaling.

  9. Définissez Nombre d'instances sur 3.

  10. Sous Redistribution des instances, sélectionnez Activée.

  11. Sous Autoréparation et Vérification de l'état, sélectionnez Aucune vérification d'état.

  12. Cliquez sur Créer. Cela vous redirige vers la page Groupes d'instances.

Créer un équilibreur de charge

Cette section explique les étapes requises pour créer un équilibreur de charge régional qui dirige le trafic TCP vers votre groupe d'instances.

  1. Dans la console Google Cloud, accédez à la page Créer un équilibreur de charge.

    Accéder à la page Créer un équilibreur de charge

  2. Sous TCP Load Balancing (Équilibrage de charge TCP), cliquez sur Start configuration (Démarrer la configuration).

  3. Dans la section Web ou interne uniquement, sélectionnez D'Internet vers mes VM.

  4. Pour le paramètre Plusieurs régions ou région unique, sélectionnez Région unique seulement.

  5. Sous Type de backend, sélectionnez Service de backend.

  6. Cliquez sur Continuer.

  7. Dans le champ Nom, saisissez espv2-load-balancer.

  8. Sous Configuration du backend, sélectionnez la région us-central1.

  9. Sélectionnez le groupe d'instances load-balancing-espv2-group.

  10. Sous Vérification d'état, créez une vérification d'état.

    • Sous Nom, saisissez espv2-load-balancer-check.
    • Confirmez que le protocole est TCP et que le port est défini sur 80.

  11. Sous Configuration de l'interface, saisissez le numéro de port 80.

  12. Sous Vérifier et finaliser, vérifiez les valeurs suivantes :

    • Le groupe d'instances est défini sur load-balancing-espv2-group.
    • La région est définie sur us-central1.
    • Le protocole est défini sur TCP.
    • Le IP:Port est défini sur EPHEMERAL:80.

  13. Une fois l'équilibreur de charge créé, recherchez l'adresse IP sur la page Équilibreur de charge.

    Accéder à la page Équilibreur de charge

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

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.

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. Assurez-vous que la CLI gcloud (gcloud) est autorisée à accéder à vos données et services sur Google Cloud :

    gcloud auth login

  2. Saisissez la commande suivante pour afficher les ID de vos projets Google Cloud :

    gcloud projects list

  3. En utilisant l'ID de projet applicable récupéré à l'étape précédente, définissez le projet Google Cloud par défaut sur celui hébergeant votre application :

    gcloud config set project [YOUR_PROJECT_ID]

  4. Obtenez le nom de tous les services gérés du projet Google Cloud :

    gcloud endpoints services list

  5. Supprimez le service de Service Management. Remplacez SERVICE_NAME par le nom du service que vous souhaitez supprimer.

    gcloud endpoints services delete SERVICE_NAME

    L'exécution de gcloud endpoints services delete ne supprime pas immédiatement le service géré. Il est désactivé pendant 30 jours, ce qui vous laisse le temps de le restaurer au besoin. Passé ce délai, Service Management supprime définitivement le service.

  6. Accédez à la page Équilibreur de charge.

    Accéder à la page Équilibreur de charge

    Supprimez l'équilibreur de charge espv2-load-balancer avec la vérification d'état espv2-load-balancer-check.

  7. Accédez à la page Groupes d'instances.

    Accéder à la page "Groupes d'instances"

    Supprimer load-balancing-espv2-group

  8. Accédez à la page Modèle d'instances.

    Accéder à la page Modèles d'instances

    Supprimer load-balancing-espv2-template

Étape suivante