Premiers pas avec Endpoints pour Kubernetes avec ESPv2

Ce tutoriel vous explique comment déployer un exemple de service gRPC simple avec Extensible Service Proxy v2 (ESPv2) sur un cluster Kubernetes qui ne s'exécute pas sur Google Cloud. Ce tutoriel utilise la version Python bookstore-grpc échantillon. Consultez la section Étapes suivantes pour obtenir des exemples gRPC dans d'autres langages.

Ce tutoriel utilise des images de conteneur prédéfinies du code d'exemple et du proxy ESPv2 stockées dans Artifact 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 Cloud Endpoints.
  3. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
  4. Créez des identifiants pour votre service Endpoints. Consultez la section Créer des identifiants pour le service.
  5. Créez un backend pour diffuser et déployer l'API. Consultez la section Déployer le backend de l'API.
  6. Obtenez l'adresse IP externe du service. Consultez la section Obtenir l'adresse IP externe du service.
  7. Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
  8. 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

Pour suivre ce tutoriel, vous devez avoir déjà installé Minikube ou un cluster Kubernetes. Pour en savoir plus, consultez la documentation Kubernetes.

  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 du projet Google Cloud, car vous en aurez besoin ultérieurement.
  7. Installez et initialisez gcloud 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 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 de votre projet Google Cloud.

    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 de gcloud CLI.

  11. Installez kubectl : 
    gcloud components install kubectl
  12. Procurez-vous de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application. Ces identifiants utilisateur sont nécessaires pour autoriser kubectl. 
    gcloud auth application-default login
  13. Dans le nouvel onglet de navigateur, choisissez un compte.
  14. Suivez les étapes du démarrage rapide de gRPC Python pour installer gRPC et les outils gRPC.

Configurer Endpoints

La bookstore-grpc contient les fichiers à copier localement et à 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 section Configurer Endpoints.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, vous devez utiliser la classe gcloud endpoints services deploy . Cette commande utilise Service Infrastructure, la plate-forme de services de base de Google, utilisée par Endpoints et d'autres services pour créer et gérer des API et des services.

  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.

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

Voir Déployer la configuration Endpoints pour en savoir plus.

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.

Créer des identifiants pour votre service

Pour assurer la gestion de votre API, ESP et ESPv2 requièrent les services de Service Infrastructure. Pour appeler ces services, ESP et ESPv2 doivent utiliser des jetons d'accès. Lorsque vous déployez ESP ou ESPv2 dans des environnements Google Cloud tels que GKE ou Compute Engine, ESP et ESPv2 obtiennent pour vous des jetons d'accès via le service de métadonnées Google Cloud.

Lorsque vous déployez ESP ou ESPv2 dans un environnement autre que Google Cloud, que votre ordinateur local, un cluster Kubernetes sur site ou un autre vous devez fournir un fichier JSON de compte de service. contenant une clé privée. ESP et ESPv2 utilisent compte de service pour générer des jetons d'accès afin d'appeler les services dont il a besoin pour gérer votre API.

Vous pouvez utiliser la console Google Cloud ou la Google Cloud CLI pour créer le compte de service et le fichier de clé privée:

Console

  1. Dans la console Google Cloud, ouvrez la page Comptes de service .

    Accéder à la page "Comptes de service"

  2. Cliquez sur Sélectionner un projet.
  3. Sélectionnez le projet dans lequel votre API a été créée et cliquez sur Ouvrir.
  4. Cliquez sur + Créer un compte de service.
  5. Dans le champ Nom du compte de service, saisissez le nom de votre compte de service.
  6. Cliquez sur Créer.
  7. Cliquez sur Continuer.
  8. Cliquez sur OK.
  9. Cliquez sur l'adresse e-mail du compte de service que vous venez de créer.
  10. Cliquez sur Clés.
  11. Cliquez sur Add key (Ajouter une clé), puis sur Create new key (Créer une clé).

  12. Cliquez sur Créer. Un fichier de clé JSON est téléchargé sur votre ordinateur.

    Veillez à stocker le fichier de clé en toute sécurité, car il peut être utilisé pour s'authentifier en tant que compte de service. Vous pouvez déplacer et renommer ce fichier comme vous le souhaitez.

  13. Cliquez sur Fermer.

gcloud

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

    gcloud projects list

  2. Remplacez PROJECT_ID dans la commande suivante pour définir le projet par défaut sur celui hébergeant l'API :

    gcloud config set project PROJECT_ID

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

    gcloud auth login

    Si vous avez plusieurs comptes, veillez à choisir le compte du projet Google Cloud dans lequel se trouve l'API. Si vous exécutez gcloud auth list, le compte que vous avez sélectionné s'affiche en tant que compte actif pour le projet.

  4. Pour créer un compte de service, exécutez la commande suivante, et remplacez SERVICE_ACCOUNT_NAME et My Service Account par le nom et le nom à afficher que vous voulez utiliser :

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"

    Cette commande attribue au compte de service une adresse e-mail au format suivant :

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Vous aurez besoin de cette adresse e-mail pour les commandes qui suivent.

  5. Créez un fichier de clé de compte de service :

    gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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 plus d'informations, voir Que sont les rôles et les autorisations ?

Pour en savoir plus sur les commandes, consultez la page gcloud iam service-accounts.

Déployer le backend de l'API

À ce stade, vous avez déployé la configuration de service dans Service Management, mais vous n'avez pas encore déployé le code qui diffusera le backend de l'API. Cette section décrit la procédure de déploiement des conteneurs prédéfinis pour l'exemple d'API et le proxy ESPv2 vers Kubernetes.

Fournir les identifiants du service au proxy ESPv2

Le proxy ESPv2, qui s'exécute à l'intérieur d'un conteneur, doit avoir accès aux identifiants stockés localement dans le fichier service-account-creds.json. Pour fournir ESPv2 ayant accès aux identifiants, vous créez Code secret Kubernetes et installer le secret Kubernetes Volume Kubernetes

Pour créer le secret Kubernetes et installer le volume :

  1. Si vous avez utilisé la console Google Cloud pour créer le compte de service, renommez le fichier JSON en service-account-creds.json. Transférez-le dans le répertoire contenant api_descriptor.pb et api_config.yaml.

  2. Créez un secret Kubernetes contenant les identifiants du compte de service :

    kubectl create secret generic service-account-creds \
    --from-file=service-account-creds.json

    Si l'opération réussit, le message suivant s'affiche :

    secret "service-account-creds" created

Le fichier manifeste de déploiement que vous utilisez pour déployer l'API et le proxy ESPv2 sur Kubernetes contient déjà le volume secret, comme indiqué dans les deux sections suivantes du fichier :

volumes:
- name: service-account-creds
  secret:
    secretName: service-account-creds
 
volumeMounts:
- mountPath: /etc/esp/creds
  name: service-account-creds
  readOnly: true

Configurer le nom du service et démarrer le service

Le proxy ESPv2 a besoin de connaître le nom du service pour trouver la configuration que vous avez déployée précédemment à l'aide de la commande gcloud endpoints services deploy.

Pour configurer le nom du service et le démarrer :

  1. Enregistrez une copie du fichier manifeste de déploiement grpc-bookstore.yaml dans le même répertoire que service-account-creds.json.

  2. Ouvrez grpc-bookstore.yaml et 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.

    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",
    "--non_gcp",
    "--service_account_key=/etc/esp/creds/service-account-creds.json",
  ]

    L'option --rollout_strategy=managed Il configure ESPv2 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 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. Pour en savoir plus sur les arguments d'ESPv2, consultez la page Options de démarrage d'ESPv2.

  3. Démarrez le service pour le déployer sur Kubernetes :

    kubectl create -f grpc-bookstore.yaml

    Si un message d'erreur semblable au suivant apparaît :

    The connection to the server localhost:8080 was refused - did you specify the right host or port?

    Cela indique que kubectl n'est pas correctement configuré. Pour en savoir plus, consultez la page Configurer kubectl.

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 comme c'est le cas lors de l'envoi de 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 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

Étape suivante