En esta página, se explica cómo implementar el código de backend de tu API y el proxy de servicio extensible (ESP) en Google Kubernetes Engine, Compute Engine y el entorno flexible de App Engine.
Aunque los pasos de implementación varían según la plataforma que aloja tu API, siempre hay un paso en el que proporcionas al ESP nombre del servicio y una opción que configura el ESP para que use el último Configuración del servicio de Cloud Endpoints. Con esta información, mediante el ESP se obtiene la configuración de Endpoints de tu API y se almacenan en servidores proxy las solicitudes y respuestas para que en Endpoints se pueda administrar tu API.
Requisitos previos
Como punto de partida, en esta página se supone que ya:
- Creaste un proyecto de Google Cloud.
- Configuraste Endpoints.
- Implementaste la configuración de Endpoints.
Cómo prepararse para la implementación
App Engine
Con la adición de un pequeño paso de configuración (descrito en los pasos siguientes), la implementación de tu API para que sea administrada por Endpoints es igual que la implementación de cualquier aplicación en el entorno flexible de App Engine. Sigue la documentación de App Engine para:
- Organizar tus archivos de configuración
- Crear el archivo de configuración
app.yaml
- Si tu aplicación se basa en microservicios, consulta la documentación para implementar aplicaciones de varios servicios a fin de obtener información sobre cómo configurar los archivos
app.yaml
para cada servicio
Para implementar tu API en App Engine, usa el comando de gcloud app deploy
. Este comando compila de forma automática una imagen del contenedor con el servicio de Container Builder y, luego, la implementa en tu entorno flexible de App Engine.
Antes de realizar la implementación, debe suceder lo siguiente:
- El propietario del proyecto de Google Cloud debe crear la aplicación de App Engine.
- Asegúrate de que tu cuenta de usuario incluya los privilegios necesarios.
Compute Engine
A fin de que en Endpoints se administre tu API, debes instalar y configurar el ESP, así como el código de servidor de backend para tu API. Necesitas instalar Docker en tu instancia de VM de Compute Engine para poder ejecutar la imagen gratuita del ESP de Docker en Artifact Registry.
Antes de realizar la implementación, debe suceder lo siguiente:
A continuación, se describen en un alto nivel los pasos que debes realizar antes de implementar tu API y el ESP en Compute Engine. Por lo general, realizas todos los pasos que sigues normalmente para ejecutar tu código de servidor de backend en Compute Engine.
- Crea, configura y luego inicia la instancia de VM. Consulta la Documentación de Compute Engine.
- Instala la edición empresarial (EE) o la edición la comunidad (CE) de Docker en la instancia de VM. Consulta Cómo instalar Docker.
- Crea un contenedor de Docker para tu código de servidor de backend. Consulta la documentación de Cloud Build.
- Envía el contenedor a Artifact Registry o algún otro registro.
- Asegúrate de que puedas realizar las acciones siguientes sin problemas:
- Conectarte a la instancia de VM
- Ejecutar la imagen de Docker para iniciar tu servidor de Backend en la instancia de VM. Consulta la Referencia de ejecución de Docker
- Enviar solicitudes a tu API.
GKE
Cuando creas un clúster en la consola de Google Cloud, de forma predeterminada, el Los permisos de OAuth que se otorgan a la cuenta de servicio del clúster incluyen el permisos que Endpoints requiere:
- Control de servicios: habilitado
- Service Management: Solo lectura
Cuando crees un clúster con el comando de gcloud container clusters create
o mediante un archivo de configuración de terceros, asegúrate de especificar los siguientes alcances:
"https://www.googleapis.com/auth/servicecontrol"
"https://www.googleapis.com/auth/service.management.readonly"
Para obtener más información, consulta ¿Qué son los alcances de acceso?
Antes de realizar la implementación, debe suceder lo siguiente:
Si agregas una pequeña sección a tu archivo de manifiesto de implementación, puedes ejecutar la imagen de Docker del ESP en los clústeres de tu contenedor junto con la aplicación en contenedores. A continuación, se describen en un alto nivel los pasos que debes realizar antes de implementar tu API con el ESP en GKE. Por lo general, realizas todos los pasos que sigues normalmente para ejecutar tu código de servidor de backend en GKE.
- Implementa la aplicación en contenedores en los clústeres del contenedor. Los pasos generales que se describen en la documentación de GKE son los siguientes:
- Empaqueta tu aplicación en una imagen de Docker.
- Sube la imagen a un registro.
- Crea un clúster de contenedor.
- Implementa tu aplicación en el clúster.
- Expón tu aplicación en Internet.
- Asegúrate de que puedas realizar las siguientes acciones sin problemas:
- Iniciar el servidor de tu API
- Enviar solicitudes a tu API.
Cómo implementar tu API y ESP
App Engine
Para implementar tu API y el ESP en App Engine, haz lo siguiente:
- Obtén el nombre de servicio de tu API. Este es el nombre que especificaste en el campo
host
de tu documento de OpenAPI. - Edita el archivo
app.yaml
y agrega una sección llamadaendpoints_api_service
que contenga el nombre del servicio. Puedes usar el archivoapp.yaml
del instructivo como modelo:Java Python Go PHP Ruby NodeJS Reemplaza
ENDPOINTS-SERVICE-NAME
por el nombre de servicio de tu API. Por ejemplo:endpoints_api_service: name: example-project-12345.appspot.com rollout_strategy: managed
La opción
rollout_strategy: managed
configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP.Si tu aplicación se basa en microservicios, debes incluir la sección
endpoints_api_service
en cada archivoapp.yaml
. - Guarda el o los archivos
app.yaml
. - Implementa tu código de backend y el ESP en App Engine con el siguiente comando:
gcloud app deploy
Debido a que agregaste la sección endpoints_api_service
al archivo app.yaml
, el comando gcloud app deploy
implementa y configura el ESP en un contenedor separado en tu entorno flexible de App Engine. Todo el tráfico de solicitudes se enruta a través del ESP, y procesa solicitudes y respuestas hacia y desde el contenedor que ejecuta tu código de servidor de backend.
Si necesitas configurar el ESP para que use un ID de configuración específico, haz lo siguiente:
- En la sección
endpoints_api_service
de tu archivoapp.yaml
, agrega el campoconfig_id
y configúralo como un ID de configuración específico. - Quita
rollout_strategy: managed
o configurarollout_strategy
comofixed
. La opciónfixed
configura el ESP para que use la configuración de servicio que especificaste enconfig_id
. - Vuelve a implementar tu API y el ESP con el siguiente comando:
gcloud app deploy
.
Te recomendamos que no configures el ESP para que use un ID de configuración específico durante mucho tiempo, ya que si implementas una configuración de servicio actualizada, debes reiniciar el ESP a fin de que use la configuración nueva.
Para quitar el ID de configuración específico, haz lo siguiente:
- Quita la opción
config_id
del archivoapp.yaml
. - Agrega la opción
rollout_strategy: managed
. - Ejecuta el comando
gcloud app deploy
.
Cuando uses la opción rollout_strategy: managed
, no incluyas config_id: YOUR_SERVICE_CONFIG_ID
en el archivo app.yaml
. Si lo haces, gcloud app deploy
produce el error siguiente:
config_id is forbidden when rollout_strategy is set to "managed".
Cuando implementas tu API al entorno de App Engine Flexible por primera vez, se pueden generar demoras mientras se configuran tu máquina virtual (VM) y otras infraestructuras. Si deseas obtener información adicional, consulta Garantizar una implementación exitosa en la documentación de App Engine.
Compute Engine
Para implementar tu API con el ESP en Compute Engine con Docker, haz lo siguiente:
- Conéctate a tu instancia de VM. Reemplaza
INSTANCE_NAME
por el nombre de tu instancia de VM.gcloud compute ssh INSTANCE_NAME
- Crea tu propia red de contenedores llamada
esp_net
de la manera siguiente:sudo docker network create --driver bridge esp_net
- Ejecuta una instancia de la imagen de tu código de servidor de backend y conéctala a la red de contenedores
esp_net
de la siguiente manera:sudo docker run \ --detach \ --name=YOUR_API_CONTAINER_NAME \ --net=esp_net \ gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0
- Reemplaza
YOUR_API_CONTAINER_NAME
con el nombre de tu contenedor. - Reemplaza
YOUR_PROJECT_ID
con el ID del proyecto de Google Cloud que usaste cuando enviaste la imagen. - Reemplaza
YOUR_IMAGE
por el nombre de tu imagen.
- Reemplaza
- Obtén el nombre de servicio de tu API. Este es el nombre que especificaste en el campo
host
de tu documento de OpenAPI. - Ejecuta una instancia de la imagen de Docker para el ESP de la siguiente manera:
sudo docker run \ --name=esp \ --detach \ --publish=80:8080 \ --net=esp_net \ gcr.io/endpoints-release/endpoints-runtime:1 \ --service=SERVICE_NAME \ --rollout_strategy=managed \ --backend=YOUR_API_CONTAINER_NAME:8080
- Reemplaza
SERVICE_NAME
por el nombre de tu servicio. - Reemplaza
YOUR_API_CONTAINER_NAME
con el nombre del contenedor de tu API.
La opción
--rollout_strategy=managed
configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP. - Reemplaza
Si necesitas configurar el ESP para que use un ID de configuración específico, haz lo siguiente:
- Incluye la opción
--version
y configúrala con un ID de configuración específico. - Quita la opción
--rollout_strategy=managed
o configura--rollout_strategy
comofixed
. La opciónfixed
configura el ESP para que use la configuración de servicio que especificaste en--version
. - Ejecuta el comando
docker run
nuevamente.
Si especificas --rollout_strategy=managed
y la opción --version
, el ESP se inicia con la configuración que especificaste en --version
, pero luego se ejecuta en modo administrado y se obtiene la configuración más reciente.
Te recomendamos que no configures el ESP para que use un ID de configuración específico durante mucho tiempo, ya que si implementas una configuración de servicio actualizada, debes reiniciar el ESP a fin de que use la configuración nueva.
Para quitar el ID de configuración específico, haz lo siguiente:
- En las marcas del ESP para
docker run
, quita la opción--version
. - Agrega la opción
--rollout_strategy=managed
. - Emite el comando
docker run
para reiniciar el ESP.
Consulta Opciones de inicio del ESP para ver la lista completa de opciones que puedes especificar cuando inicias el ESP.
GKE
Para implementar el ESP en GKE, haz lo siguiente:
- Obtén el nombre de servicio de tu API (el nombre que especificaste en el campo
host
de tu documento de OpenAPI). - Abre tu archivo de manifiesto de implementación (denominado archivo
deployment.yaml
) y agrega lo siguiente a la sección de contenedores:containers: - name: esp image: gcr.io/endpoints-release/endpoints-runtime:1 args: [ "--http_port=8081", "--backend=127.0.0.1:8080", "--service=SERVICE_NAME", "--rollout_strategy=managed" ]
Reemplaza
SERVICE_NAME
por el nombre de servicio de tu API.La opción
--rollout_strategy=managed"
configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración determinado para que lo utilice el ESP. - Inicia el servicio de Kubernetes con el siguiente comando kubectl create:
kubectl create -f deployment.yaml
Si necesitas configurar el ESP para que use un ID de configuración específico, haz lo siguiente:
- En tu archivo de manifiesto de implementación, agrega la opción
--version
y configúrala con un ID de configuración específico. - Quita
--rollout_strategy=managed
o configura--rollout_strategy
comofixed
. La opciónfixed
configura el ESP para que use la configuración de servicio que especificaste en--version
. - Inicia el servicio de Kubernetes con el siguiente comando:
kubectl create -f deployment.yaml
Si especificas --rollout_strategy=managed
y la opción --version
, el ESP se inicia con la configuración que especificaste en --version
, pero luego se ejecuta en modo administrado y se obtiene la configuración más reciente.
Te recomendamos que no configures el ESP para que use un ID de configuración específico durante mucho tiempo porque si implementas una configuración de servicio actualizada, debes reiniciar el ESP a fin de que use la configuración nueva.
Para quitar el ID de configuración específico, haz lo siguiente:
- En tu archivo de manifiesto de implementación, quita la opción
--version
. - Agrega
--rollout_strategy=managed
. - Inicia el servicio de Kubernetes:
kubectl create -f deployment.yaml
.
Consulta Opciones de inicio del ESP para ver la lista completa de opciones que puedes especificar cuando inicias el ESP.
Realice un seguimiento de la actividad de la API
Una vez que hayas implementado el ESP y el backend de tu API, puedes usar herramientas como curl
o Postman para enviar solicitudes a tu API. Si no obtienes una respuesta correcta, consulta Cómo solucionar errores de respuesta.
Luego de enviar algunas solicitudes, puedes hacer lo siguiente:
Observa los grafos de actividad de tu API en Endpoints > Servicios.
Ir a la página Servicios de Endpoints
La solicitud puede tardar unos momentos en reflejarse en los grafos.Consulta los registros de solicitudes de tu API en la página de Cloud Logging.
¿Qué sigue?
- Soluciona problemas en la implementación de App Engine Flexible
- Soluciona problemas de Cloud Endpoints en Compute Engine
- Soluciona problemas de Cloud Endpoints en GKE