Exécuter ESP en local ou sur une autre plate-forme

OpenAPI | gRPC

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

Vous avez installé Docker si vous déployez le conteneur ESP en local ou sur une VM. Consultez la section Installer Docker pour plus d'informations.
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 :

Obtenir l'exemple de code

Clonez le dépôt de l'exemple d'application sur votre ordinateur local :
```
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
```
Accédez au répertoire qui contient l'exemple de code :
```
cd python-docs-samples/endpoints/getting-started
```

Configurer Endpoints

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"

Dans le champ host, remplacez YOUR-PROJECT-ID par votre ID de projet Google Cloud.

Important :Il doit s'agir du même projet que celui que vous avez sélectionné dans Créer le compte de service.
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.

Mettre à jour la CLI gcloud
```
gcloud components update
```
Assurez-vous que la 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.
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.

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

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
```
Démarrez le serveur :
```
python main.py
```
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, 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 la console Google Cloud ou la Google Cloud CLI pour créer le compte de service et le fichier de clé privée:

Console

Dans la console Google Cloud, ouvrez la page Comptes de service .
Accéder à la page "Comptes de service"
Cliquez sur Sélectionner un projet.
Sélectionnez le projet dans lequel votre API a été créée et cliquez sur Ouvrir.
Cliquez sur + Créer un compte de service.
Dans le champ Nom du compte de service, saisissez le nom de votre compte de service.
Cliquez sur Créer.
Cliquez sur Continuer.
Cliquez sur OK.
Cliquez sur l'adresse e-mail du compte de service que vous venez de créer.
Cliquez sur Clés.
Cliquez sur Add key (Ajouter une clé), puis sur Create new key (Créer une clé).
Cliquez sur Créer. Un fichier de clé JSON est téléchargé sur votre ordinateur.

Veillez à stocker le fichier de clé en toute sécurité, car il peut être utilisé pour s'authentifier en tant que compte de service. Vous pouvez déplacer et renommer ce fichier comme vous le souhaitez.
Cliquez sur Fermer.

`gcloud`

Saisissez la commande suivante pour afficher les ID de vos projets Google Cloud :
```
gcloud projects list
```
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
```
Important : Vous devez créer le compte de service dans le projet dans lequel se trouve l'API.
Assurez-vous que la Google Cloud CLI (gcloud) est autorisée à 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.
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.

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 :

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.com est le compte de service associé. Pour en savoir plus, consultez la page Comprendre les rôles.

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

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.
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 \
  --backend=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 \
  --backend=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 \
  --backend=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.

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

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",
          "--backend=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.

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 vérifier que le fichier du compte de service est correct et que les ports sont correctement mappés, envoyez des requêtes à votre API et assurez-vous qu'elles passent par ESP. Pour afficher les journaux ESP, exécutez la commande suivante:

sudo docker logs esp

Les exemples suivants envoient des requêtes à l'exemple d'API. Si vous n'utilisez pas l'exemple d'API, nous vous recommandons d'exécuter des tests similaires.

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

Solution :

  {
    "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

Solution :

  {
   "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 :

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

Accéder à la page Identifiants
Cliquez sur Créer les identifiants, puis sélectionnez Clé API.
Copiez la clé, puis collez-la dans l'instruction de la variable d'environnement suivante :
```
export KEY=AIza...
```

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.

Étapes suivantes

Découvrez comment ajouter le protocole SSL à ESP.