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 déployez le proxy ESP, vous avez installé Docker. en local ou sur une VM. Voir Installer Docker pour en savoir plus.
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 vous explique comment configurer et déployer la version Python de
la
getting-started
pour Endpoints
en local. 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
.Dans le champ
host
, remplacezYOUR-PROJECT-ID
par votre ID de projet Google Cloud.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 fichieropenapi.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, que votre ordinateur local, un cluster Kubernetes sur site ou un autre vous devez fournir un fichier JSON de compte de service. contenant une clé privée. ESP et ESPv2 utilisent compte de service pour générer des jetons d'accès afin d'appeler les services dont il a besoin pour gérer 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 .
- 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
Assurez-vous que la Google Cloud CLI (
gcloud
) est autorisée à accéder à votre sur les données et services 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 l'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 plus d'informations, voir
Que sont les rôles et les autorisations ?
Voir
gcloud iam service-accounts
pour en savoir plus sur les commandes.
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 commandedocker run
suivante.Dans la commande
docker run
ci-dessous, remplacezYOUR_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 etYOUR_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 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 :
Créez une clé API sur la page Identifiants de l'API.
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
Une réponse indiquant que l'opération a réussi s'affiche:
{ "message": "hello world" }
Nettoyer
Arrêtez et supprimez le conteneur Docker esp
à l'aide de l'outil docker
:
Si vous souhaitez nettoyer la configuration de service déployée, consultez Supprimer une API et des instances d'APIsudo docker stop esp
sudo docker rm esp