Implementa el backend de la API

OpenAPI  |  gRPC

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.

Si bien 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 el nombre de servicio y una opción que configura el ESP para que use la configuración más reciente del servicio de Cloud Endpoints que se implementó. 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.

Nota: El proxy de servicio extensible V2 (ESPv2) también se puede implementar en GKE y Kubernetes. El ESPv2 no es compatible con el entorno flexible de App Engine.

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.

1. Crea, configura y luego inicia la instancia de VM. Consulta la Documentación de Compute Engine.
2. 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.
3. Crea un contenedor de Docker para tu código de servidor de backend. Consulta la documentación de Cloud Build.
4. Envía el contenedor a Artifact Registry o a otro registro.
5. 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, los alcances de OAuth que se otorgan a la cuenta de servicio del clúster incluyen los siguientes alcances que requiere Endpoints:

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

1. 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:
   1. Empaqueta tu aplicación en una imagen de Docker.
   2. Sube la imagen a un registro.
   3. Crea un clúster de contenedor.
   4. Implementa tu aplicación en el clúster.
   5. Expón tu aplicación en Internet.
2. 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:

1. Obtén el nombre de servicio de tu API. Este es el nombre que especificaste en el campo host de tu documento de OpenAPI.
2. Edita el archivo app.yaml y agrega una sección llamada endpoints_api_service que contenga el nombre del servicio. Puedes usar el archivo app.yaml del instructivo como modelo:
   Java

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Python

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Go

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   PHP

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
     # previously run the deploy command, you can list your existing configuration
     # ids using the 'configs list' command as follows:
     #
     #     gcloud endpoints configs list --service=YOUR-PROJECT-ID.appspot.com
     #
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   Ruby

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   NodeJS

   endpoints_api_service:
     # The following values are to be replaced by information from the output of
     # 'gcloud endpoints services deploy openapi-appengine.yaml' command.
     name: ENDPOINTS-SERVICE-NAME
     rollout_strategy: managed

   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 archivo app.yaml.

3. Guarda el o los archivos app.yaml.
4. 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:

1. En la sección endpoints_api_service de tu archivo app.yaml, agrega el campo config_id y configúralo como un ID de configuración específico.
2. Quita rollout_strategy: managed o configura rollout_strategy como fixed. La opción fixed configura el ESP para que use la configuración de servicio que especificaste en config_id.
3. 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:

1. Quita la opción config_id del archivo app.yaml.
2. Agrega la opción rollout_strategy: managed.
3. 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:

1. Conéctate a tu instancia de VM. Reemplaza INSTANCE_NAME por el nombre de tu instancia de VM.

   gcloud compute ssh INSTANCE_NAME

2. Crea tu propia red de contenedores llamada esp_net de la manera siguiente:

   sudo docker network create --driver bridge esp_net

3. 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.
4. Obtén el nombre de servicio de tu API. Este es el nombre que especificaste en el campo host de tu documento de OpenAPI.
5. 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.

Si necesitas configurar el ESP para que use un ID de configuración específico, haz lo siguiente:

1. Incluye la opción --version y configúrala con un ID de configuración específico.
2. Quita la opción --rollout_strategy=managed o configura --rollout_strategy como fixed. La opción fixed configura el ESP para que use la configuración de servicio que especificaste en --version.
3. 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:

1. En las marcas del ESP para docker run, quita la opción --version.
2. Agrega la opción --rollout_strategy=managed.
3. 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:

1. Obtén el nombre de servicio de tu API (el nombre que especificaste en el campo host de tu documento de OpenAPI).
2. 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.

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

1. En tu archivo de manifiesto de implementación, agrega la opción --version y configúrala con un ID de configuración específico.
2. Quita --rollout_strategy=managed o configura --rollout_strategy como fixed. La opción fixed configura el ESP para que use la configuración de servicio que especificaste en --version.
3. 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:

1. En tu archivo de manifiesto de implementación, quita la opción --version.
2. Agrega --rollout_strategy=managed.
3. 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.
  

  Ir a la página Explorador de registros

¿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