Cette page a été traduite par l'API Cloud Translation.
Switch to English

Premiers pas avec Cloud Endpoints pour Kubernetes avec ESPv2

Ce tutoriel vous explique comment configurer et déployer un exemple d'API et le proxy Extensible Service Proxy V2 (ESPv2) sur un cluster Kubernetes qui ne se trouve pas sur Google Cloud. Si vous souhaitez utiliser Google Kubernetes Engine (GKE), consultez la page Premiers pas avec Endpoints sur GKE.

L'API REST de l'exemple de code est décrite à l'aide de la spécification OpenAPI. Le tutoriel vous montre également comment créer une clé API pour envoyer des requêtes adressées à l'API.

Ce tutoriel utilise des images de conteneur prédéfinies du code d'exemple et du proxy ESPv2 stockées 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 Architecture Cloud Endpoints.

Objectifs

Tout au long du tutoriel, reportez-vous au récapitulatif des étapes présenté ci-dessous. Toutes les tâches de la partie 1 sont nécessaires pour envoyer des requêtes à l'API.

Partie 1

  1. Configurez un projet Google Cloud. Consultez la section Avant de commencer.
  2. Installez et configurez le logiciel utilisé dans le tutoriel. Consultez la section Installer et configurer les logiciels requis.
  3. Téléchargez l'exemple de code (facultatif). Consultez la section Obtenir l'exemple de code.
  4. Téléchargez le fichier de configuration Kubernetes. Consultez la section Obtenir le fichier de configuration Kubernetes.
  5. Configurez le fichier openapi.yaml, utilisé pour configurer Endpoints. Consultez la section Configurer Endpoints.
  6. Déployez la configuration Endpoints pour créer un service Cloud Endpoints. Consultez la section Déployer la configuration Endpoints.
  7. Créez des identifiants pour votre service Endpoints. Consultez la section Créer des identifiants pour votre service.
  8. Déployez l'API et ESPv2 sur le cluster. Consultez la section Déployer le backend de l'API.
  9. Obtenez l'adresse IP externe du service. Consultez la section Obtenir l'adresse IP externe.
  10. Envoyez une requête à l'API via une adresse IP. Consultez la section Envoyer une requête à l'aide d'une adresse IP.
  11. Suivez l'activité de l'API. Consultez la section Suivre l'activité de l'API.

Partie 2

  1. Configurez un enregistrement DNS pour l'exemple d'API. Consultez la section Configurer le DNS pour Endpoints.
  2. Envoyez une requête à l'API en utilisant le nom de domaine. Consultez la section Envoyer une requête à l'aide du nom de domaine complet.

Nettoyage

Lorsque vous avez terminé, consultez la section Nettoyage pour éviter des frais sur votre compte Google Cloud.

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

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

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Assurez-vous que la facturation est activée pour votre projet 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.

Installer et configurer le logiciel requis

Dans ce tutoriel, vous allez installer le SDK Cloud afin de pouvoir gérer votre projet à l'aide de l'interface de ligne de commande gcloud. Vous allez utiliser kubectl, une interface de ligne de commande permettant d'exécuter des commandes sur les clusters Kubernetes. Vous aurez également besoin d'un moyen de tester l'API.

Dans la procédure suivante, si le logiciel requis est déjà installé, passez à l'étape suivante.

Pour installer et configurer le logiciel requis :

  1. Vous aurez besoin d'une application pour envoyer des requêtes à l'exemple d'API.

    • Utilisateurs Linux et macOS : ce tutoriel fournit un exemple utilisant curl, qui est généralement préinstallé sur votre système d'exploitation. Si vous ne disposez pas de curl, vous pouvez le télécharger sur la page Releases and Downloads de curl.
    • Utilisateurs Windows : ce tutoriel fournit un exemple d'utilisation de Invoke-WebRequest, compatible avec PowerShell 3.0 et versions ultérieures.
  2. Installez et initialisez le SDK Cloud.
  3. Mettez à jour le SDK Cloud et installez les composants Endpoints :
    gcloud components update
  4. Assurez-vous que le SDK Cloud (gcloud) est autorisé à accéder à vos données et services sur Google Cloud :
    gcloud auth login
    Dans le nouvel onglet qui s'ouvre, sélectionnez un compte.
  5. 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.

  6. Installez kubectl :
    gcloud components install kubectl
  7. Procurez-vous de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application. Les identifiants utilisateur autorisent kubectl.
    gcloud auth application-default login
  8. Dans le nouvel onglet qui s'ouvre, choisissez un compte.
  9. Exécutez la commande suivante pour vous assurer que le client Kubernetes est correctement configuré :
    kubectl version

    Un résultat semblable aux lignes suivantes doit s'afficher :

       Client Version: version.Info{Major:"1", Minor:"8", GitVersion:"v1.8.4",
         GitCommit:"9befc2b8928a9426501d3bf62f72849d5cbcd5a3", GitTreeState:"clean",
         BuildDate:"2017-11-20T05:28:34Z", GoVersion:"go1.8.3", Compiler:"gc",
         Platform:"linux/amd64"}
       Server Version: version.Info{Major:"1", Minor:"7+",
         GitVersion:"v1.7.8-gke.0",
         GitCommit:"a7061d4b09b53ab4099e3b5ca3e80fb172e1b018", GitTreeState:"clean",
         BuildDate:"2017-10-10T18:48:45Z", GoVersion:"go1.8.3", Compiler:"gc",
         Platform:"linux/amd64"}
       

Télécharger l'exemple de code

Téléchargez l'exemple de code (facultatif). Dans ce tutoriel, vous allez déployer une image de conteneur prédéfinie. Vous n'avez donc pas besoin de créer un conteneur à partir de l'exemple de code. Toutefois, vous souhaiterez peut-être télécharger l'exemple de code, disponible dans plusieurs langues, pour mieux comprendre le fonctionnement de l'exemple d'API.

Pour télécharger l'exemple de code :

Java

Pour cloner ou télécharger l'exemple d'API :

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :
    cd java-docs-samples/endpoints/getting-started
Python

Pour cloner ou télécharger l'exemple d'API :

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    git clone https://github.com/GoogleCloudPlatform/python-docs-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :
    cd python-docs-samples/endpoints/getting-started
Go

Pour cloner ou télécharger l'exemple d'API :

  1. Assurez-vous que la variable d'environnement GOPATH est définie.
  2. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    go get -u -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
  3. Accédez au répertoire qui contient l'exemple de code :
    cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
PHP

Pour cloner ou télécharger l'exemple d'API :

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    git clone https://github.com/GoogleCloudPlatform/php-docs-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :
    cd php-docs-samples/endpoints/getting-started
Ruby

Pour cloner ou télécharger l'exemple d'API :

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :
    cd ruby-docs-samples/endpoints/getting-started
NodeJS

Pour cloner ou télécharger l'exemple d'API :

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire qui contient l'exemple de code :
    cd nodejs-docs-samples/endpoints/getting-started

Obtenir le fichier de configuration Kubernetes

  1. Clonez le dépôt GitHub contenant les fichiers yaml utilisés dans ce tutoriel sur votre machine locale :

     git clone https://github.com/googlecloudplatform/endpoints-samples

    Vous pouvez également télécharger l'exemple sous forme de fichier zip et l'extraire.

  2. Accédez au répertoire contenant les fichiers de configuration :

     cd endpoints-samples/kubernetes

Configurer Endpoints

L'exemple de code inclut le fichier de configuration OpenAPI openapi.yaml basé sur la spécification OpenAPI version 2.0. Pour configurer Cloud Endpoints :

  1. Dans le répertoire de l'exemple de code, ouvrez le fichier de configuration openapi.yaml.

    swagger: "2.0"
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    host: "echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog"

    Veuillez noter les points suivants :

    • L'exemple de configuration affiche les lignes situées à proximité du champ host que vous devez modifier. Pour déployer le fichier openapi.yaml sur Endpoints, vous devez disposer du document OpenAPI complet.
    • L'exemple de fichier openapi.yaml contient une section sur la configuration de l'authentification qui n'est pas nécessaire pour ce tutoriel. Vous n'avez pas besoin de configurer les lignes avec YOUR-SERVICE-ACCOUNT-EMAIL et YOUR-CLIENT-ID.
    • OpenAPI est une spécification indépendante du langage. Pour plus de commodité, le même fichier openapi.yaml figure dans l'exemple getting-started sur le dépôt GitHub de chaque langage.
  2. Dans le champ host, remplacez le texte par le nom du service Endpoints, qui doit être au format suivant :
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    

    Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud. Exemple :

    host: "echo-api.endpoints.example-project-12345.cloud.goog"
    

echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog est le nom du service Endpoints. Ce n'est pas le nom de domaine complet (FQDN) que vous utilisez pour envoyer des requêtes à l'API.

Pour plus d'informations sur les champs du document OpenAPI requis par Endpoints, consultez la page Configurer Endpoints.

Une fois que vous avez terminé toutes les étapes de configuration suivantes pour pouvoir envoyer des requêtes à l'exemple d'API à l'aide d'une adresse IP, consultez la section Configurer le DNS pour Endpoints afin d'obtenir des informations sur la configuration pour utiliser echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog en tant nom de domaine complet.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, exécutez la commande gcloud endpoints services deploy. Celle-ci crée un service géré à l'aide de Service Management.

Pour déployer la configuration Endpoints :

  1. Assurez-vous que vous vous trouvez dans le répertoire endpoints-samples/kubernetes.
  2. Importez la configuration et créez un service géré :
    gcloud endpoints services deploy openapi.yaml
    

La commande gcloud appelle ensuite l'API Service Management pour créer un service géré avec le nom que vous avez spécifié dans le champ host du fichier openapi.yaml. Service Management configure le service en fonction des paramètres du fichier openapi.yaml. Lorsque vous apportez des modifications au fichier openapi.yaml, vous devez le redéployer pour mettre à jour le service Endpoints.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Vous pouvez ignorer en toute sécurité les avertissements concernant les chemins du fichier openapi.yaml qui ne nécessitent pas de clé d'API. Une fois la configuration du service terminée, Service Management affiche un message avec l'ID de configuration du service et le nom du service, comme illustré ci-dessous :

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Dans l'exemple ci-dessus, 2017-02-13r0 correspond à l'ID de configuration du service et echo-api.endpoints.example-project-12345.cloud.goog au service Endpoints. L'ID de configuration du service se compose d'un horodatage, suivi d'un numéro de révision. Si vous déployez à nouveau le fichier openapi.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 de service Endpoints sur la page Endpoints > Services de Cloud Console.

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.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.

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, Compute Engine ou l'environnement flexible App 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, tel que votre ordinateur local, un cluster Kubernetes sur site ou un autre fournisseur cloud, vous devez fournir unfichier JSON du compte de service contenant une clé privée. ESP et ESPv2 utilisent le compte de service pour générer des jetons d'accès, afin d'appeler les services nécessaires à la gestion de votre API.

Vous pouvez utiliser Cloud Console ou l'outil de ligne de commande gcloud pour créer le compte de service et le fichier de clé privée, ainsi que pour attribuer au compte de service les rôles suivants :

Console

  1. Dans Cloud Console, accédez à 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. Sélectionnez le compte de service que vous venez de créer, cliquez sur le menu Action à droite, puis sur son élément de menu Créer une clé.
  10. Dans le panneau contextuel "Créer une clé privée", sélectionnez le type de clé, et utilisez le type par défaut : JSON.
  11. Cliquez sur Créer.

Le compte de service est alors créé, et sa clé privée est téléchargée dans un fichier JSON.

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 le SDK Cloud (gcloud) est autorisé à 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 :

Les rôles IAM suivants sont requis pour le compte de service qu'utilisent ESP et ESPv2.

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. Ouvrez la page IAM/Iam.

    Accéder à la page IAM/Iam

    Cette page devrait répertorier tous les membres IAM, comptes de service compris.
  3. Sélectionnez votre compte de service, puis cliquez sur l'icône Modifier en forme d'épingle, située à 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?

See
[`gcloud iam service-accounts`](/sdk/gcloud/reference/iam/service-accounts/){: track-type="tutorial" track-name="internalLink" track-metadata-position="body" }
for more information about the commands.

Déployer le backend de l'API

Vous avez déployé le document OpenAPI sur Service Management, mais vous n'avez pas encore déployé le code qui diffuse 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.

Vérifier les autorisations requises

Accordez les autorisations requises au compte de service associé à votre cluster :

gcloud projects add-iam-policy-binding PROJECT_NAME \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/servicemanagement.serviceController

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

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 permettre au proxy ESPv2 d'accéder à ces identifiants, créez un secret Kubernetes et installez-le en tant que volume Kubernetes.

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

  1. Veillez à renommer le fichier JSON en service-account-creds.json et à le copier dans endpoints-samples/kubernetes s'il a été téléchargé dans un autre répertoire. De cette façon, le nom correspond aux options spécifiées dans le fichier manifeste de déploiement echo.yaml.
  2. Assurez-vous que vous vous trouvez dans le répertoire endpoints-samples/kubernetes.
  3. Créez un secret Kubernetes avec les identifiants du compte de service à l'aide de la commande suivante :

    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. Ouvrez le fichier manifeste de déploiement, echo.yaml, et remplacez SERVICE_NAME dans les options de démarrage ESPv2 par le nom du service. Il s'agit du nom que vous avez configuré dans le champ host du document OpenAPI. Exemple :

    "--service=echo-api.endpoints.example-project-12345.cloud.goog"
    containers:
    - name: esp
      image: gcr.io/endpoints-release/endpoints-runtime:2
      args: [
        "--listener_port=8080",
        "--backend=127.0.0.1:8081",
        "--service=SERVICE_NAME",
        "--rollout_strategy=managed",
        "--non_gcp",
        "--service_account_key=/etc/esp/creds/service-account-creds.json"
      ]
      ports:
        - containerPort: 8080
      volumeMounts:
        - mountPath: /etc/esp/creds
          name: service-account-creds
          readOnly: true
    - name: echo
      image: gcr.io/endpoints-release/echo:latest
      ports:
        - containerPort: 8081
    

    L'option "--rollout_strategy=managed" configure ESPv2 afin d'utiliser 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 autres options à utiliser avec ESPv2, consultez la section Options de démarrage d'ESPv2.

  2. Démarrez le service pour déployer le service Endpoints sur Kubernetes à l'aide de la commande suivante :

    kubectl create -f echo.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. Pour plus d'informations, consultez la section Déployer Endpoints sur Kubernetes.

Obtenir l'adresse IP externe du service

Si vous utilisez Minikube, passez à la section Envoyer une requête à l'aide d'une adresse IP. Après le démarrage du service dans le conteneur, il peut parfois s'écouler quelques minutes avant que l'adresse IP externe ne soit prête.

Pour afficher l'adresse IP externe du service :

  1. Exécutez la commande suivante :

    kubectl get service

  2. Notez la valeur de EXTERNAL-IP. Vous vous servirez de cette adresse IP pour envoyer une requête à l'exemple d'API.

Envoyer une requête à l'aide d'une adresse IP

Une fois que l'exemple d'API est exécuté dans le cluster de conteneurs, vous pouvez envoyer des requêtes à l'API.

Créer une clé API et définir une variable d'environnement

L'exemple de code nécessite une clé API. Pour simplifier la requête, définissez une variable d'environnement pour la clé API.

  1. Dans le projet Google Cloud utilisé pour l'API, créez une clé API depuis la page des identifiants de l'API. Si vous souhaitez créer une clé API dans un autre projet Google Cloud, consultez la page Activer une API dans votre projet Google Cloud.

    Accéder à la page Identifiants

  2. Cliquez sur Créer les identifiants, puis sélectionnez Clé API.
  3. Copiez la clé dans le presse-papier.
  4. Cliquez sur Fermer.
  5. Sur l'ordinateur local, collez la clé API pour l'attribuer à une variable d'environnement :
    • Sous Linux ou macOS : export ENDPOINTS_KEY=AIza...
    • Dans Windows PowerShell : $Env:ENDPOINTS_KEY="AIza..."

Envoyer la requête à minikube

Les commandes suivantes utilisent la variable d'environnement ENDPOINTS_KEY que vous avez définie précédemment.

Linux ou macOS

NODE_PORT=`kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}'`
MINIKUBE_IP=`minikube ip`
curl --request POST \
    --header "content-type:application/json" \
    --data '{"message":"hello world"}' \
    ${MINIKUBE_IP}:${NODE_PORT}/echo?key=${ENDPOINTS_KEY}

PowerShell

$Env:NODE_PORT=$(kubectl get service esp-echo --output='jsonpath={.spec.ports[0].nodePort}')
$Env:MINIKUBE_IP=$(minikube ip)
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://$Env:MINIKUBE_IP:$Env:NODE_PORT/echo?key=$Env:ENDPOINTS_KEY").Content

Envoyer la requête à d'autres clusters Kubernetes

Linux ou macOS

Utilisez curl pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_KEY définie précédemment. Remplacez IP_ADDRESS par l'adresse IP externe de l'instance.

curl --request POST \
   --header "content-type:application/json" \
   --data '{"message":"hello world"}' \
   "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"

Dans la commande curl ci-dessus :

  • L'option --data indique les données à publier sur l'API.
  • L'option --header indique que les données sont au format JSON.

PowerShell

Utilisez Invoke-WebRequest pour envoyer une requête HTTP à l'aide de la variable d'environnement ENDPOINTS_KEY définie précédemment. Remplacez IP_ADDRESS par l'adresse IP externe de l'instance.

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").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 l'extension Postman du navigateur Chrome pour envoyer la requête :

  • Sélectionnez POST comme verbe HTTP.
  • Pour l'en-tête, sélectionnez la clé content-type et la valeur application/json.
  • Pour le corps, saisissez ce qui suit :
    {"message":"hello world"}
  • Dans l'URL, utilisez la clé API réelle plutôt que la variable d'environnement. Par exemple :
    http://192.0.2.0:80/echo?key=AIza...

L'API renvoie le message que vous lui avez envoyé et répond avec les éléments suivants :

{
  "message": "hello world"
}

Si vous ne recevez pas de réponse positive, consultez la section 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

Pour suivre l'activité de l'API :

  1. Examinez les graphiques d'activité de l'API dans la page Endpoints > Services.

    Accédez à la page Services 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.

    Accéder à la page Visionneuse de journaux

Configurer le DNS pour Cloud Endpoints

Comme le nom du service Endpoints pour l'API se trouve dans le domaine .endpoints.YOUR_PROJECT_ID.cloud.goog, vous pouvez l'utiliser comme nom de domaine complet en modifiant légèrement la configuration de votre fichier openapi.yaml. De cette façon, vous pouvez envoyer des requêtes à l'exemple d'API à l'aide de echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog au lieu de l'adresse IP.

Pour configurer le DNS Endpoints :

  1. Ouvrez le fichier de configuration OpenAPI openapi.yaml, puis ajoutez la propriété x-google-endpoints au niveau supérieur du fichier (elle ne doit pas être en retrait ni imbriquée), comme indiqué dans l'extrait suivant :
    host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
    x-google-endpoints:
    - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
      target: "IP_ADDRESS"
    
  2. Dans la propriété name, remplacez YOUR_PROJECT_ID par l'ID de votre projet.
  3. Dans la propriété target, remplacez IP_ADDRESS par l'adresse IP que vous avez utilisée lorsque vous avez envoyé une requête à l'exemple d'API.
  4. Déployez le fichier de configuration OpenAPI mis à jour sur Service Management :
    gcloud endpoints services deploy openapi.yaml
    

Par exemple, supposons que le fichier openapi.yaml ait la configuration suivante :

host: "echo-api.endpoints.example-project-12345.cloud.goog"
x-google-endpoints:
- name: "echo-api.endpoints.example-project-12345.cloud.goog"
  target: "192.0.2.1"

Lorsque vous déployez le fichier openapi.yaml à l'aide de la commande gcloud ci-dessus, Service Management crée un enregistrement A DNS, echo-api.endpoints.my-project-id.cloud.goog, qui est associé à l'adresse IP cible 192.0.2.1. La propagation de la nouvelle configuration DNS peut prendre quelques minutes.

Configurer SSL

Pour plus d'informations sur la configuration DNS et SSL, consultez la section Activer SSL pour Endpoints.

Envoyer une requête au nom de domaine complet (FQDN)

Une fois que vous avez configuré l'enregistrement DNS pour l'exemple d'API, envoyez une requête à l'aide du nom de domaine complet (remplacez YOUR_PROJECT_ID par l'ID de projet) et de la variable d'environnement ENDPOINTS_KEY définie précédemment :
  • Sous Linux ou Mac OS :
    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
  • Dans Windows PowerShell :
    (Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content

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.

Nettoyer

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 les ressources individuelles.

  • Supprimez le service Kubernetes et son déploiement :
    kubectl delete -f echo.yaml

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