Desplegar el backend de la API

OpenAPI   |  gRPC

En esta página se explica cómo desplegar el código de backend de tu API y el Extensible Service Proxy (ESP) en Google Kubernetes Engine, Compute Engine y el entorno flexible de App Engine.

Aunque los pasos de implementación varían en función de la plataforma que aloje tu API, siempre hay un paso en el que proporcionas a ESP el nombre del servicio y una opción que configura ESP para que use la configuración del servicio Cloud Endpoints más reciente. Con esta información, ESP puede obtener la configuración de los endpoints de tu API, lo que le permite proxyizar solicitudes y respuestas para que Endpoints pueda gestionar tu API.

Nota: Extensible Service Proxy V2 (ESPv2) también se puede implementar en GKE y Kubernetes. ESPv2 no es compatible con el entorno flexible de App Engine.

Requisitos previos

Para empezar, en esta página se presupone que tienes lo siguiente:

• Ha creado un Google Cloud proyecto.
• Has configurado Endpoints.
• Desplegar la configuración de Endpoints.

Preparación para la implementación

App Engine

Si añades un pequeño paso de configuración (descrito en los pasos siguientes), desplegar tu API para que la gestione Endpoints es lo mismo que desplegar cualquier aplicación en el entorno flexible de App Engine. Sigue la documentación de App Engine para hacer lo siguiente:

• Organiza tus archivos de configuración.
• Crea el archivo de configuración app.yaml.
• Si tu aplicación se basa en microservicios, consulta la documentación sobre despliegue de varias aplicaciones de servicio para obtener información sobre cómo configurar los archivos app.yaml de cada servicio.

Para desplegar tu API en App Engine, usa el comando gcloud app deploy. Este comando compila automáticamente una imagen de contenedor mediante el servicio Container Builder y, a continuación, despliega esa imagen en tu entorno flexible de App Engine.

Antes de implementar:

• El propietario del Google Cloud proyecto debe crear la aplicación de App Engine.
• Asegúrate de que tu cuenta de usuario incluye los privilegios necesarios.

Compute Engine

Para que Endpoints gestione tu API, debes instalar y configurar ESP, así como el código del servidor backend de tu API. Debes instalar Docker en tu instancia de VM de Compute Engine para poder ejecutar la imagen Docker de ESP, que está disponible de forma gratuita en Artifact Registry.

Antes de implementar:

A continuación, se describen los pasos generales que debes seguir antes de poder desplegar tu API y ESP en Compute Engine. Por lo general, debes seguir todos los pasos que harías normalmente para ejecutar el código del servidor backend en Compute Engine.

1. Crea, configura e inicia tu instancia de VM. Consulta la documentación de Compute Engine.
2. Instala Docker Enterprise Edition (EE) o Docker Community Edition (CE) en tu instancia de VM. Consulta Instalar Docker.
3. Crea un contenedor Docker para el código de tu servidor backend. Consulta la documentación de Cloud Build.
4. Envía el contenedor a Artifact Registry u otro registro.
5. Asegúrate de que puedes hacer lo siguiente:
   • Conéctate a la instancia de VM.
   • Ejecuta la imagen de Docker para iniciar el servidor backend en la instancia de VM. Consulta la referencia de Docker run.
   • Envía solicitudes a tu API.

GKE

Cuando creas un clúster en la Google Cloud consola, de forma predeterminada, los permisos de OAuth que se conceden a la cuenta de servicio del clúster incluyen los permisos que requiere Endpoints:

• Control de servicios: habilitado
• Gestión de servicios: solo lectura

Cuando crees un clúster con el comando gcloud container clusters create o con un archivo de configuración de terceros, asegúrate de especificar los siguientes ámbitos:

• "https://www.googleapis.com/auth/servicecontrol"
• "https://www.googleapis.com/auth/service.management.readonly"

Para obtener más información, consulta ¿Qué son los ámbitos de acceso?

Antes de implementar:

Si añades una pequeña sección al archivo manifiesto de implementación, puedes ejecutar la imagen de Docker de ESP en tus clústeres de contenedores junto con tu aplicación en contenedores. A continuación, se describen los pasos generales que debes seguir para desplegar tu API con ESP en GKE. Por lo general, debes seguir todos los pasos que harías normalmente para ejecutar el código de tu servidor backend en GKE.

1. Despliega tu aplicación en contenedores en los clústeres de contenedores. 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 contenedores.
   4. Despliega la aplicación en el clúster.
   5. Expón tu aplicación a Internet.
2. Asegúrate de que puedes hacer lo siguiente:
   • Inicia el servidor de tu API.
   • Envía solicitudes a tu API.

Desplegar una API y ESP

App Engine

Para desplegar la API y el ESP en App Engine, haz lo siguiente:

1. Obtén el nombre del servicio de tu API. Es el nombre que has especificado en el campo host de tu documento OpenAPI.
2. Edita el archivo app.yaml y añade una sección llamada endpoints_api_service que contenga el nombre del servicio. Puedes usar el archivo app.yaml del tutorial 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

   Ir

   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

   Sustituye ENDPOINTS-SERVICE-NAME por el nombre del 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 ESP para que use la configuración de servicio implementada más reciente. Si especifica esta opción, el ESP detectará el cambio y empezará a usarlo automáticamente en un plazo de 5 minutos después de que implemente una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo use ESP.

   Si tu aplicación se basa en microservicios, debes incluir la sección endpoints_api_service en todos los archivos app.yaml.

3. Guarda el archivo (o los archivos) app.yaml.
4. Despliega el código de backend y el ESP en App Engine:

   gcloud app deploy

Como has añadido la sección endpoints_api_service al archivo app.yaml, el comando gcloud app deploy implementa y configura ESP en un contenedor independiente de tu entorno flexible de App Engine. Todo el tráfico de solicitudes se enruta a través de ESP, que proxyiza las solicitudes y las respuestas hacia y desde el contenedor que ejecuta el código de tu servidor backend.

Si necesitas configurar ESP para que use un ID de configuración específico:

1. En la sección endpoints_api_service de tu archivo app.yaml, añade el campo config_id y asigna un ID de configuración específico.
2. Elimina rollout_strategy: managed o asigna el valor fixed a rollout_strategy. La opción fixed configura ESP para que use la configuración de servicio que has especificado en config_id.
3. Vuelve a implementar tu API y ESP: gcloud app deploy

Te recomendamos que no mantengas configurado ESP para que use un ID de configuración específico durante mucho tiempo, ya que, si implementas una configuración de servicio actualizada, tendrás que reiniciar ESP para usar la nueva configuración.

Para eliminar el ID de configuración específico, haz lo siguiente:

1. Elimina la opción config_id del archivo app.yaml.
2. Añade la opción rollout_strategy: managed.
3. Ejecute 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 fallará y se mostrará el siguiente error:

config_id is forbidden when rollout_strategy is set to "managed".

Cuando despliegues tu API en el entorno flexible de App Engine por primera vez, puede que haya un retraso mientras se configuran tu máquina virtual y otra infraestructura. Para obtener más información, consulta Asegurar que el despliegue se realice correctamente en la documentación de App Engine.

Compute Engine

Para desplegar tu API con ESP en Compute Engine con Docker, haz lo siguiente:

1. Conéctate a tu instancia de VM. Sustituye 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:

   sudo docker network create --driver bridge esp_net

3. Ejecuta una instancia de la imagen del código de tu servidor backend y conéctala a la red de contenedores esp_net:

   sudo docker run \
       --detach \
       --name=YOUR_API_CONTAINER_NAME \
       --net=esp_net \
       gcr.io/YOUR_PROJECT_ID/YOUR_IMAGE:1.0

   • Sustituye YOUR_API_CONTAINER_NAME por el nombre de tu contenedor.
   • Sustituye YOUR_PROJECT_ID por el ID del proyecto Google Cloud que has usado al enviar la imagen.
   • Sustituye YOUR_IMAGE por el nombre de tu imagen.
4. Obtén el nombre del servicio de tu API. Es el nombre que has especificado en el campo host de tu documento OpenAPI.
5. Ejecuta una instancia de la imagen Docker de ESP:

   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

   • Sustituye SERVICE_NAME por el nombre de tu servicio.
   • Sustituye YOUR_API_CONTAINER_NAME por el nombre del contenedor de tu API.

   La opción --rollout_strategy=managed configura ESP para que use la configuración de servicio implementada más reciente. Si especifica esta opción, el ESP detectará el cambio y empezará a usarlo automáticamente en un plazo de 5 minutos después de que implemente una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo use ESP.

Si necesitas configurar ESP para que use un ID de configuración específico:

1. Incluya la opción --version y asígnele un ID de configuración específico.
2. Quita la opción --rollout_strategy=managed o asigna el valor fixed a --rollout_strategy. La opción fixed configura ESP para que use la configuración de servicio que has especificado en --version.
3. Vuelve a ejecutar el comando docker run.

Si especifica tanto --rollout_strategy=managed como la opción --version, el ESP se inicia con la configuración que haya especificado en --version, pero luego se ejecuta en modo gestionado y obtiene la configuración más reciente.

Te recomendamos que no mantengas configurado ESP para que use un ID de configuración específico durante mucho tiempo, ya que, si implementas una configuración de servicio actualizada, tendrás que reiniciar ESP para usar la nueva configuración.

Para eliminar el ID de configuración específico, haz lo siguiente:

1. En las marcas de ESP de docker run, elimina la opción --version.
2. Añade la opción --rollout_strategy=managed.
3. Ejecuta el comando docker run para reiniciar el ESP.

Consulta las opciones de inicio del ESP para ver la lista completa de opciones que puedes especificar al iniciar el ESP.

GKE

Para desplegar ESP en GKE, haz lo siguiente:

1. Obtén el nombre del servicio de tu API (el nombre que has especificado en el campo host de tu documento de OpenAPI).
2. Abre el archivo de manifiesto de implementación (denominado archivo deployment.yaml) y añade lo siguiente a la sección containers:

   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"
     ]

   Sustituye SERVICE_NAME por el nombre del servicio de tu API.

   La opción --rollout_strategy=managed" configura ESP para que use la última configuración de servicio implementada. Si especifica esta opción, el ESP detectará el cambio y empezará a usarlo automáticamente en un plazo de 5 minutos después de que implemente una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo use ESP.

3. Inicia el servicio de Kubernetes con el comando kubectl create:

   kubectl create -f deployment.yaml

Si necesitas configurar ESP para que use un ID de configuración específico:

1. En el archivo de manifiesto de la implementación, añade la opción --version y asígnale un ID de configuración específico.
2. Elimina --rollout_strategy=managed o asigna el valor fixed a --rollout_strategy. La opción fixed configura ESP para que use la configuración del servicio que has especificado en --version.
3. Inicia el servicio de Kubernetes: kubectl create -f deployment.yaml

Si especifica tanto --rollout_strategy=managed como la opción --version, ESP se inicia con la configuración que haya especificado en --version, pero luego se ejecuta en modo gestionado y obtiene la configuración más reciente.

Le recomendamos que no mantenga configurado ESP para que use un ID de configuración específico durante mucho tiempo, ya que, si implementa una configuración de servicio actualizada, tendrá que reiniciar ESP para usar la nueva configuración.

Para eliminar el ID de configuración específico, haz lo siguiente:

1. En el archivo de manifiesto de implementación, elimina la opción --version.
2. Añade --rollout_strategy=managed.
3. Inicia el servicio de Kubernetes: kubectl create -f deployment.yaml

Consulta las opciones de inicio del ESP para ver la lista completa de opciones que puedes especificar al iniciar el ESP.

Monitorizar la actividad de la API

Después de implementar ESP y tu backend de API, puedes usar herramientas como curl o Postman para enviar solicitudes a tu API. Si no recibes una respuesta correcta, consulta Solucionar errores de respuesta.

Después de enviar algunas solicitudes, puedes hacer lo siguiente:

• Consulta los gráficos de actividad de tu API en Endpoints > Services.
  

  Ir a la página Servicios de Endpoints

  
  La solicitud puede tardar unos instantes en reflejarse en los gráficos.

• Consulta los registros de solicitudes de tu API en la página Cloud Logging.
  

  Ir a la página Explorador de registros

Siguientes pasos

• Solucionar problemas de despliegue en el entorno flexible de App Engine.
• Solucionar problemas de Endpoints en Compute Engine.
• Solucionar problemas de endpoints en Google Kubernetes Engine