Premiers pas avec Endpoints pour GKE avec ESP

OpenAPI | gRPC

Ce tutoriel explique comment déployer un exemple de service gRPC simple avec Extensible Service Proxy (ESP) sur Google Kubernetes Engine (GKE). Il utilise la version Python de l'exemple bookstore-grpc. Consultez la section Étapes suivantes pour obtenir des exemples gRPC dans d'autres langages.

Le tutoriel utilise des images de conteneur prédéfinies du code d'exemple et d'ESP, qui sont stockées dans Artifact Registry. Si vous n'êtes pas encore familiarisé avec les conteneurs, consultez les sections suivantes pour plus d'informations :

• Déployer une application Web en conteneur
• Images de conteneur Kubernetes

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 figurant dans l'exemple bookstore-grpc. 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. Créez un backend pour diffuser et déployer l'API. Consultez la section Déployer le backend de l'API.
5. Obtenez l'adresse IP externe du service. Consultez la section Obtenir l'adresse IP externe du service.
6. Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
7. Pour éviter que des frais ne soient facturés sur votre compte Google Cloud , Consultez la section Effectuer un nettoyage.

Coûts

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

• GKE
• Endpoints

Vous pouvez obtenir 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 sans frais.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Notez l'ID du projet Google Cloud , car vous en aurez besoin ultérieurement.
2. Installez et initialisez Google Cloud CLI.
3. Mettez à jour gcloud CLI et installez les composants Endpoints.

   gcloud components update

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

   gcloud auth login

   Un nouvel onglet de navigateur vous invite à choisir un compte.
5. 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.

6. Installez kubectl :

   gcloud components install kubectl

7. Obtenez de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application. Les identifiants utilisateur sont nécessaires pour autoriser kubectl.

   gcloud auth application-default login

   Dans le nouvel onglet de navigateur, choisissez un compte.
8. Suivez les étapes figurant sur la page gRPC Python Quickstart pour installer gRPC et les outils gRPC.

Configurer Endpoints

L'exemple bookstore-grpc contient les fichiers que vous devez copier localement puis configurer.

1. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
   2. Create the following directory: mkdir generated_pb2
   3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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

      In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

2. Create a gRPC API configuration YAML file:
   1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
   2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:

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

      Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.

      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. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.

   gcloud config list project
   

   If you need to change the default project, run the following command:

   gcloud config set project YOUR_PROJECT_ID
   

3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

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

   CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

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

   In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

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

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 projetGoogle 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

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 Endpoints 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 service dans Service Management, mais vous n'avez pas encore déployé le code qui diffuse le backend de l'API. Cette section vous guide dans la création d'un cluster GKE pour héberger le backend de l'API et dans le déploiement de l'API.

Créer un cluster de conteneur

Pour créer un cluster de conteneur pour notre exemple :

1. Dans la console Google Cloud , accédez à la page "Clusters Kubernetes".
   

   Accéder à la page des clusters Kubernetes

2. Cliquez sur Créer un cluster.
3. Acceptez les paramètres par défaut et cliquez sur Créer. Notez le nom du cluster et la zone, car ils sont nécessaires ultérieurement dans ce tutoriel.

Authentifier kubectl sur le cluster de conteneurs

Pour utiliser kubectl afin de créer et gérer des ressources de cluster, vous devez obtenir les identifiants du cluster et les mettre à la disposition de kubectl. Pour ce faire, exécutez la commande suivante, en remplaçant NAME par votre nouveau nom de cluster et ZONE par sa zone de cluster.

gcloud container clusters get-credentials NAME --zone ZONE

Vérifier les autorisations requises

ESP et ESPv2 appellent les services Google qui utilisent IAM pour vérifier si l'identité appelante dispose des autorisations suffisantes pour accéder aux ressources IAM utilisées. L'identité appelante est le compte de service associé qui déploie ESP et ESPv2.

Lorsqu'il est déployé dans un pod GKE, le compte de service associé est le compte de service de nœud. Il s'agit généralement du compte de service Compute Engine par défaut. Veuillez suivre cette recommandation d'autorisation pour choisir un compte de service de nœud approprié.

Si Workload Identity est utilisé, il est possible d'utiliser un compte de service distinct autre que le compte de service de nœud pour communiquer avec les services Google. Vous pouvez créer un compte de service Kubernetes pour que le pod exécute ESP et ESPv2, créer un compte de service Google et associer le compte de service Kubernetes au compte de service Google.

Pour associer un compte de service Kubernetes à un compte de service Google, suivez ces étapes. Ce compte de service Google est le compte de service associé.

Si le compte de service associé est le compte de service Compute Engine par défaut du projet et que la configuration du service de point de terminaison est déployée dans le même projet, le compte de service doit disposer des autorisations suffisantes pour accéder aux ressources IAM. L'étape de configuration des rôles IAM peut être ignorée. Sinon, les rôles IAM suivants doivent être ajoutés au compte de service associé.

Ajoutez les rôles IAM requis :

Cette section décrit les ressources IAM utilisées par ESP et ESPv2, ainsi que les rôles IAM requis pour que le compte de service associé puisse accéder à ces ressources.

Configuration du service de point de terminaison

ESP et ESPv2 appellent Service Control, qui utilise la configuration du service de point de terminaison. Celle-ci est une ressource IAM. ESP et ESPv2 ont besoin du rôle Contrôleur du service pour y accéder.

Le rôle IAM s'applique à la configuration du service de point de terminaison, et non au projet. Un projet peut posséder plusieurs configurations de service de point de terminaison.

Utilisez la commande gcloud suivante pour ajouter le rôle au compte de service associé pour la configuration du service de point de terminaison.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Où
* SERVICE_NAME est le nom du service de point de terminaison ;
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com est le compte de service associé.

Cloud Trace

ESP et ESPv2 appellent le service Cloud Trace pour exporter Trace vers un projet. Ce projet est appelé projet de traçage. Dans ESP, le projet de traçage et le projet propriétaire de la configuration du service de point de terminaison sont identiques. Dans ESPv2, le projet de traçage peut être spécifié par l'option --tracing_project_id, et est défini par défaut sur le projet de déploiement.

ESP et ESPv2 nécessitent le rôle Agent Cloud Trace pour activer Cloud Trace.

Exécutez la commande gcloud suivante pour ajouter le rôle au compte de service associé :

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Où
* TRACING_PROJECT_ID est l'ID du projet de traçage ;
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.comest le compte de service associé. Pour en savoir plus, consultez Que sont les rôles et les autorisations ?

Déployer les exemples d'API et d'ESP sur le cluster

Pour déployer l'exemple de service gRPC sur le cluster afin que les clients puissent l'utiliser :

1. Enregistrez et ouvrez pour éditer une copie du fichier manifeste de déploiement grpc-bookstore.yaml.
2. Remplacez SERVICE_NAME par le nom de votre service Endpoints. Il s'agit du nom que vous avez configuré dans le champ name du fichier api_config.yaml.
   spec:
     containers:
     - name: esp
       image: gcr.io/endpoints-release/endpoints-runtime:1
       args: [
         "--http2_port=9000",
         "--service=SERVICE_NAME",
         "--rollout_strategy=managed",
         "--backend=grpc://127.0.0.1:8000"
       ]
       ports:
         - containerPort: 9000
     - name: bookstore
       image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
       ports:
         - containerPort: 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.

   Exemple :

       spec:
         containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:1
           args: [
             "--http2_port=9000",
             "--service=bookstore.endpoints.example-project-12345.cloud.goog",
             "--rollout_strategy=managed",
             "--backend=grpc://127.0.0.1:8000"
           ]

   Nous vous recommandons de définir imagePullPolicy dans la spécification de conteneur ci-dessus sur Always. Cela permettra aux pods nouvellement créés d'extraire systématiquement la dernière version d'ESP. Découvrez les bonnes pratiques de configuration pour en savoir plus. Lorsqu'une nouvelle version d'ESP est publiée, vous pouvez effectuer un redémarrage progressif de tous les pods pour vous assurer que la version la plus récente est utilisée.

3. Démarrez le service :

   kubectl create -f grpc-bookstore.yaml
   

Remarque : Si votre cluster GKE est privé, vous devez utiliser le serveur de métadonnées Compute Engine en tant que résolveur DNS pour résoudre les noms d'hôte de service Google. Ajoutez l'option ESP suivante : --dns=169.254.169.254

Si vous recevez un message d'erreur, reportez-vous à la page Dépannage de Cloud Endpoints dans GKE.

Obtenir l'adresse IP externe du service

L'adresse IP externe du service est nécessaire pour envoyer des demandes à l'exemple d'API. Une fois que vous avez démarré le service dans le conteneur, la préparation de l'adresse IP externe peut prendre quelques minutes.

1. Affichez l'adresse IP externe :

   kubectl get service

2. Notez la valeur de EXTERNAL-IP et enregistrez-la dans une variable d'environnement SERVER_IP. L'adresse IP externe est utilisée pour envoyer des requêtes à l'exemple d'API.

   export SERVER_IP=YOUR_EXTERNAL_IP
   

Envoyer une requête à l'API

To send requests to the sample API, you can use a sample gRPC client written in Python.

1. Clone the git repo where the gRPC client code is hosted:

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

2. Change your working directory:

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

3. Install dependencies:

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

4. Send a request to the sample API:

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

   • Look at the activity graphs for your API in the Endpoints > Services page.
     

     Go to the Endpoints Services page

     It may take a few moments for the request to be reflected in the graphs.

   • Look at the request logs for your API in the Logs Explorer page.
     

     Go to the Logs Explorer page

Si vous ne recevez pas de réponse positive, consultez la page Dépanner des 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 API.

2. Supprimez le cluster GKE :

   gcloud container clusters delete NAME --zone ZONE
   

Étapes suivantes

• Découvrez comment configurer votre propre API gRPC pour Cloud 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