Exécuter Extensible Service Proxy en local ou sur une autre plate-forme

Cette page explique comment configurer et exécuter une instance du proxy Extensible Service Proxy (ESP) sur une machine locale, sur un autre fournisseur cloud, tel qu'Amazon Web Services (AWS), ou sur un cluster Kubernetes qui ne figure pas sur Google Cloud.

Vous pouvez exécuter un proxy ESP sur un ordinateur Linux ou macOS, ou sur une machine virtuelle (VM). Microsoft Windows n'est pas compatible. Vous pouvez déployer votre application et le proxy ESP sur le même hôte ou sur des hôtes différents. L'hébergement d'une instance locale d'un ESP vous permet :

  • de tester un ESP avant de le déployer réellement sur une plate-forme de production ;
  • de vérifier que les paramètres de sécurité sont configurés et fonctionnent correctement, et que les métriques et les journaux apparaissent sur la page Endpoints > Services, comme prévu.

Prérequis

Pour commencer, nous partons du principe que vous avez déjà :

Si vous avez besoin d'une API pour effectuer des tests avec ESP, vous pouvez configurer et déployer l'exemple de code dans la section Facultatif : Utiliser un exemple d'API. Si vous avez déjà configuré et déployé votre API, passez à la section Créer un compte de service.

Facultatif : Utiliser un exemple d'API

Cette section décrit la procédure de configuration et de déploiement en local de la version Python de l'exemple getting-started pour Endpoints. Suivez les étapes décrites dans cette section seulement si vous ne disposez pas d'une API pour effectuer des tests avec ESP.

L'exemple getting-started de Cloud Endpoints est disponible dans d'autres langages. Consultez la page Exemples pour connaître l'emplacement GitHub de l'exemple getting-started dans le langage de votre choix. Suivez les instructions du fichier README.md de l'exemple pour une exécution locale, puis suivez les instructions de cette section pour configurer Endpoints et déployer la configuration.

Obtenir le logiciel requis

Si vous n'avez pas encore configuré d'environnement de développement Python, consultez la page Configurer un environnement de développement Python pour obtenir des conseils. Assurez-vous que les éléments suivants sont installés :

Obtenir l'exemple de code

  1. Clonez le dépôt de l'exemple d'application sur votre ordinateur local :

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples
    
  2. Accédez au répertoire qui contient l'exemple de code :

    cd python-docs-samples/endpoints/getting-started
    

Configurer 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"
  2. Dans le champ host, remplacez YOUR-PROJECT-ID par votre ID de projet Google Cloud.

  3. Enregistrez le fichier openapi.yaml.

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. Mettez à jour le SDK Cloud :

    gcloud components update
    
  2. 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 de navigateur, choisissez un compte.

  3. 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 Google Cloud que vous avez spécifié dans le fichier openapi.yaml.

  4. Déployez votre configuration :

    gcloud endpoints services deploy openapi.yaml
    

Service Management utilise le texte que vous avez spécifié dans le champ host du fichier openapi.yaml pour créer un service Endpoints avec le nom echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog (s'il n'existe pas), puis configure le service en fonction de votre fichier de configuration OpenAPI.

Lors de la création et de la configuration du service, Service Management transmet des informations au terminal. Vous pouvez ignorer en toute sécurité les avertissements indiquant que les chemins du fichier openapi.yaml ne nécessitent pas de clé API. Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration du service et le nom du service :

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 nom du service.

Démarrer votre serveur local

  1. Créez une instance virtualenv, activez-la, puis installez les dépendances de l'application.

    virtualenv env
    source env/bin/activate
    pip install -r requirements.txt
    
  2. Démarrez le serveur :

    python main.py
    
  3. Ouvrez une autre fenêtre de terminal et utilisez curl pour envoyer une requête :

    curl --request POST \
        --header "content-type:application/json" \
        --data '{"message":"hello world"}' \
        http://localhost:8080/echo
    

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

    {
      "message": "hello world"
    }
    

Créer un compte de 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, 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.

Exécuter ESP dans un conteneur

Cette section explique comment déployer le conteneur ESP. La procédure à suivre dépend de l'emplacement où vous déployez le conteneur ESP :

Dans les exemples suivants, l'option ESP --http_port ne fonctionne que si le transcodage de contenu HTTP/JSON en gRPC est configuré. Pour en savoir plus, consultez la page Transcoder du contenu HTTP/JSON en gRPC.

Exécuter localement ESP dans un conteneur Docker ou sur une autre plate-forme

  1. Remplacez le nom du fichier JSON contenant la clé privée du compte de service par service-account-creds.json, et copiez-le dans $HOME/Downloads/ s'il a été téléchargé dans un autre répertoire. De cette manière, le nom de chemin complet correspond à la valeur de --service_account_key dans la commande docker run suivante.

  2. Dans la commande docker run ci-dessous, remplacez YOUR_SERVICE_NAME par le nom de votre service.

Linux

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

macOS

L'option Docker --net="host" ne fonctionne pas sur macOS. Vous devez mapper explicitement le port de l'hôte au conteneur en remplaçant --net="host" par --publish 8082:8082. Vous devez également remplacer localhost par le nom DNS docker.for.mac.localhost, uniquement valable pour macOS. Pour en savoir plus, consultez la section Cas d'utilisation et solutions alternatives figurant dans la documentation Docker.

sudo docker run \
    --detach \
    --name="esp" \
    --publish=8082:8082 \
    --volume=$HOME/Downloads:/esp \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://docker.for.mac.localhost:8080 \
    --service_account_key=/esp/service-account-creds.json
  

Autre plate-forme

sudo docker run \
    --detach \
    --name="esp" \
    --net="host" \
    --volume=$HOME/Downloads:/esp \
    --publish=8082 \
    gcr.io/endpoints-release/endpoints-runtime:1 \
    --service=YOUR_SERVICE_NAME \
    --rollout_strategy=managed \
    --http_port=8082 \
    --http2_port=8083 \
    --backend=grpc://IP_Address:PORT \
    --service_account_key=/esp/service-account-creds.json
  

Le tableau suivant décrit les options Docker utilisées dans les commandes ci-dessus. Pour en savoir plus sur les options ESP utilisées dans l'exemple, consultez la section relative aux options de démarrage ESP.

Option Description
--detach Cette option Docker démarre le conteneur en mode dissociation et s'exécute donc en arrière-plan.
--name="esp" Cette option Docker fournit un nom qui permet d'accéder facilement au conteneur. Par exemple, pour afficher les journaux du conteneur, vous pouvez exécuter docker logs esp.
--net="host" Cette option Docker indique que le conteneur Docker utilise la même configuration réseau que pour la machine hôte, ce qui lui permet d'effectuer des appels à l'hôte local sur la machine hôte. Cette option ne fonctionne pas pour exécuter ESP sur une machine locale sous Mac OS.
--publish=8082:8082 Lorsque vous souhaitez exécuter ESP localement sur macOS, utilisez cette option Docker au lieu de --net="host" pour mapper explicitement le port de l'hôte au conteneur.
--volume=
$HOME/Downloads:/esp
Cette option Docker mappe votre répertoire local $HOME/Downloads au répertoire /esp du conteneur. Ce mappage est utilisé par l'option ESP --service_account_key.

Exécuter ESP dans un conteneur sur un cluster Kubernetes

Cette section décrit comment déployer ESP sur un cluster Kubernetes qui n'est pas sur Google Cloud.

Pour que votre API soit gérée par Endpoints, déployez le conteneur ESP sur le même pod Kubernetes que votre conteneur d'API. Les pods exécutant ESP et votre API sont regroupés dans un service Kubernetes à l'aide d'un sélecteur d'étiquettes, tel que app: my-api. Le service Kubernetes spécifie la règle d'accès pour équilibrer la charge des requêtes client sur le port du proxy.

  1. Remplacez le nom du fichier JSON contenant la clé privée du compte de service par service-account-creds.json, et copiez-le dans $HOME/Downloads/ s'il a été téléchargé dans un autre répertoire. De cette manière, le nom de chemin complet correspond à la commande de l'étape suivante.

  2. Exécutez la commande suivante pour créer un secret Kubernetes et l'installer en tant que volume Kubernetes.

    kubectl create secret generic service-account-creds \
    --from-file=$HOME/Downloads/service-account-creds.json
    

    Si l'opération réussit, le message suivant s'affiche : secret "service-account-creds" created

  3. Dans votre fichier de configuration Kubernetes, ajoutez ce qui suit en remplaçant YOUR_APP_NAME par le nom de votre API et YOUR_SERVICE_NAME par le nom de votre service.

    spec:
    replicas: 1
    template:
      metadata:
        labels:
          app: "YOUR_APP_NAME"
      spec:
        volumes:
          - name: service-account-creds
            secret:
              secretName: service-account-creds
              containers:
          - name: esp
            image: gcr.io/endpoints-release/endpoints-runtime:1
            args: [
              "--http_port=8082",
              "--http2_port=8083",
              "--backend=grpc://127.0.0.1:8081",
              "--service=YOUR_SERVICE_NAME",
              "--rollout_strategy=managed",
              "--service_account_key=/etc/nginx/creds/service-account-creds.json"
            ]
            ports:
              - containerPort: 8080
            volumeMounts:
              - mountPath: /etc/nginx/creds
                name: service-account-creds
                readOnly: true
    

    Pour en savoir plus sur les options ESP utilisées dans l'exemple, consultez la page Options de démarrage ESP.

  4. Déployez ESP sur Kubernetes. Remplacez YOUR_CONFIGURATION_FILE par le nom de votre fichier de configuration Kubernetes.

    kubectl apply -f YOUR_CONFIGURATION_FILE
    

Envoyer des requêtes

Pour confirmer que le fichier du compte de service est correct et que les ports sont mappés correctement, envoyez des requêtes à votre API et assurez-vous qu'elles passent par ESP. Vous pouvez afficher les journaux ESP en exécutant la commande suivante :

sudo docker logs esp

Dans les cas ci-dessous, des requêtes sont envoyées à l'exemple d'API. Si vous n'utilisez pas l'exemple d'API, nous vous recommandons d'effectuer des tests semblables.

Vous avez configuré le conteneur Docker pour recevoir des requêtes sur le port 8082. Si vous envoyez une requête directement au serveur à l'adresse http://localhost:8080, les requêtes contournent ESP. Exemple :

Requête :

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8080/echo

Réponse :

    {
      "message": "hello world"
    }

Lorsque vous adressez une requête à http://localhost:8082, qui passe par le proxy ESP, sans envoyer de clé API, ESP refuse la requête. Exemple :

Requête :

    curl --request POST \
      --header "content-type:application/json" \
      --data '{"message":"hello world"}' \
      http://localhost:8082/echo

Réponse :

    {
     "code": 16,
     "message": "Method doesn't allow unregistered callers (callers without
      established identity). Please use API Key or other form of API consumer
      identity to call this API.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "service_control"
      }
     ]
    }

Pour tester l'API avec une clé API :

  1. Créez une clé API sur la page Identifiants de l'API.

    Accéder à la page Identifiants

  2. Cliquez sur Créer les identifiants, puis sélectionnez Clé API.

  3. Copiez la clé, puis collez-la dans l'instruction de la variable d'environnement suivante :

    export KEY=AIza...
    
  4. Envoyez une requête avec la clé :

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

    Si l'opération réussit, vous obtenez la réponse suivante :

    {
      "message": "hello world"
    }
    

Nettoyer

Arrêtez et supprimez le conteneur Docker esp à l'aide de l'outil docker :

sudo docker stop esp
sudo docker rm esp

Si vous souhaitez nettoyer la configuration de service déployée, consultez la section Supprimer une API et des instances d'API.

Étape suivante