En esta página, se explica cómo configurar y ejecutar una instancia del proxy de servicio extensible (ESP) en una máquina local, en otro proveedor de servicios en la nube, como Amazon Web Services (AWS), o en un clúster de Kubernetes que no se ejecuta en Google Cloud.
Puedes ejecutar el ESP en una computadora Linux o macOS o en una máquina virtual (VM). Microsoft Windows no es compatible. Puedes implementar tu aplicación y el ESP en el mismo host o en hosts diferentes. Alojar una instancia local del ESP te permite hacer lo siguiente:
- Probar el ESP antes de implementarlo en una plataforma de producción
- Verificar que la configuración de seguridad esté configurada y funcione de forma correcta, además de que las métricas y los registros aparezcan en la página Endpoints > Servicios como se esperaba.
Requisitos previos
Como punto de partida, esta página supone lo siguiente:
Instalaste Docker. Si implementas el ESP contenedor de forma local o en una VM. Consulta Instala Docker para obtener más información.
Que implementaste una API de forma local o en un host accesible al host en el que ejecutarás el ESP.
Has configurado Cloud Endpoints y has implementado la configuración a fin de crear un servicio administrado para tu API.
Si necesitas una API para realizar pruebas con el ESP, puedes implementar y configurar el código de muestra en la sección Opcional: usa una API de muestra. Si ya implementaste y configuraste tu API, ve a Crea una cuenta de servicio.
Opcional: usa una API de muestra
En esta sección, se explica cómo implementar y configurar la versión de Python de
el
getting-started
para Endpoints
muestrear a nivel local. Sigue los pasos de esta sección solo si no tienes una API para realizar pruebas con el ESP.
La muestra getting-started
de Cloud Endpoints está disponible en otros lenguajes.
Consulta la página Muestras si quieres conocer la ubicación del GitHub para la muestra getting-started
en el lenguaje que prefieras. Sigue las instrucciones del archivo README.md
de la muestra para realizar la ejecución local. Luego, sigue las instrucciones de esta sección a fin de configurar Endpoints y, además, implementar la configuración.
Cómo obtener el software necesario
Si aún no configuraste un entorno de desarrollo de Python, consulta Cómo configurar un entorno de desarrollo de Python para obtener asesoramiento. Asegúrate de tener instalado lo siguiente:
Obtén el código de muestra
Clona el repositorio de la aplicación de muestra en tu máquina local con el siguiente comando:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
Ve al directorio que contiene el código de muestra:
cd python-docs-samples/endpoints/getting-started
Configura Endpoints
En el directorio de código de muestra, abre el archivo de configuración
openapi.yaml
.En el campo
host
, reemplazaYOUR-PROJECT-ID
con tu propio ID del proyecto de Google Cloud.Guarda el archivo
openapi.yaml
.
Implemente la configuración de Endpoints
Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy
. Este comando usa Service Management a fin de crear un servicio administrado.
Actualiza la CLI de gcloud:
gcloud components update
Asegúrate de que gcloud CLI (
gcloud
) esté autorizada para acceder a tus datos y servicios en Google Cloud:gcloud auth login
En la pestaña del navegador nueva que se abre, selecciona una cuenta.
Configura el proyecto predeterminado como el ID del proyecto de la manera siguiente:
gcloud config set project YOUR-PROJECT-ID
Reemplaza
YOUR-PROJECT-ID
con el ID del proyecto de Google Cloud que especificaste en el archivoopenapi.yaml
.Implementa tu configuración:
gcloud endpoints services deploy openapi.yaml
Service Management usa el texto que especificaste en el campo host
del archivo openapi.yaml
para crear un servicio de Endpoints nuevo con el nombre echo-api.endpoints.YOUR-PROJECT-ID.cloud.goog
(si no existe) y, luego, configura el servicio según tu archivo de configuración de OpenAPI.
A medida que se crea y configura el servicio, Service Management envía información a la terminal. Puedes ignorar las advertencias sin problemas sobre las rutas de acceso en el archivo openapi.yaml
que no requieren una clave de API. Cuando completas la tarea con éxito, una línea similar a la siguiente muestra el ID de configuración del servicio y el nombre del servicio entre corchetes:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
En el ejemplo anterior, 2017-02-13r0
es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog
es el nombre del servicio.
Inicia tu servidor local
Crea un
virtualenv
, actívalo y, luego, instala las dependencias de la aplicación.virtualenv env
source env/bin/activate
pip install -r requirements.txt
Inicia el servidor. Para esto, sigue los pasos siguientes:
python main.py
Abre otra ventana de la terminal y usa
curl
para enviar una solicitud de la manera siguiente:curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8080/echo
La API repite el mensaje que le enviaste y responde lo siguiente:
{ "message": "hello world" }
Crea una cuenta de servicio
A fin de proporcionar administración a tu API, el ESP y el ESPv2 requieren los servicios de la infraestructura del servicio. Para llamar a estos servicios, el ESP y el ESPv2 deben usar tokens de acceso. Cuando implementas el ESP o el ESPv2 Beta en entornos de Google Cloud, como GKE o Compute Engine, el ESP y el ESPv2 obtienen tokens de acceso mediante el servicio de metadatos de Google Cloud.
Cuando implementas el ESP o el ESPv2 en un entorno que no es de Google Cloud, como tu computadora de escritorio local, un clúster de Kubernetes local o cualquier otro proveedor de servicios en la nube, tienes que proporcionar un archivo JSON de la cuenta de servicio que contenga una clave privada. El ESP y el ESPv2 usan el cuenta de servicio para generar tokens de acceso y llamar a los servicios que necesita para administrar tu API.
Puedes usar la consola de Google Cloud o Google Cloud CLI para crear la cuenta de servicio y el archivo de claves privadas:
Console
- En la consola de Google Cloud, abre la página Cuentas de servicio .
- Haz clic en Seleccionar un proyecto.
- Selecciona el proyecto en el que creaste tu API y haz clic en Abrir.
- Haz clic en + Crear cuenta de servicio.
- En el campo Nombre de la cuenta de servicio, ingresa el nombre de tu cuenta de servicio.
- Haga clic en Crear.
- Haz clic en Continuar.
- Haz clic en Listo.
- Haz clic en la dirección de correo electrónico de la cuenta de servicio recién creada.
- Haga clic en Claves.
- Haz clic en Agregar clave, luego haz clic en Crear clave nueva.
Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.
Asegúrate de almacenar el archivo de claves de forma segura, ya que se puede usar para autenticarse como tu cuenta de servicio. Puedes mover y cambiar el nombre de este archivo como desees.
Haz clic en Cerrar.
gcloud
Ingresa lo siguiente para mostrar los ID de tus proyectos de Google Cloud:
gcloud projects list
Reemplaza PROJECT_ID en el comando siguiente para definir el proyecto predeterminado donde está tu API:
gcloud config set project PROJECT_ID
Asegúrate de que Google Cloud CLI (
gcloud
) esté autorizado para acceder a tus datos y servicios en Google Cloud:gcloud auth login
Si tienes más de una cuenta, asegúrate de elegir la que está en el proyecto de Google Cloud en el que se encuentra la API. Si ejecutas
gcloud auth list
, la cuenta que seleccionaste se muestra como la cuenta activa para el proyecto.Para crear una cuenta de servicio, ejecuta el comando siguiente y reemplaza SERVICE_ACCOUNT_NAME y
My Service Account
por el nombre y el nombre comercial que quieres usar:gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --display-name "My Service Account"
Con el comando, se asigna una dirección de correo electrónico para la cuenta de servicio en este formato:
SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Esta dirección de correo electrónico se requiere en los comandos posteriores.
Crea un archivo de claves de la cuenta de servicio:
gcloud iam service-accounts keys create ~/service-account-creds.json \ --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
Agrega las funciones requeridas de IAM:
En esta sección, se describen los recursos de IAM que usan el ESP y el ESPv2 y las funciones de IAM necesarias para que la cuenta de servicio conectada acceda a estos recursos.
Configuración del servicio de extremo
El ESP y el ESPv2 llaman al Control de servicios que usa la configuración del servicio de extremo. La configuración del servicio de extremo es un recurso de IAM, por lo que el ESP y el ESPv2 necesitan la función de Controlador de servicio para acceder a él.
La función de IAM se encuentra en la configuración del servicio de extremo, no en el proyecto. Un proyecto puede tener múltiples opciones de configuración de servicio de extremo.
Usa el siguiente comando de gcloud a fin de agregar la función a la cuenta de servicio conectada para la configuración del servicio de extremo.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
En el ejemplo anterior
* SERVICE_NAME
es el nombre del servicio de extremo
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
es la cuenta de servicio conectada
Cloud Trace
El ESP y el ESPv2 llaman al servicio de Cloud Trace para exportar Trace a un proyecto. Este proyecto se llama proyecto de seguimiento. En el ESP, el proyecto de seguimiento y el proyecto que posee la configuración del servicio de extremo son los mismos. En el ESPv2, el proyecto de seguimiento se puede especificar con la marca --tracing_project_id
y, de forma predeterminada, se establece el proyecto de implementación.
ESP y ESPv2 requieren el agente de Cloud Trace para habilitar Cloud Trace.
Usa el siguiente comando de gcloud para agregar la función a la cuenta de servicio conectada:
gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/cloudtrace.agent
Donde
* TRACING_PROJECT_ID es el ID del proyecto de seguimiento.
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
es la cuenta de servicio conectada.
Para obtener más información, consulta
¿Qué son los roles y los permisos?
Consulta gcloud iam service-accounts
para obtener más información sobre los comandos.
Ejecuta ESP en un contenedor
En esta sección, se describe cómo implementar el contenedor del ESP. El procedimiento que uses dependerá de las opciones siguientes para implementar el contenedor del ESP:
- Cómo ejecutar el ESP en un contenedor de Docker de forma local o en otra plataforma
- Ejecuta el ESP en un contenedor dentro de un clúster de Kubernetes
--http_port
solo funciona si el servicio gRPC tiene configurada la transcodificación HTTP/JSON. Para obtener más información, consulta Transcodificar HTTP/JSON a gRPC.
Ejecuta el ESP en un contenedor de Docker de forma local o en otra plataforma
Renombra el archivo JSON que contiene la clave privada para la cuenta de servicio a
service-account-creds.json
y cópialo en$HOME/Downloads/
, si se descargó en un directorio diferente. De esta forma, el nombre completo de la ruta de acceso coincide con el valor para--service_account_key
en el comando dedocker run
siguiente.En el comando siguiente de
docker run
, reemplazaYOUR_SERVICE_NAME
por el nombre de tu servicio.
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
mac OS
La opción --net="host"
de Docker no funciona en macOS.
En su lugar, debes realizar una asignación de puertos explícita del host al contenedor, en la que reemplaces --net="host"
por --publish 8082:8082
. También debes reemplazar localhost
por el nombre de DNS especial docker.for.mac.localhost
solo para macOS. Consulta la sección sobre casos prácticos y soluciones alternativas en la documentación de Docker para obtener más información.
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
Otra plataforma
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
En la siguiente tabla, se describen las opciones de Docker utilizadas en los comandos anteriores. Para obtener más información sobre las opciones del ESP que se usaron en el ejemplo, consulta Opciones de inicio del ESP.
Opción | Descripción |
---|---|
--detach
|
Esta opción de Docker inicia al contenedor en modo separado, así que se ejecuta en segundo plano. |
--name="esp"
|
Esta opción de Docker brinda al contenedor un nombre de fácil acceso.
Por ejemplo, para ver los registros del contenedor, puedes ejecutar docker logs esp . |
--net="host"
|
Esta opción indica que el contenedor de Docker usa la misma configuración de red que la máquina host, lo que le permite realizar llamadas al host local en la máquina host. Esta opción no funciona para ejecutar el ESP de manera local en macOS. |
--publish=8082:8082
|
En macOS, cuando quieras ejecutar el ESP de manera local, usa esta opción de Docker, en lugar de --net="host" , para hacer una asignación explícita de puertos desde el host hasta el contenedor. |
--volume= $HOME/Downloads:/esp
|
Con esta opción de Docker, se asigna tu directorio local $HOME/Downloads al directorio /esp en el contenedor. La opción del ESP --service_account_key usa esta asignación. |
Ejecuta el ESP en un contenedor dentro de un clúster de Kubernetes
En esta sección, se describe cómo implementar el ESP en un clúster de Kubernetes que no está en Google Cloud.
Para que Endpoints administre tu API, debes implementar el contenedor del ESP en el mismo pod de Kubernetes que el del contenedor de tu API. El conjunto de pods que ejecutan el ESP y tu API se agrupan en un servicio de Kubernetes mediante un selector de etiquetas, como app: my-api
. El servicio de Kubernetes especifica la política de acceso para balancear la carga de las solicitudes del cliente en el puerto del proxy.
Renombra el archivo JSON que contiene la clave privada para la cuenta de servicio a
service-account-creds.json
y cópialo en$HOME/Downloads/
, si se descargó en un directorio diferente. De este modo, el nombre completo de la ruta de acceso al directorio coincidirá con el comando en el paso siguiente.Ejecuta el comando siguiente para crear un secreto de Kubernetes y actívalo como un volumen de Kubernetes.
kubectl create secret generic service-account-creds \ --from-file=$HOME/Downloads/service-account-creds.json
Cuando el proceso finaliza con éxito, se muestra el mensaje siguiente:
secret "service-account-creds" created
En tu archivo de configuración de Kubernetes, agrega lo siguiente y reemplaza
YOUR_APP_NAME
por el nombre de tu API yYOUR_SERVICE_NAME
por el nombre de tu servicio.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
Para obtener más información sobre las opciones del ESP que se usaron en el ejemplo, consulta Opciones de inicio del ESP.
Implementa el ESP en Kubernetes. Reemplaza
YOUR_CONFIGURATION_FILE
por el nombre de tu archivo de configuración de Kubernetes.kubectl apply -f YOUR_CONFIGURATION_FILE
Envía solicitudes
Para confirmar que el archivo de la cuenta de servicio sea correcto y que los puertos estén bien asignados, envía algunas solicitudes a tu API y asegúrate de que pasen por el ESP. Puedes ver los registros del ESP si ejecutas el comando siguiente:
sudo docker logs esp
Los ejemplos siguientes envían solicitudes a la API de muestra. Si no usas la API de muestra, te recomendamos que ejecutes pruebas similares.
Configuraste el contenedor del ESP para recibir solicitudes en el puerto 8082
. Si envías una solicitud directo al servidor en http://localhost:8080
, la solicitud omite el ESP. Por ejemplo:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8080/echo
Respuesta:
{ "message": "hello world" }
Cuando envías una solicitud a http://localhost:8082
, que pasa por el ESP, y no envías una clave de API, el ESP rechaza la solicitud. Por ejemplo:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8082/echo
Respuesta:
{ "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" } ] }
Para probar la API con una clave de API, haz lo siguiente:
Crea una clave de API en la página Credenciales de API.
Haz clic en Crear credenciales y, luego, selecciona Clave de API.
Copia la clave y pégala en la declaración de variable de entorno siguiente:
export KEY=AIza...
Envía una solicitud con la clave:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ http://localhost:8082/echo?key=$KEY
Verás la respuesta siguiente que indica que el proceso se completó de forma correcta:
{ "message": "hello world" }
Realiza una limpieza
Apaga y quita el contenedor de Docker esp
con la herramienta de docker
de la manera siguiente:
sudo docker stop esp
sudo docker rm esp