Configurer OpenAPI Cloud Endpoints pour Cloud Run avec ESPv2
Cette page vous explique comment configurer Cloud Endpoints pour Cloud Run. Cloud Endpoints utilise le proxy Extensible Service Proxy V2 (ESPv2) en guise de passerelle API. Afin d'assurer la gestion des API par Cloud Run, vous devez déployer le conteneur ESPv2 prédéfini sur Cloud Run. Vous pouvez ensuite sécuriser vos services à l'aide de l'IAM Cloud Run afin qu'ESPv2 puisse les appeler.
Une fois la configuration finalisée, ESPv2 peut intercepter toutes les requêtes adressées à vos services avant de les appeler, et effectuer les vérifications nécessaires, telles que l'authentification. Lorsque le service répond, ESPv2 rassemble et consigne les données de télémétrie, comme illustré par la figure ci-dessous. Vous pouvez afficher les métriques de votre service sur la page Endpoints > Page Services dans la console Google Cloud.
Pour obtenir une présentation de Cloud Endpoints, consultez les pages À propos de Cloud Endpoints et Architecture Cloud Endpoints.
Migrer vers ESPv2
Les versions précédentes de Cloud Endpoints acceptaient l'utilisation du proxy Extensible Service Proxy (ESP) avec Cloud Functions. Si vous souhaitez migrer des API existantes vers ESPv2, consultez la page Migrer vers Extensible Service Proxy V2 pour en savoir plus.
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.
- 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 backend. Consultez la section Avant de commencer.
- Réservez un nom d'hôte Cloud Run pour le service ESPv2. Consultez la page Réserver un nom d'hôte Cloud Run.
- Créez un document OpenAPI décrivant votre API, puis configurez les routes vers votre environnement Cloud Run. Consultez la section Configurer Endpoints.
- Déployez le document OpenAPI pour créer un service géré. Consultez la section Déployer la configuration Endpoints.
- Créez une image ESPv2 pour Docker avec votre configuration de service Endpoints. Consultez la section Créer une nouvelle image ESPv2.
- Déployez le conteneur ESPv2 dans Cloud Run. Accordez ensuite à ESPv2 l'autorisation IAM (Identity and Access Management) d'appeler votre service. Consultez la section Déployer le conteneur ESPv2.
- Appelez un service. 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.
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.
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
Avant de vous lancer, procédez comme suit :
Dans la console Google Cloud, accédez à la page Gérer les ressources. et créer un projet.
Assurez-vous que la facturation est activée pour votre projet.
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.
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.
Téléchargez et installez Google Cloud CLI.
Si vous n'avez pas encore déployé votre propre service backend Cloud Run, suivez la procédure décrite dans le guide Démarrage rapide : Déployer un exemple de conteneur prédéfini pour sélectionner ou créer un projet Google Cloud, et déployer un exemple de backend. Notez la région et l'ID de projet correspondant à l'emplacement de déploiement de votre service. 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.
Réserver un nom d'hôte Cloud Run
Vous devez réserver un nom d'hôte Cloud Run pour le service ESPv2 afin de configurer le document OpenAPI ou la configuration du service gRPC. Pour réserver un nom d'hôte, vous devez déployer un exemple de conteneur dans Cloud Run. Vous déploierez par la suite le conteneur ESPv2 sur le même service Cloud Run.
-
Assurez-vous que la CLI gcloud est autorisée à accéder à vos données et services.
- Connectez-vous.
gcloud auth login
- 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 dans Cloud Run.
- Connectez-vous.
- Définissez la région.
gcloud config set run/region us-central1
-
Déployez l'exemple d'image
gcr.io/cloudrun/hello
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/cloudrun/hello" \ --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 etgateway-12345-uc.a.run.app
à CLOUD_RUN_HOSTNAME. - Notez CLOUD_RUN_SERVICE_NAME et CLOUD_RUN_HOSTNAME.
Vous déploierez par la suite ESPv2 sur le service Cloud Run CLOUD_RUN_SERVICE_NAME.
Spécifiez CLOUD_RUN_HOSTNAME dans le champ
host
du document OpenAPI.
Configurer Endpoints
Vous devez disposer d'un document OpenAPI basé sur la version 2.0 de la spécification OpenAPI décrivant la surface de votre service de backend, ainsi que les conditions requises pour l'authentification. Vous devez également ajouter un champ spécifique à Google contenant l'URL de chaque service afin qu'ESPv2 dispose des informations nécessaires pour les appeler. Si vous débutez avec OpenAPI, consultez la page Présentation d'OpenAPI pour en savoir plus.
-
Créez un fichier texte intitulé
openapi-run.yaml
. Pour des raisons de commodité, cet article utilise ce nom de fichier pour désigner le document OpenAPI, mais vous pouvez le nommer autrement si vous préférez. -
Votre service de backend Cloud Run est défini en haut du fichier
openapi-run.yaml
, dans une définitionx-google-backend
. Exemple : La mise en retrait est importante pour le format YAML. Par exemple, le champswagger: '2.0' info: title: Cloud Endpoints + Cloud Run description: Sample API on Cloud Endpoints with a Cloud Run backend version: 1.0.0 host: CLOUD_RUN_HOSTNAME schemes: - https produces: - application/json x-google-backend: address: BACKEND_SERVICE_NAME protocol: h2 paths: /hello: get: summary: Greet a user operationId: hello responses: '200': description: A successful response schema: type: string
host
doit se trouver au même niveau queinfo
. Dans le champ
address
de la sectionx-google-backend
, remplacez BACKEND_SERVICE_NAME par l'URL réelle de votre service de backend Cloud Run créé à l'étape 6 de la page Avant de commencer.Cet exemple part du principe que vous utilisez le service de backend
hello
créé dans le guide Démarrage rapide : Déployer un exemple de conteneur prédéfini. Si vous utilisez un autre service Cloud Run de backend, remplacez BACKEND_SERVICE_NAME par l'URL de votre service Cloud Run.Dans le champ
host
, spécifiez CLOUD_RUN_HOSTNAME, c'est-à-dire la partie nom d'hôte de l'URL réservée, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run. N'incluez pas l'identifiant du protocolehttps://
. Exemple :swagger: '2.0' info: title: Cloud Endpoints + Cloud Run description: Sample API on Cloud Endpoints with a Cloud Run backend version: 1.0.0 host: gateway-12345-uc.a.run.app
Notez la valeur de la propriété
title
dans le fichieropenapi-run.yaml
:title: Cloud Endpoints + Cloud Run
La valeur de la propriété
title
devient le nom du service Endpoints après le déploiement de la configuration.- Enregistrez votre document OpenAPI.
Pour en savoir plus sur les champs du document OpenAPI requis par Endpoints, 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.
Pour déployer la configuration Endpoints :
- Assurez-vous que vous vous trouvez dans le répertoire contenant votre document OpenAPI.
Téléchargez la configuration et créez un service géré.
gcloud endpoints services deploy openapi-run.yaml \ --project ESP_PROJECT_ID
Vous créez ainsi un service Endpoints avec le nom spécifié dans le champ
host
du fichieropenapi-run.yaml
. Le service est configuré conformément à votre document OpenAPI.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 [CLOUD_RUN_HOSTNAME]
CONFIG_ID correspond à l'ID unique de configuration du service Endpoints créé par le déploiement. Exemple :
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
L'ID de configuration de service se compose d'un horodatage, suivi d'un numéro de révision. Si vous déployez à nouveau
openapi-run.yaml
le même jour, le numéro de révision est incrémenté dans l'ID de configuration de service. Vous pouvez afficher la configuration du service Historique des déploiements sur le point de terminaison Points de terminaison > Services de la console Google Cloud.Si vous recevez un message d'erreur, consultez la section Résoudre des problèmes de déploiement de la configuration Endpoints.
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.comgcloud 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 champname
de votre configuration Endpoints gRPC.
Pour en savoir plus sur les commandes gcloud
, consultez la page Services gcloud
.
Créer une image ESPv2
Créez la configuration du service Endpoints dans une nouvelle image ESPv2 pour Docker. Vous déploierez par la suite cette image sur le service Cloud Run réservé.
Pour créer la configuration de service dans une nouvelle image ESPv2 pour Docker, procédez comme suit :
Télécharger script sur votre machine locale sur laquelle gcloud CLI est installée.
Exécutez le script avec la commande suivante :
chmod +x gcloud_build_image
./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_ID
Pour le paramètre CLOUD_RUN_HOSTNAME, spécifiez le nom d'hôte de l'URL que vous avez réservé, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run. 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 your-project-id
-
Le script utilise la commande
gcloud
pour télécharger la configuration de service, la compiler dans une nouvelle image ESPv2, puis importer la nouvelle image dans le registre de conteneurs de votre projet. Le script utilise automatiquement la dernière version d'ESPv2, désignée par ESP_VERSION dans le nom de l'image de sortie. L'image de sortie est importée dans l'emplacement suivant :gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID
Exemple :
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
Déployer le conteneur ESPv2
Déployez le service ESPv2 pour Cloud Run avec la nouvelle image créée ci-dessus. Remplacez CLOUD_RUN_SERVICE_NAME par le nom du service Cloud Run utilisé lors de la réservation initiale du nom d'hôte, comme indiqué ci-dessus dans la section Réserver un nom d'hôte Cloud Run :
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Si vous souhaitez configurer Endpoints afin d'utiliser d'autres options de démarrage d'ESPv2, 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:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --allow-unauthenticated \ --platform managed \ --project ESP_PROJECT_ID
Pour en savoir plus et obtenir des exemples de définition de la variable d'environnement
ESPv2_ARGS
, y compris la liste des options disponibles et des informations sur la manière de spécifier plusieurs options, reportez-vous à la page sur les options d'Extensible Service Proxy V2.Accordez à ESPv2 l'autorisation d'appeler Service Management et Service Control.
- Dans la console Google Cloud, accédez à la page Cloud Run.
- Vous pouvez voir l'instance Cloud Run que vous avez déployée et le compte de service qui lui est associé.
- Accordez des autorisations au compte de service :
- Accordez à ESPv2 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 de backend créé dans le guide Démarrage rapide : Déployer un exemple de conteneur prédéfini, utilisez
hello
comme valeur. - Remplacez ESP_PROJECT_NUMBER par le numéro du projet que vous avez créé pour ESPv2. Pour ce faire, vous pouvez accéder à la page IAM de la console Google Cloud et rechercher le compte de service Compute par défaut, qui correspond au compte de service utilisé dans l'indicateur "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
- Remplacez BACKEND_SERVICE_NAME par le nom du service Cloud Run appelé. Si vous utilisez le service de backend créé dans le guide Démarrage rapide : Déployer un exemple de conteneur prédéfini, utilisez
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceController
Pour en savoir plus, consultez la page Gérer les accès à l'aide d'IAM.
Envoyer des requêtes à l'API
Cette section montre comment envoyer des requêtes à votre API.
- Créez une variable d'environnement pour le nom de votre service Endpoints. Il s'agit du nom que vous avez spécifié dans le champ
host
du document OpenAPI. Exemple :Linux ou macOS :
export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
Windows PowerShell:
$Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"
Linux ou macOS
Utilisez curl
pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_HOST
que vous avez définie à l'étape précédente.
curl --request GET \ --header "content-type:application/json" \ "https://${ENDPOINTS_HOST}/hello"
PowerShell
Utilisez Invoke-WebRequest
pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_HOST
que vous avez définie à l'étape précédente.
(Invoke-WebRequest -Method GET ` -Headers @{"content-type"="application/json"} ` -URI "https://$Env:ENDPOINTS_HOST/hello").Content
Dans l'exemple ci-dessus, les deux premières lignes se terminent par un accent grave. Lorsque vous collez l'exemple dans PowerShell, assurez-vous qu'il n'y a pas d'espace après les accents graves. Pour plus d'informations sur les options utilisées dans l'exemple de requête, consultez la page Invoke-WebRequest dans la documentation Microsoft.
Application tierce
Vous pouvez utiliser une application tierce telle que le navigateur Chrome. extension Facteur requête.
- Sélectionnez
GET
comme verbe HTTP. - Pour l'en-tête, sélectionnez la clé
content-type
et la valeurapplication/json
. Utilisez l'URL réelle au lieu de la variable d'environnement, par exemple :
https://gateway-12345-uc.a.run.app/hello
Si vous ne recevez pas de réponse positive, consultez la section Résoudre des problèmes concernant les erreurs de réponse.
Vous venez de déployer et de tester une API dans Endpoints.
Suivre l'activité de l'API
Consultez les graphiques d'activité de votre API sur la page Endpoints > Service de la console Google Cloud.
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.
Consultez les journaux de requêtes de votre API sur la page de l'explorateur 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 sur cette page soient facturées sur votre compte Google Cloud, procédez comme suit :
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.