Premiers pas avec Endpoints pour GKE avec ESPv2

Ce tutoriel explique comment déployer un exemple de services gRPC simple avec Extensible Service Proxy V2 bêta (ESPv2 bêta) 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.

Ce tutoriel est basé sur des images de conteneur prédéfinies du code d'exemple et d'ESPv2 bêta, qui sont stockés dans Container Registry. Si vous n'êtes pas encore familiarisé avec les conteneurs, consultez les sections suivantes pour plus d'informations :

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 publier 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. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Effectuer un nettoyage.

Coûts

Ce tutoriel utilise 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é ce tutoriel, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Consultez la page Effectuer un nettoyage pour en savoir plus.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

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

    Accéder à la page de sélection du projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Notez l'ID du projet Google Cloud, car vous en aurez besoin ultérieurement.
  5. Installez et initialisez le SDK Cloud.
  6. Mettez à jour le SDK Cloud et installez les composants Endpoints.
    gcloud components update
  7. Assurez-vous que le SDK Cloud (gcloud) est autorisé à accéder à vos données et services sur Google Cloud :
    gcloud auth login
    Un nouvel onglet de navigateur vous invite à choisir un compte.
  8. 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 voulez les gérer à l'aide de gcloud, consultez la page Gérer les configurations du SDK Cloud.

  9. Installez kubectl :
    gcloud components install kubectl
  10. 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.
  11. 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. 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éployez le fichier proto descriptor et le fichier de configuration à l'aide de l'outil de ligne de commande gcloud :
    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 Endpoints de Cloud Console. 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 conteneurs pour notre exemple :

  1. Dans Cloud Console, accédez à la page des 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

Veuillez suivre cette recommandation d'autorisation pour choisir un compte de service de nœud approprié en tant qu'identité permettant de communiquer avec les services Google. ESP et ESPv2 bêta doivent communiquer avec Google ServiceController et Stackdriver. Des rôles IAM supplémentaires sont requis pour le compte de service de nœud exécutant ESP et ESPv2 bêta.

Si le compte de service de nœud n'est pas le compte de service Compute Engine par défaut, suivez l'étape ci-dessous pour ajouter les rôles IAM requis :

Ajoutez les rôles IAM requis :

Les rôles IAM suivants sont requis pour le compte de service utilisé pour ESP et ESPv2 bêta.

Pour ajouter les rôles IAM du contrôleur de service et de l'agent Cloud Trace au compte de service, procédez comme suit :

Console

  1. Dans Cloud Console, sélectionnez le projet dans lequel votre compte de service a été créé.
  2. Ouvrir la page IAM/Iam

    Accéder à la page IAM/Iam

    La page doit répertorier tous les membres IAM, y compris tous les comptes de service.
  3. Sélectionnez votre compte de service, puis cliquez sur le bouton Modifier situé à droite.
  4. Un panneau Modifier les autorisations s'ouvre.
  5. Cliquez sur + Ajouter un autre rôle.
  6. Cliquez sur Sélectionner un rôle, puis sélectionnez Service Management > Contrôleur des services.
  7. Cliquez sur + Ajouter un autre rôle.
  8. Cliquez sur Sélectionner un rôle, puis sélectionnez Cloud Trace > Agent Cloud Trace.
  9. Cliquez sur Enregistrer.
  10. Vous devriez maintenant voir les rôles de contrôleur de service et d'agent Cloud Trace dans la colonne Rôle de votre compte de service sur la page IAM.

gcloud

  1. Ajoutez le rôle "Contrôleur des services" :

    gcloud projects add-iam-policy-binding PROJECT_ID \
            --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
            --role roles/servicemanagement.serviceController
  2. Ajoutez le rôle "Agent Cloud Trace" pour activer Cloud Trace :

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

Pour en savoir plus, consultez la section Que sont les rôles et les autorisations?

WorkLoad Identity :

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 le pod afin d'exécuter ESP et ESPv2 bêta, 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.

Le compte de service Google doit avoir les rôles IAM requis ci-dessus. Sinon, suivez les étapes pour ajouter les rôles IAM requis.

Déployer les exemples d'API et d'ESPv2 bêta sur le cluster

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

  1. git clone ce dépôt et ouvrez le fichier manifeste de déploiement grpc-bookstore.yaml pour le modifier.
  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:2
        args: [
          "--listener_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 ESPv2 bêta pour qu'il utilise la dernière configuration de service déployée. Si cette option est spécifiée, une minute après le déploiement d'une nouvelle configuration de service, ESPv2 bêta détecte la modification et commence à l'utiliser automatiquement. Nous vous recommandons de spécifier cette option plutôt que de fournir un ID de configuration spécifique à utiliser avec ESPv2 bêta. Pour en savoir plus sur les arguments d'ESPv2 bêta, consultez les options de démarrage d'ESPv2 bêta.

    Exemple :

        spec:
          containers:
          - name: esp
            image: gcr.io/endpoints-release/endpoints-runtime:2
            args: [
              "--listener_port=9000",
              "--service=bookstore.endpoints.example-project-12345.cloud.goog",
              "--rollout_strategy=managed",
              "--backend=grpc://127.0.0.1:8000"
            ]
    
  3. Démarrez le service :
    kubectl create -f grpc-bookstore.yaml
    

Si vous recevez un message d'erreur, reportez-vous à la section Dépannage de Endpoints sur 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

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 Dépanner des 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 dans ce tutoriel soient facturées sur votre compte Google Cloud Platform :

  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