Premiers pas avec Endpoints pour Cloud Run

Cette page vous explique comment configurer Cloud Endpoints pour Cloud Run avec un backend gRPC. Cloud Endpoints utilise le proxy Extensible Service Proxy V2 bêta (ESPv2 bêta) en tant que passerelle API. Afin d'assurer la gestion des API pour Cloud Run, vous devez déployer le conteneur ESPv2 bêta prédéfini sur Cloud Run. Vous pouvez ensuite sécuriser vos services à l'aide des rôles IAM pour Cloud Run afin qu'ESPv2 bêta puisse les appeler.

Une fois la configuration finalisée, ESPv2 bêta peut intercepter toutes les requêtes adressées à vos services et effectuer les vérifications nécessaires, telles que l'authentification, avant de les appeler. Lorsque le service répond, ESPv2 bêta rassemble et consigne les données de télémétrie. Vous pouvez afficher les métriques de votre service sur la page Endpoints > Services de Google Cloud Console.

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

Migrer vers ESPv2 bêta

Les versions précédentes de Cloud Endpoints n'acceptaient pas gRPC sur Cloud Run avec ESP. Veuillez migrer vers Extensible Service Proxy V2 bêta pour utiliser cette fonctionnalité.

Liste de tâches

Tout au long du tutoriel, reportez-vous à la liste de tâches présentée ci-dessous. La finalisation du tutoriel suppose de réaliser l'intégralité de ces tâches.

  1. Créez un projet Google Cloud et, si vous n'avez pas déployé votre propre environnement Cloud Run, déployez un exemple de service gRPC. Consultez la section Avant de commencer.
  2. Déployez le conteneur ESPv2 bêta dans Cloud Run. Consultez la section Déployer ESPv2 bêta.
  3. Créez un document de configuration de l'API gRPC décrivant votre API, puis configurez les routes vers votre instance Cloud Run. Consultez la section Configurer Endpoints.
  4. Déployez le document de configuration de l'API gRPC pour créer un service géré. Consultez la section Déployer la configuration Endpoints.
  5. Créez et déployez une image Docker ESPv2 bêta avec votre configuration du service Endpoints. Accordez ensuite à ESPv2 bêta l'autorisation IAM (Identity and Access Management) d'appeler votre service. Consultez la section Créer une image ESPv2 bêta.
  6. Appelez un service. Consultez la section Envoyer des requêtes à l'API.
  7. Suivez l'activité de vos services. Consultez la section Suivre l'activité de l'API.
  8. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Effectuer un nettoyage.

Avant de commencer

Avant de vous lancer, procédez comme suit :

  1. Dans Cloud Console, accédez à la page Gérer les ressources et créez un projet.

    Accéder à la page "Gérer les ressources"

  2. Assurez-vous que la facturation est activée pour votre projet.

    Découvrir comment activer la facturation

  3. Notez l'ID du projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, cet ID est appelé ESP_PROJECT_ID.

  4. Notez le numéro de projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, ce numéro est appelé ESP_PROJECT_NUMBER.

  5. Téléchargez et installez le SDK Cloud.

    Télécharger le SDK Cloud

  6. Suivez les étapes du guide de démarrage rapide de gRPC Python pour installer gRPC et les outils gRPC.

  7. Déployez l'exemple de service Cloud Run gRPC python-grpc-bookstore-server pour l'utiliser avec ce tutoriel. Le service gRPC utilise l'image de conteneur suivante :

    gcr.io/endpointsv2/python-grpc-bookstore-server:2

    Suivez les étapes du Guide de démarrage rapide : déployer un exemple de conteneur prédéfini pour déployer le service. Veillez à remplacer l'image de conteneur spécifiée dans ce guide de démarrage rapide par gcr.io/endpointsv2/python-grpc-bookstore-server:2.

    Notez la région et l'identifiant du projet dans lequel votre service est déployé. Sur le reste de cette page, cet ID est appelé BACKEND_PROJECT_ID. Le nom désignant le service déployé est BACKEND_SERVICE_NAME.

Déployer ESPv2 bêta

Pour déployer le conteneur ESPv2 bêta dans Cloud Run, procédez comme suit :

  1. Assurez-vous que le SDK Cloud est autorisé à accéder à vos données et services.
    1. Connectez-vous.
      gcloud auth login
    2. Dans le nouvel onglet de navigateur qui s'ouvre, choisissez un compte auquel a été attribué le rôle Éditeur ou Propriétaire dans le projet Google Cloud que vous avez créé pour déployer ESPv2 bêta dans Cloud Run.
  2. Définissez la région.
    gcloud config set run/region us-central1
  3. Déployez ESPv2 bêta dans Cloud Run. Remplacez CLOUD_RUN_SERVICE_NAME par le nom que vous souhaitez utiliser pour le service.
    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
        --image="gcr.io/endpoints-release/endpoints-runtime-serverless:2" \
        --allow-unauthenticated \
        --platform managed \
        --project=ESP_PROJECT_ID
    

    Si elle réussit, la commande affiche un message semblable à celui-ci :

    Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

    Par exemple, si vous définissez CLOUD_RUN_SERVICE_NAME sur gateway :

    Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

    Dans cet exemple, https://gateway-12345-uc.a.run.app correspond à CLOUD_RUN_SERVICE_URL et gateway-12345-uc.a.run.app à CLOUD_RUN_HOSTNAME.

  4. Notez la valeur de CLOUD_RUN_HOSTNAME. Spécifiez l'élément CLOUD_RUN_HOSTNAME dans le champ name du document de configuration de l'API gRPC (vous en aurez besoin ultérieurement).
  5. Vous pouvez vérifier si la version initiale d'ESPv2 bêta est déployée sur Cloud Run en accédant à CLOUD_RUN_SERVICE_URL dans votre navigateur Web. Un message d'avertissement à propos d'une variable d'environnement manquante s'affiche normalement. Ce message d'avertissement est attendu et s'affiche jusqu'à la fin de l'étape Créer une image ESPv2 bêta
  6. Votre service Cloud Run est public sur Internet. Si vous souhaitez ajouter des fonctionnalités d'authentification, nous vous recommandons d'utiliser l'une des méthodes d'authentification compatibles avec Endpoints.

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 dans votre répertoire de travail actuel 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 dans votre répertoire de travail : 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 :
      python3 -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 texte appelé api_config.yaml dans votre répertoire de travail actuel (le même répertoire que celui contenant bookstore.proto). Pour plus de commodité, cette page utilise ce nom de fichier pour désigner le document de configuration de l'API gRPC, mais vous pouvez lui donner un autre nom si vous préférez. Ajoutez le contenu suivant au fichier  :
    # The configuration schema is defined by the service.proto file.
    # https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
    
    type: google.api.Service
    config_version: 3
    name: CLOUD_RUN_HOSTNAME
    title: Cloud Endpoints + Cloud Run gRPC
    apis:
      - name: endpoints.examples.bookstore.Bookstore
    usage:
      rules:
      # ListShelves methods can be called without an API Key.
      - selector: endpoints.examples.bookstore.Bookstore.ListShelves
        allow_unregistered_calls: true
    backend:
      rules:
        - selector: "*"
          address: grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app
    
    La mise en retrait est importante pour le format YAML. Par exemple, le champ name doit se trouver au même niveau que type.
  3. Dans le champ name, spécifiez CLOUD_RUN_HOSTNAME, la partie du nom d'hôte de l'URL créée par Cloud Run lors du déploiement d'ESPv2 bêta, effectué à la section Déployer ESPv2 bêta. N'incluez pas l'identifiant de protocole https:// ou grpcs://.

  4. Dans le champ address dans la section backend.rules, remplacer grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app avec l'URL réelle de l'exemple de service gRPC Cloud Run Python-grpc-bookstore-server, où HASH est le code de hachage unique généré lors de la création du service.

    Dans cet exemple, nous partons du principe que vous utilisez le service Bookstore gRPC créé dans la section Avant de commencer. Si nécessaire, remplacez cette valeur par l'URL de votre service Cloud Run.

  5. Notez la valeur de la propriété title dans le fichier api_config.yaml :

    title: Cloud Endpoints + Cloud Run gRPC

    La valeur de la propriété title devient le nom du service Endpoints après le déploiement de la configuration.

  6. Enregistrez le document de configuration de votre API gRPC.

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.

Créer une image ESPv2 bêta

Créez la configuration de service Endpoints dans une nouvelle image Docker ESPv2 bêta et redéployez le service ESPv2 bêta Cloud Run avec l'image. Accordez ensuite à ESPv2 bêta l'autorisation IAM d'appeler vos services.

Pour créer la configuration de service dans une nouvelle image Docker ESPv2 bêta, procédez comme suit :

  1. Téléchargez ce script sur la machine locale où le SDK gcloud est installé, puis exécutez-le comme suit :

    chmod +x gcloud_build_image
    
    ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
        -c CONFIG_ID -p ESP_PROJECT_ID

    Dans le champ CLOUD_RUN_HOSTNAME, spécifiez le nom d'hôte de l'URL créée par Cloud Run lors du déploiement d'ESPv2 bêta effectué à la section Déployer ESPv2 bêta. N'incluez pas l'identifiant du protocole https://.

    Exemple :

    chmod +x gcloud_build_image
    ./gcloud_build_image -s gateway-12345-uc.a.run.app \
        -c 2019-02-01r0 -p ESP_PROJECT_ID

    Le script utilise la commande gcloud pour télécharger la configuration de service, créer cette configuration dans une nouvelle image ESPv2 bêta, et importer la nouvelle image dans le registre de conteneurs de votre projet situé à l'emplacement suivant :

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID

    Exemple :

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:gateway-12345-uc.a.run.app-2019-02-01r0"
  2. Redéployez le service Cloud Run ESPv2 bêta avec la nouvelle image. Remplacez CLOUD_RUN_SERVICE_NAME par le nom du service Cloud Run utilisé lors du déploiement initial effectué à la section Déployer ESPv2 bêta :

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --allow-unauthenticated \
      --platform managed \
      --project=ESP_PROJECT_ID
  3. Si vous souhaitez configurer d'autres options de démarrage ESPv2 bêta pour Cloud Endpoints, telles que l'activation de CORS, vous pouvez transmettre les arguments dans la variable d'environnement ESPv2_ARGS :

    gcloud run deploy CLOUD_RUN_SERVICE_NAME \
      --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:CLOUD_RUN_HOSTNAME-CONFIG_ID" \
      --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
      --allow-unauthenticated \
      --platform managed \
      --project ESP_PROJECT_ID

    Pour obtenir des exemples de définition de la variable d'environnement ESPv2_ARGS, consulter la liste des options disponibles et découvrir comment spécifier plusieurs options, reportez-vous à la page sur les options ESPv2 bêta.

  4. Attribuez à ESPv2 bêta l'autorisation d'appeler vos services Cloud Run. Exécutez la commande ci-dessous pour chaque service. Dans la commande suivante :
    • Remplacez BACKEND_SERVICE_NAME par le nom du service Cloud Run appelé. Si vous utilisez le service créé en déployant "gcr.io/endpointsv2/python-grpc-bookstore-server:2", utilisez python-grpc-bookstore-server comme valeur.
    • Remplacez ESP_PROJECT_NUMBER par le numéro du projet que vous avez créé pour ESPv2 bêta. Pour ce faire, vous pouvez accéder à la page IAM de Cloud Console et trouver le Compte de service Compute par défaut, qui est celui utilisé dans l'option "member".
    gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
      --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/run.invoker" \
      --platform managed \
      --project BACKEND_PROJECT_ID

Pour en savoir plus, consultez la page Gérer les accès à l'aide d'IAM.

Envoyer des requêtes à 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 :

    pip3 install virtualenv
    virtualenv env
    source env/bin/activate
    pip3 install -r requirements.txt
  4. Envoyez une requête à l'exemple d'API :

    python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

    Spécifiez le nom d'hôte de votre service Cloud Run ESPv2 bêta dans CLOUD_RUN_HOSTNAME, sans l'identifiant de protocole. Exemple :

    python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true

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.

Suivre l'activité de l'API

  1. Consultez les graphiques d'activité de votre API sur la page Endpoints > Services de Cloud Console.

    Afficher les graphiques d'activité Endpoints

    Il peut s'écouler quelques instants avant que la requête ne soit reflétée dans les graphiques.

  2. Consultez les journaux de requêtes de votre API sur la page de la visionneuse de journaux.

    Afficher les journaux de requête Endpoints

Créer un portail développeur pour l'API

Vous pouvez utiliser le portail Cloud Endpoints pour créer un portail des développeurs, c'est-à-dire un site Web qui vous permet d'interagir avec l'exemple d'API. Pour en savoir plus, consultez la page Présentation du portail Cloud Endpoints.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce guide démarrage rapide soient facturées sur votre compte Google Cloud :

Pour plus d'informations sur l'arrêt des services utilisés par ce tutoriel, consultez la page Supprimer une API et des instances d'API.

Étapes suivantes