Exécuter ESP 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 requiert les services de Service Infrastructure. Pour appeler ces services, le proxy ESP doit utiliser des jetons d'accès. Lorsque vous déployez ESP dans des environnements Google Cloud tels que GKE, Compute Engine ou l'environnement flexible App Engine, ESP obtient pour vous des jetons d'accès via le service de métadonnées Google Cloud.

Lorsque vous déployez ESP dans un environnement autre que Google Cloud, tel que votre ordinateur local, un cluster Kubernetes sur site ou un autre fournisseur cloud, vous devez lui fournir un fichier JSON de compte de service contenant une clé privée. Le proxy ESP utilise 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 Sélectionner un rôle, puis sélectionnez Service Management > Contrôleur des services.
  8. Cliquez sur + Ajouter un autre rôle.
  9. Cliquez sur Sélectionner un rôle, puis sélectionnez Cloud Trace > Agent Cloud Trace.
  10. Cliquez sur Continuer.
  11. Cliquez sur + Créer une clé.
  12. Dans le panneau de droite, dans le champ Type de clé, utilisez le type par défaut : JSON.
  13. Cliquez sur Créer.
  14. Dans la boîte de dialogue, cliquez sur Fermer.
  15. Cliquez sur OK.

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 celui 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 en remplaçant SERVICE_ACCOUNT_NAME par le nom que vous voulez utiliser et My Service Account par le nom à afficher  :

    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
        

    L'adresse e-mail est nécessaire pour les commandes suivantes.

  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
        
  6. 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
        
  7. 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 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 à suivre 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

  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 \
        --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 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 attribue au conteneur un nom facilement accessible. 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 macOS.
--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 de libellés, 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",
                  "--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 section 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
        

Envoi de 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