Premiers pas avec API Gateway et Cloud Run pour gRPC

Cette page explique comment configurer API Gateway pour gérer et sécuriser un service de backend Cloud Run avec gRPC.

Liste de tâches

Tout au long du tutoriel, reportez-vous à la liste de tâches présentée ci-dessous. Toutes les tâches sont requises afin de déployer une passerelle API pour votre service de backend Cloud Run avec gRPC.

Créez ou sélectionnez un projet Google Cloud.
Si vous n'avez pas déployé votre propre environnement Cloud Run, déployez un exemple de service gRPC de backend. Reportez-vous à l'étape 7 de la section Avant de commencer.
Activez les services API Gateway requis.
Créez un document de configuration d'API gRPC qui décrit votre API et configure les routes vers votre environnement Cloud Run. Consultez la section Configurer une configuration d'API avec gRPC.
Déployez une passerelle API à l'aide de votre configuration d'API. Consultez la section Déployer une passerelle API.
Testez le déploiement de votre API en envoyant une requête. Consultez la section Envoyer des requêtes à l'API.
Suivez l'activité de vos services. Consultez la section Suivre l'activité de l'API.
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

Dans la console Google Cloud, accédez à la page Tableau de bord, puis sélectionnez ou créez un projet Google Cloud.
Accéder à la page "Tableau de bord"

Remarque : Si vous ne prévoyez pas de conserver les ressources créées dans ce tutoriel, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
Assurez-vous que la facturation est activée pour votre projet.
Découvrir comment activer la facturation
Notez l'ID du projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, cet ID est appelé PROJECT_ID.
Notez le numéro de projet, car vous en aurez besoin ultérieurement. Sur le reste de cette page, ce numéro est appelé PROJECT_NUMBER.
Téléchargez et installez la Google Cloud CLI.
Télécharger la gcloud CLI
Suivez les étapes du guide de démarrage rapide de gRPC Python pour installer gRPC et les outils gRPC.
Déployez l'exemple de service Cloud Run gRPC backend 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 l'URL du service, ainsi que la région et l'ID du projet dans lequel votre service est déployé.

Activer les services requis

API Gateway nécessite l'activation des services Google suivants :

Nom	Titre
`apigateway.googleapis.com`	API de la passerelle API
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

Pour confirmer que les services requis sont activés, procédez comme suit :

gcloud services list

Si les services requis ne sont pas répertoriés, activez-les :

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Pour en savoir plus sur les services gcloud, consultez la section Services gcloud.

Créer une configuration d'API avec gRPC

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

Créez un fichier descripteur protobuf autonome à partir du fichier .proto de votre service :
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.

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: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + 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.

Dans le champ name, un service nommé *.apigateway.PROJECT_ID.cloud.goog, où PROJECT_ID est le nom de votre ID de projet Google Cloud.
Dans le champ address de la section backend.rules, remplacez grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app par l'URL réelle du service gRPC Cloud Run backend python-grpc-bookstore-server service, où HASH est le code de hachage unique généré lors de la création du service.

Remarque : Pour utiliser gRPC avec TLS sur Cloud Run, le champ address doit comporter le schéma grpcs:// au lieu de https://.

Cet exemple suppose que vous utilisez le service de backend gRPC Bookstore créé dans la section Avant de commencer. Si nécessaire, remplacez cette valeur par l'URL de votre service Cloud Run.
Enregistrez le document de configuration de votre API gRPC.

Créez la configuration de l'API :

gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml

où :

CONFIG_ID spécifie le nom de votre configuration d'API.
API_ID spécifie le nom de votre API.
PROJECT_ID est le nom de votre projet Google Cloud.

Exemple:

gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

Déployer une passerelle API

Pour déployer la configuration de l'API gRPC sur une passerelle, exécutez la commande suivante :

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

où :

GATEWAY_ID spécifie le nom de la passerelle.
API_ID spécifie le nom de l'API API Gateway associée à cette passerelle.
CONFIG_ID spécifie le nom de la configuration d'API déployée sur la passerelle.
GCP_REGION est la région Google Cloud pour la passerelle déployée.
Remarque :
Les valeurs autorisées sont les suivantes :
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
Les passerelles API Gateway créées précédemment dans asia-east1 ne seront plus compatibles à partir du 1er novembre 2022. Nous vous recommandons d'examiner toutes les passerelles en cours d'exécution dans asia-east1, puis de les supprimer ou de les recréer dans un nouvel emplacement si nécessaire.
PROJECT_ID est le nom de votre projet Google Cloud.

Exemple :

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

Si l'opération réussit, vous pouvez utiliser la commande suivante pour afficher les détails de la passerelle :

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Notez la valeur de la propriété defaultHostname dans le résultat de cette commande. Il s'agit de la partie nom d'hôte de l'URL de passerelle que vous utiliserez pour tester votre déploiement à l'étape suivante.

Exemple :

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

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.

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

Modifiez votre répertoire de travail :

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

Installez les dépendances :

pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

Envoyez une requête à l'exemple d'API :

python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

Spécifiez la propriété defaultHostname de votre passerelle dans DEFAULT_HOSTNAME, sans l'identifiant de protocole. Exemple :

python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

Suivre l'activité de l'API

Affichez les graphiques d'activité de votre API sur la page API Gateway de la console Google Cloud. Cliquez sur votre API pour afficher ses graphiques d'activité sur la page Présentation. Il peut s'écouler quelques instants avant que les requêtes ne soient reflétées dans les graphiques.
Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux. Un lien vers la page Explorateur de journaux est disponible sur la page API Gateway de la console Google Cloud.
Accéder à la page API Gateway
Une fois sur la page API Gateway :
1. Sélectionnez l'API à afficher.
2. Cliquez sur l'onglet Détails.
3. Cliquez sur le lien sous Journaux.

Vous venez de déployer et de tester une API dans API Gateway avec gRPC.

Effectuer un nettoyage

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

Vous pouvez également supprimer le projet Google Cloud utilisé pour ce tutoriel.