Esta página se ha traducido con Cloud Translation API.

Configurar Cloud Endpoints OpenAPI para Cloud Run con ESPv2

OpenAPI | gRPC

En esta página se explica cómo configurar Cloud Endpoints para Cloud Run. Endpoints usa el proxy de servicios extensible V2 (ESPv2) como pasarela de APIs. Para proporcionar gestión de APIs en Cloud Run, debes desplegar el contenedor ESPv2 prediseñado en Cloud Run. A continuación, protege tus servicios con Cloud Run IAM para que ESPv2 pueda invocarlos.

Con esta configuración, ESPv2 intercepta todas las solicitudes a tus servicios y realiza las comprobaciones necesarias (como la autenticación) antes de invocar el servicio. Cuando el servicio responde, ESPv2 recoge y registra la telemetría, como se muestra en la figura siguiente. Puede ver las métricas de su servicio en la página Endpoints > Services (Endpoints > Servicios) de la consola de Google Cloud .

Arquitectura de Endpoints

Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y Arquitectura de Endpoints.

Migrar a ESPv2

En versiones anteriores de Cloud Endpoints, se podía usar Extensible Service Proxy (ESP) con Cloud Run. Si tienes APIs que quieres migrar a ESPv2, consulta Migrar a Extensible Service Proxy V2 para obtener más información.

Lista de tareas

Usa la siguiente lista de tareas mientras sigues el tutorial. Debes completar todas las tareas para seguir este tutorial.

Crea un Google Cloud proyecto y, si no has desplegado tu propio Cloud Run, despliega un servicio backend de ejemplo. Consulta la sección Antes de empezar.
Reserva un nombre de host de Cloud Run para el servicio ESPv2. Consulta Reservar un nombre de host de Cloud Run.
Crea un documento de OpenAPI que describa tu API y configura las rutas a tu Cloud Run. Consulta Configurar Endpoints.
Implementa el documento de OpenAPI para crear un servicio gestionado. Consulta Desplegar la configuración de Endpoints.
Crea una imagen Docker de ESPv2 con la configuración de tu servicio Endpoints. Consulta Crear una imagen de ESPv2.
Despliega el contenedor ESPv2 en Cloud Run. A continuación, concede a ESPv2 el permiso de gestión de identidades y accesos (IAM) para invocar tu servicio. Consulta Desplegar el contenedor de ESPv2.
Invocar un servicio. Consulta Enviar una solicitud a la API.
Monitorizar la actividad de tus servicios. Consulta Seguimiento de la actividad de las APIs.
Evita que se te apliquen cargos en tu cuenta de Google Cloud . Consulta Liberar espacio.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

Para configurarlo, sigue estos pasos:

En la Google Cloud consola, ve a la página Gestionar recursos y crea un proyecto.
Ir a la página Gestionar recursos
Comprueba que la facturación esté habilitada en tu proyecto.
Descubre cómo habilitar la facturación.
Anota el ID del proyecto, ya que lo necesitarás más adelante. En el resto de esta página, este ID de proyecto se denomina ESPv2_PROJECT_ID.
Anota el número de proyecto, ya que lo necesitarás más adelante. En el resto de esta página, este número de proyecto se denomina ESPv2_PROJECT_NUMBER.
Descarga e instala Google Cloud CLI.
Descargar gcloud CLI
Si no has desplegado tu propio servicio backend de Cloud Run, sigue los pasos de la guía de inicio rápido para desplegar un contenedor de ejemplo prediseñado para seleccionar o crear un proyecto y desplegar un backend de ejemplo. Google Cloud Anota la región y el ID del proyecto en el que se ha desplegado tu servicio. En el resto de esta página, este ID de proyecto se denomina BACKEND_PROJECT_ID. El nombre del servicio implementado se denomina BACKEND_SERVICE_NAME.

Reservar un nombre de host de Cloud Run

Debes reservar un nombre de host de Cloud Run para el servicio ESPv2 para configurar el documento OpenAPI o la configuración del servicio gRPC. Para reservar un nombre de host, desplegarás un contenedor de ejemplo en Cloud Run. Más adelante, desplegarás el contenedor de ESPv2 en el mismo servicio de Cloud Run.

Asegúrate de que la CLI de gcloud tenga autorización para acceder a tus datos y servicios.
1. Inicia sesión.
```
gcloud auth login
```
2. En la nueva pestaña del navegador que se abre, elige una cuenta que tenga el rol Editor u Propietario en el Google Cloud proyecto que has creado para implementar ESPv2 en Cloud Run.

Selecciona la región.

gcloud config set run/region us-central1

Despliega la imagen de ejemplo gcr.io/cloudrun/hello en Cloud Run. Sustituye ESPv2_CLOUD_RUN_SERVICE_NAME por el nombre que quieras usar para el servicio.

gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
    --image="gcr.io/cloudrun/hello" \
    --allow-unauthenticated \
    --platform managed \
    --project=ESPv2_PROJECT_ID

Si se completa correctamente, el comando muestra un mensaje similar al siguiente:

Service [ESPv2_CLOUD_RUN_SERVICE_NAME] revision [ESPv2_CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

Por ejemplo, si asignas ESPv2_CLOUD_RUN_SERVICE_NAME a gateway:

Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

En este ejemplo, https://gateway-12345-uc.a.run.app es el CLOUD_RUN_SERVICE_URL y gateway-12345-uc.a.run.app es el v2_CLOUD_RUN_HOSTNAME.

Anota ESPv2_CLOUD_RUN_SERVICE_NAME y ESPv2_CLOUD_RUN_HOSTNAME. Más adelante, desplegarás ESPv2 en el servicio de ESPv2_CLOUD_RUN_SERVICE_NAME Cloud Run. Especifique ESPv2_CLOUD_RUN_HOSTNAME en el campo host de su documento OpenAPI.

Configurar Endpoints

Debes tener un documento de OpenAPI basado en la especificación de OpenAPI v2.0 que describa la superficie de tu servicio backend y los requisitos de autenticación. También debe añadir un campo específico de Google que contenga la URL de cada servicio para que ESPv2 tenga la información que necesita para invocar un servicio. Si no conoces OpenAPI, consulta la información general sobre OpenAPI para obtener más información.

Crea un archivo de texto llamado openapi-run.yaml. (Por comodidad, en esta página se hace referencia al documento de OpenAPI con ese nombre de archivo, pero puedes darle otro nombre si lo prefieres).

Tu servicio de backend de Cloud Run se define en la parte superior del archivo openapi-run.yaml, en una definición de x-google-backend. Por ejemplo:

swagger: '2.0'
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
host: ESPv2_CLOUD_RUN_HOSTNAME
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: BACKEND_SERVICE_NAME
  protocol: h2
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

La indentación es importante para el formato YAML. Por ejemplo, el campo host debe estar al mismo nivel que info.

En el campo address de la sección x-google-backend, sustituye BACKEND_SERVICE_NAME por la URL real de tu servicio de backend de Cloud Run, que has creado en el paso 6 de Antes de empezar.

En este ejemplo, se presupone que usas el servicio backend hello creado en la guía de inicio rápido sobre cómo desplegar un contenedor de ejemplo prediseñado. Si usas otro servicio de backend de Cloud Run, sustituye BACKEND_SERVICE_NAME por la URL de tu servicio de Cloud Run.
En el campo host, especifica ESPv2_CLOUD_RUN_HOSTNAME, la parte del nombre de host de la URL que se ha reservado más arriba en Reservar un nombre de host de Cloud Run. No incluyas el identificador de protocolo, https://. Por ejemplo:
```
swagger: '2.0'
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0
host: gateway-12345-uc.a.run.app
```
Toma nota del valor de la propiedad title en el archivo openapi-run.yaml:
```
title: Cloud Endpoints + Cloud Run
```
El valor de la propiedad title se convierte en el nombre del servicio Endpoints después de implementar la configuración.
Guarda el documento de OpenAPI.

Para obtener información sobre los campos del documento OpenAPI que requiere Endpoints, consulta Configurar Endpoints.

Desplegar la configuración de Endpoints

Para desplegar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Management para crear un servicio gestionado.

Para desplegar la configuración de Endpoints, sigue estos pasos:

Asegúrate de que estás en el directorio que contiene tu documento OpenAPI.
Sube la configuración y crea un servicio gestionado.
```
gcloud endpoints services deploy openapi-run.yaml \
  --project ESPv2_PROJECT_ID
```
De esta forma, se crea un servicio de Endpoints con el nombre que hayas especificado en el campo host del archivo openapi-run.yaml. El servicio se configura según tu documento de OpenAPI.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Cuando se complete la implementación, se mostrará un mensaje similar al siguiente:
```
Service Configuration [CONFIG_ID] uploaded for service [ESPv2_CLOUD_RUN_HOSTNAME]
```
CONFIG_ID es el ID único de configuración del servicio Endpoints que se crea durante la implementación. Por ejemplo:
```
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
```
El ID de configuración del servicio consta de una marca de fecha seguida de un número de revisión. Si vuelve a implementar openapi-run.yaml el mismo día, el número de revisión se incrementará en el ID de configuración del servicio. Puedes ver la configuración del servicio y el historial de implementaciones en la página Endpoints > Services (Endpoints > Servicios) de la consola de Google Cloud .

Si aparece un mensaje de error, consulta Solucionar problemas de despliegue de la configuración de Endpoints.

Comprobando los servicios necesarios

Como mínimo, Endpoints y ESP requieren que los siguientes servicios de Google estén habilitados:

Nombre	Título
`servicemanagement.googleapis.com`	API Service Management
`servicecontrol.googleapis.com`	API Service Control

En la mayoría de los casos, el comando gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa correctamente, pero no habilita los servicios necesarios en las siguientes circunstancias:

Si has usado una aplicación de terceros, como Terraform, y no incluyes estos servicios.
Has desplegado la configuración de Endpoints en unGoogle Cloud proyecto en el que estos servicios se han inhabilitado explícitamente.

Usa el siguiente comando para confirmar que los servicios necesarios están habilitados:

gcloud services list

Si no ves los servicios necesarios, habilítalos:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

También debes habilitar el servicio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar el ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

Después de desplegar la configuración de Endpoints, ve a la página Endpoints de la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.
En OpenAPI, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo host de tu especificación de OpenAPI. En gRPC, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo name de tu configuración de endpoints de gRPC.

Para obtener más información sobre los comandos de gcloud, consulta los servicios de gcloud.

Crear una imagen de ESPv2

Crea la configuración del servicio Endpoints en una nueva imagen de Docker de ESPv2. Más adelante, desplegarás esta imagen en el servicio de Cloud Run reservado.

Nota:

Este paso es obligatorio.

La configuración del servicio debe compilarse en una nueva imagen de Docker porque Cloud Run es un servicio de escalado a cero. Esto significa que, cuando no hay tráfico, se eliminan todas las instancias. Cuando el tráfico aumenta, se crean nuevas instancias bajo demanda. Este tipo de creación de instancias de servicio también se denomina inicio en frío. Consulta más información en la documentación sobre simultaneidad de Cloud Run.

Si la imagen de Docker no tuviera la configuración del servicio integrada, Cloud Run tendría que hacer dos llamadas a la API de Google Service Management al iniciar en frío. Estas llamadas se contabilizan en tu cuota de la API Service Management de Google.

Al compilar la configuración del servicio en la imagen de Docker de ESPv2, se eliminan las dos llamadas a la API y no se afecta al recuento de cuota del servicio Service Management de Google. Este paso también acelera la creación de la nueva instancia de servicio y reduce la latencia de las solicitudes que esperan la nueva instancia.

Debe volver a ejecutar todo este paso y volver a implementar el nuevo contenedor:

Cada vez que modifiques y vuelvas a desplegar la configuración del servicio Endpoints. De lo contrario, los cambios en la configuración del servicio no se propagarán a ESPv2.
Cuando se lanza una nueva versión de ESPv2. De lo contrario, se mantendrá desplegada la versión anterior de ESPv2.

Para compilar la configuración del servicio en una nueva imagen de Docker de ESPv2, haz lo siguiente:

Descarga esta secuencia de comandos en tu máquina local, donde esté instalada la CLI de gcloud.

Nota:
Este script requiere bash. Si no usas macOS o Linux, puedes ejecutarlo en Cloud Shell, Compute Engine o el subsistema de Windows para Linux.
Ejecuta la secuencia de comandos con el siguiente comando:
```
chmod +x gcloud_build_image

./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
    -c CONFIG_ID -p ESPv2_PROJECT_ID
```
Nota:
Este script está diseñado para crear una carpeta en el directorio /tmp. Asegúrate de que tienes acceso de escritura al directorio /tmp al ejecutar esta secuencia de comandos.

Si no tienes acceso de escritura al directorio /tmp, debes modificar la secuencia de comandos para especificar un directorio alternativo en el que tengas el acceso necesario para crear carpetas.

En ESPv2_CLOUD_RUN_HOSTNAME, especifica el nombre de host de la URL que has reservado anteriormente en Reservar un nombre de host de Cloud Run. No incluyas el identificador de protocolo, https://.

Por ejemplo:
```
chmod +x gcloud_build_image

./gcloud_build_image -s gateway-12345-uc.a.run.app \
    -c 2019-02-01r0 -p your-project-id
```
La secuencia de comandos usa el comando gcloud para descargar la configuración del servicio, compilarla en una nueva imagen de ESPv2 y subir la nueva imagen al registro de contenedores de tu proyecto. La secuencia de comandos usa automáticamente la versión más reciente de ESPv2, que se indica con el símbolo ESPv2_VERSION en el nombre de la imagen de salida. La imagen de salida se sube a:
```
gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID
```
Por ejemplo:
```
gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"
```
Nota:
Pasa la marca -z a la secuencia de comandos para generar la imagen en otra ubicación del registro.

Por ejemplo, para enviar la imagen de ESPv2 generada a un centro de datos de la Unión Europea, pasa -z eu a la secuencia de comandos.

Desplegar el contenedor de ESPv2

Despliega el servicio de Cloud Run de ESPv2 con la nueva imagen que has creado anteriormente. Sustituye ESPv2_CLOUD_RUN_SERVICE_NAME por el mismo nombre de servicio de Cloud Run que usaste cuando reservaste el nombre de host anterior en Reservar un nombre de host de Cloud Run:
```
gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID
```
Nota:
Si quieres que ESPv2 gestione el acceso, usa la marca --allow-unauthenticated para asegurarte de que ESPv2 verifique el token JWT. Si no se usa la marca, el token JWT se intercepta y lo verifica el servidor de gestión de identidades y accesos de control de acceso de Cloud Run. Como IAM y ESPv2 usan el mismo encabezado Authorization, no funcionan juntos. Asegúrate de usar solo uno de ellos. Recomendamos usar IAM en lugar de ESPv2 para gestionar el acceso.
Si quieres configurar Endpoints para que use opciones de inicio de ESPv2 adicionales, como habilitar CORS, puedes transferir los argumentos en la variable de entorno ESPv2_ARGS:
```
gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
  --allow-unauthenticated \
  --platform managed \
  --project ESPv2_PROJECT_ID
```
Para obtener más información y ejemplos sobre cómo definir la variable de entorno ESPv2_ARGS, incluida la lista de opciones disponibles e información sobre cómo especificar varias opciones, consulta Flags de Extensible Service Proxy V2.
Concede permiso a ESPv2 para llamar a Service Management y Service Control.

En la Google Cloud consola, ve a la página Cloud Run.

Ir a la página de Cloud Run

Puedes ver la instancia de Cloud Run que has desplegado y la cuenta de servicio asociada.
Concede los permisos necesarios a la cuenta de servicio:

gcloud projects add-iam-policy-binding PROJECT_ID \
       --member "serviceAccount:SERVICE_ACCOUNT" \
       --role roles/servicemanagement.serviceController

¿Qué son los roles y los permisos?

Concede permiso a ESPv2 para invocar tus servicios de Cloud Run. Ejecuta el siguiente comando para cada servicio. En el siguiente comando:
Nota:
Este paso no es necesario si el servicio de Cloud Run de ESPv2 se implementa sin usar la marca --service-account y el servicio backend BACKEND_SERVICE_NAME se implementa en el proyecto ESPv2_PROJECT_NUMBER.
- Sustituye BACKEND_SERVICE_NAME por el nombre del servicio de Cloud Run que se está invocando. Si usas el servicio backend creado en la guía de inicio rápido sobre cómo desplegar un contenedor de ejemplo prediseñado, usa hello como valor.
- Sustituye ESPv2_PROJECT_NUMBER por el número del proyecto que has creado para ESPv2. Una forma de encontrarlo es ir a la página IAM de la consola de Google Cloud y buscar la cuenta de servicio de Compute predeterminada, que es la cuenta de servicio que se usa en la marca `member`. Google Cloud
```
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \
  --member "serviceAccount:ESPv2_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role "roles/run.invoker" \
  --platform managed \
  --project BACKEND_PROJECT_ID
```

Para obtener más información, consulta Gestionar el acceso con la gestión de identidades y accesos.

Enviar solicitudes a la API

En esta sección se muestra cómo enviar solicitudes a tu API.

Crea una variable de entorno para el nombre de tu servicio Endpoints. Es el nombre que has especificado en el campo host de tu documento de OpenAPI. Por ejemplo:
- Linux o macOS:
  
  export ENDPOINTS_HOST=gateway-12345-uc.a.run.app
- Windows PowerShell:
  
  $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

Linux o macOS

Usa curl para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_HOST que has definido en el paso anterior.

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

PowerShell

Usa Invoke-WebRequest para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_HOST que has definido en el paso anterior.

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

En el ejemplo anterior, las dos primeras líneas terminan en una comilla inversa. Cuando pegues el ejemplo en PowerShell, asegúrate de que no haya ningún espacio después de las comillas inversas. Para obtener información sobre las opciones que se usan en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

Aplicación de terceros

Puedes usar una aplicación de terceros, como la extensión del navegador Chrome Postman, para enviar una solicitud.

Selecciona GET como verbo HTTP.
En el encabezado, selecciona la clave content-type y el valor application/json.
Usa la URL real en lugar de la variable de entorno. Por ejemplo:
```
https://gateway-12345-uc.a.run.app/hello
```

Si no has recibido una respuesta correcta, consulta la sección Solucionar problemas de errores de respuesta.

Acabas de desplegar y probar una API en Endpoints.

Monitorizar la actividad de la API

Consulta los gráficos de actividad de tu API en la página Endpoints > Service ( Google Cloud consola).

Ver gráficos de actividad 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 Explorador de registros. Ver los registros de solicitudes de Endpoints

Limpieza

Para evitar que se apliquen cargos en tu cuenta de Google Cloud por los recursos utilizados en esta página, sigue estos pasos.

Consulta Eliminar una API y sus instancias para obtener información sobre cómo detener los servicios que se usan en este tutorial.