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à :

• installé Docker, si vous déployez le conteneur ESP en local ou sur une VM. Pour en savoir plus, consultez la section Installer Docker.

• déployé une API localement ou sur un hôte accessible à l'hôte sur lequel exécuter ESP ;

• configuré Cloud Endpoints et déployé la configuration pour créer un service géré pour votre API.

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 :

• virtualenv
• Google Cloud CLI
• curl

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. Mettre à jour gcloud CLI :

   gcloud components update

2. Assurez-vous que gcloud CLI (gcloud) est autorisée à 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 un fichier 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 la console Google Cloud ou Google Cloud CLI pour créer le compte de service et le fichier de clé privée:

Ajoutez les rôles IAM requis :

Cette section décrit les ressources IAM utilisées par ESP et ESPv2, ainsi que les rôles IAM requis pour que le compte de service associé puisse accéder à ces ressources.

Configuration du service de point de terminaison

ESP et ESPv2 appellent Service Control, qui utilise la configuration du service de point de terminaison. Celle-ci est une ressource IAM. ESP et ESPv2 ont besoin du rôle Contrôleur du service pour y accéder.

Le rôle IAM s'applique à la configuration du service de point de terminaison, et non au projet. Un projet peut posséder plusieurs configurations de service de point de terminaison.

Utilisez la commande gcloud suivante pour ajouter le rôle au compte de service associé pour la configuration du service de point de terminaison.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Où
* SERVICE_NAME est le nom du service de point de terminaison ;
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com est le compte de service associé.

Cloud Trace

ESP et ESPv2 appellent le service Cloud Trace pour exporter Trace vers un projet. Ce projet est appelé projet de traçage. Dans ESP, le projet de traçage et le projet propriétaire de la configuration du service de point de terminaison sont identiques. Dans ESPv2, le projet de traçage peut être spécifié par l'option --tracing_project_id, et est défini par défaut sur le projet de déploiement.

ESP et ESPv2 nécessitent le rôle Agent Cloud Trace pour activer Cloud Trace.

Exécutez la commande gcloud suivante pour ajouter le rôle au compte de service associé :

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Où
* TRACING_PROJECT_ID est l'ID du projet de traçage ;
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.comest le compte de service associé. Pour en savoir plus, consultez la page Que sont les rôles et les autorisations ?

Pour en savoir plus sur les commandes, consultez la page gcloud iam service-accounts.

Exécuter ESP dans un conteneur

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

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

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.

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
  

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
  

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.

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 :

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 :

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

Étape suivante

• Découvrez comment ajouter le protocole SSL à ESP.