Configura OpenAPI de Cloud Endpoints para Cloud Run con ESPv2
En esta página se muestra cómo configurar Cloud Endpoints para Cloud Run. Endpoints usa el proxy de servicio extensible V2 (ESPv2) como una puerta de enlace de la API. Si deseas proporcionar administración de API para Cloud Run, debes implementar en Cloud Runel contenedor de ESPv2 Beta compilado previamente y, luego, proteger tus servicios mediante la IAM de Cloud Run para que el ESPv2 Beta pueda invocarlos.
Con esta configuración, el ESPv2 intercepta todas las solicitudes a tus servicios y realiza las verificaciones necesarias (como la autenticación) antes de invocar el servicio. Cuando el servicio responde, el ESPv2 informa y recopila la telemetría, como se muestra en la siguiente figura. Puedes ver las métricas de tu servicio en la página Endpoints > Services de Google Cloud Console.
Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y la descripción de la arquitectura de Cloud Endpoints.
Migra a ESPv2
Las versiones anteriores de Cloud Endpoints admiten el uso del proxy de servicio extensible (ESP) con Cloud Run. Si tienes API existentes que deseas migrar a ESPv2, consulta Migra al proxy de servicio extensible V2 para obtener más información.
Lista de tareas
Usa la siguiente lista de tareas mientras trabajas en este instructivo. Todas las tareas son obligatorias para completar el instructivo.
- Crea un proyecto de Google Cloud y, si no has implementado tu propio Cloud Run, implementa un servicio de backend de muestra. Consulta Antes de comenzar.
- Reserva un nombre de host de Cloud Run para el servicio de ESPv2. Consulta Reserva un nombre de host de Cloud Run.
- Crea un Documento de OpenAPI que describa tu API y configura las rutas a Cloud Run. Consulta Cómo configurar Endpoints.
- Implementa el documento de OpenAPI para crear un servicio administrado. Consulta Cómo implementar la configuración de Endpoints.
- Compila una nueva imagen de Docker del ESPv2 con tu configuración de servicio de Endpoints. Consulta Compila una imagen de ESPv2 nueva.
- Implementa el contenedor de ESPv2 en Cloud Run. Luego, otórgale al ESPv2 el permiso de administración de identidades y accesos (IAM) para invocar tu servicio. Consulta Implementa el contenedor del ESPv2.
- Invoca un servicio. Consulta Cómo enviar una solicitud a la API.
- Realiza un seguimiento de la actividad de tus servicios. Consulta Cómo realizar un seguimiento de la actividad de la API.
- Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Realiza una limpieza.
Costos
En este documento, usarás los siguientes componentes facturables de Google Cloud:
Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.
Cuando finalices las tareas que se describen en este documento, puedes borrar los recursos que creaste para evitar que continúe la facturación. Para obtener más información, consulta Cómo realizar una limpieza.
Antes de comenzar
Para realizar la configuración, sigue estos pasos:
En la consola de Google Cloud, ve a la página Administrar recursos. y crear un proyecto.
Asegúrate de tener habilitada la facturación para tu proyecto.
Toma nota del ID del proyecto, ya que lo necesitarás más tarde. En el resto de la página, este ID del proyecto se denomina ESP_PROJECT_ID.
Anota el número del proyecto, ya que será necesario más tarde. En el resto de esta página, este número de proyecto se denomina ESP_PROJECT_NUMBER.
Descarga e instala Google Cloud CLI.
Si no has implementado tu propio servicio de backend de Cloud Run, sigue los pasos de la guía de inicio rápido para implementar un contenedor de muestra compilado previamente para seleccionar o crear un proyecto de Google Cloud y, luego, implementar una muestra de backend Toma nota de la región y el ID del proyecto donde se implementa tu servicio. En el resto de esta página, este ID del proyecto se denomina BACKEND_PROJECT_ID. El nombre del servicio implementado se conoce como BACKEND_SERVICE_NAME.
Reserva un nombre de host de Cloud Run
Debes reservar un nombre de host de Cloud Run para el servicio ESPv2 a fin de configurar el documento de OpenAPI o la configuración de servicio de gRPC. Para reservar un nombre de host, implementarás un contenedor de muestra en Cloud Run. Luego, implementa el contenedor del ESPv2 en el mismo servicio de Cloud Run.
-
Asegúrate de que gcloud CLI esté autorizada para acceder a tus datos y
de Google Cloud.
- Accede.
gcloud auth login
- En la nueva pestaña que se abre, elige una cuenta que tenga la función de Editor o Propietario en el proyecto de Google Cloud que creaste para implementar ESPv2 en Cloud Run.
- Accede.
-
Configura la región.
gcloud config set run/region us-central1
-
Implementa la imagen de muestra
gcr.io/cloudrun/hello
en Cloud Run Reemplaza CLOUD_RUN_SERVICE_NAME por el nombre que deseas usar para el servicio.gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/cloudrun/hello" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Cuando el proceso finalice correctamente, el comando mostrará un mensaje similar a este:
Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL
Por ejemplo, si configuras CLOUD_RUN_SERVICE_NAME como
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 CLOUD_RUN_SERVICE_URL ygateway-12345-uc.a.run.app
es CLOUD_RUN_HOSTNAME. - Toma nota de CLOUD_RUN_SERVICE_NAME y CLOUD_RUN_HOSTNAME.
Luego, implementarás ESPv2 en el servicio CLOUD_RUN_SERVICE_NAME de Cloud Run.
Debes especificar CLOUD_RUN_HOSTNAME en el campo
host
del documento de OpenAPI.
Configura Endpoints
Debes tener un documento de OpenAPI basado en OpenAPI Specification v2.0 que describa la superficie de tu servicio de backend y cualquier requisito de autenticación. También debes agregar 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 eres nuevo en OpenAPI, consulta Descripción general de OpenAPI para obtener más información.
-
Crea un archivo de texto denominado
openapi-run.yaml
. (Por conveniencia, en esta página, se hace referencia al documento de OpenAPI por ese nombre de archivo, pero puedes nombrarlo de otra manera si lo prefieres). -
Tu servicio de backend de Cloud Run se define en la parte superior del archivo
openapi-run.yaml
, en una definiciónx-google-backend
. Por ejemplo: La sangría es importante para el formato yaml. 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: 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
host
. debe estar en el mismo nivel queinfo
. En la
address
en elx-google-backend
sección, reemplazaBACKEND_SERVICE_NAME por la URL real del servicio de backend de Cloud Run, que ser creó en el paso 6 de Antes de comenzar.En este ejemplo, se supone que usas el servicio de backend
hello
creado en la Guía de inicio rápido para implementar un contenedor de muestra ya compilado. Si usas un servicio de backend de Cloud Run diferente, reemplaza BACKEND_SERVICE_NAME por la URL de tu servicio de Cloud Run.En el campo
host
, especifica CLOUD_RUN_HOSTNAME, la parte del nombre de host de la URL que se reservó antes en Reserva un nombre de host de Cloud Run. No incluyashttps://
, el identificador de protocolo. 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
Ten en cuenta el valor de la propiedad
title
del archivoopenapi-run.yaml
:title: Cloud Endpoints + Cloud Run
El valor de la propiedad
title
se convierte en el nombre del servicio de Endpoints después de que implementas la configuración.- Guarda tu documento de OpenAPI.
Para obtener información sobre los campos del documento de OpenAPI que Endpoints requiere, consulta la sección sobre cómo configurar Endpoints.
Implemente la configuración de Endpoints
Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy
. Este comando usa la Administración de servicios para crear un servicio administrado.
Para implementar la configuración de Endpoints, haz lo siguiente:
- Asegúrate de estar en el directorio que contiene el documento de OpenAPI.
Sube la configuración y crea un servicio administrado.
gcloud endpoints services deploy openapi-run.yaml \ --project ESP_PROJECT_ID
Con este proceso, se crea un servicio de Endpoints nuevo con el nombre que especificaste en el campo
host
del archivoopenapi-run.yaml
. El servicio se configura según tu documento de OpenAPI.Mientras se crea y configura el servicio, Service Management exporta la información a la terminal. Cuando se completa la implementación, aparece un mensaje similar al siguiente:
Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]
CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó la implementación. Por ejemplo:
Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]
El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si vuelves a implementar
openapi-run.yaml
el mismo día, se incrementa el número de revisión en el ID de configuración del servicio. Puedes ver la configuración del servicio historial de implementaciones en la pestaña Extremos > Servicios de la consola de Google Cloud.Si recibes un mensaje de error, consulta Cómo solucionar problemas en la implementación de la configuración de Endpoints.
Verifica los servicios requeridos
Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:Name | Cargo |
---|---|
servicemanagement.googleapis.com |
API de Administración de servicios |
servicecontrol.googleapis.com |
API de Control de servicios |
endpoints.googleapis.com |
Google Cloud Endpoints |
En la mayoría de los casos, el comando de gcloud endpoints services deploy
habilita estos servicios obligatorios. Sin embargo, el comando gcloud
se completa de manera correcta sin habilitar los servicios requeridos en las circunstancias siguientes:
Usaste una aplicación de terceros, como Terraform, y no incluiste estos servicios.
Si implementaste la configuración de Endpoints en un proyecto existente de Google Cloud en el que se inhabilitaron explícitamente estos servicios
Usa el siguiente comando para confirmar que los servicios requeridos están habilitados:
gcloud services list
Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:
gcloud services enable servicemanagement.googleapis.comgcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com
También habilita el servicio de Endpoints:
gcloud services enable ENDPOINTS_SERVICE_NAME
Para determinar la variable ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:
Después de implementar la configuración de Endpoints, ve a la página Extremos en la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.
Para OpenAPI, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo
host
de tu especificación de OpenAPI. Para gRPC, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el camponame
de tu configuración de Endpoints de gRPC.
Para obtener más información sobre los comandos gcloud
, consulta servicios de gcloud
.
Compila una imagen de ESPv2 nueva
Compila la configuración de servicio de Endpoints en una nueva imagen de Docker del ESPv2. Luego, implementarás esta imagen en el servicio reservado de Cloud Run.
Si quieres compilar la configuración de servicio en una imagen de Docker de ESPv2 nueva, sigue estos pasos:
Descargar secuencia de comandos a la máquina local en la que está instalada gcloud CLI.
Ejecuta la secuencia de comandos con el siguiente comando:
chmod +x gcloud_build_image
./gcloud_build_image -s CLOUD_RUN_HOSTNAME \ -c CONFIG_ID -p ESP_PROJECT_ID
Para CLOUD_RUN_HOSTNAME, especifica el nombre de host de la URL que reservaste antes en Reserva un nombre de host de Cloud Run. No incluyas
https://
, el identificador de protocolo.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 de
gcloud
para descargar la configuración del servicio, compilarla en una imagen de ESPv2 nueva y subir la imagen nueva al registro de contenedores del proyecto. La secuencia de comandos usa automáticamente la última versión del ESPv2 indicada por ESP_VERSION en el nombre de la imagen de salida. La imagen resultante se sube a la siguiente ubicación:gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-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"
Implementa el contenedor de ESPv2
Implementa el servicio ESPv2 de Cloud Run con la imagen nueva que compilaste antes. Reemplaza CLOUD_RUN_SERVICE_NAME por el mismo nombre de servicio de Cloud Run que usaste cuando reservaste el nombre de host anterior en Reserva un nombre de host de Cloud Run:
gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --allow-unauthenticated \ --platform managed \ --project=ESP_PROJECT_ID
Si quieres configurar Endpoints para usar opciones adicionales de inicio de ESPv2, como habilitar CORS, puedes pasar los argumentos en la variable de entorno
ESPv2_ARGS
:gcloud run deploy CLOUD_RUN_SERVICE_NAME \ --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \ --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ --allow-unauthenticated \ --platform managed \ --project ESP_PROJECT_ID
Para obtener más información y ejemplos sobre cómo configurar la variable de entorno
ESPv2_ARGS
, incluida la lista de opciones disponibles y la información sobre cómo especificar varias opciones, consulta Marcas del proxy de servicio extensible V2.Otorga permiso a ESPv2 para llamar a Service Management y Control de servicios.
- En la consola de Google Cloud, ve a la página de Cloud Run.
- Puedes ver la instancia de Cloud Run que implementaste y la cuenta de servicio asociada a ella.
- Otorga los permisos necesarios a la cuenta de servicio:
- Otorga permiso al ESPv2 para invocar tus servicios de Cloud Run. Ejecuta el siguiente comando para cada servicio. En el siguiente comando, haz lo siguiente:
- Reemplaza BACKEND_SERVICE_NAME por el nombre del servicio de Cloud Run que se invoca. Si usas el servicio de backend creado en la Guía de inicio rápido: Implementa un contenedor de muestra ya compilado, usa
hello
como este valor. - Reemplaza ESP_PROJECT_NUMBER por el número del proyecto que creaste para ESPv2. Una forma de hacerlo es ir a la página de IAM en la consola de Google Cloud y buscar la cuenta de servicio de procesamiento predeterminada, que es la cuenta de servicio que se usó en la marca “member”.
gcloud run services add-iam-policy-binding BACKEND_SERVICE_NAME \ --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --role "roles/run.invoker" \ --platform managed \ --project BACKEND_PROJECT_ID
- Reemplaza BACKEND_SERVICE_NAME por el nombre del servicio de Cloud Run que se invoca. Si usas el servicio de backend creado en la Guía de inicio rápido: Implementa un contenedor de muestra ya compilado, usa
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceController
Para obtener más información, consulta Administra el acceso mediante IAM.
Envía 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 servicio de Endpoints. Este es el nombre que especificaste 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 con la variable de entorno ENDPOINTS_HOST
que estableciste 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 con la variable de entorno ENDPOINTS_HOST
que estableciste 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 un acento grave. Cuando pegues el ejemplo en PowerShell, asegúrate de que no quede un espacio después de los acentos graves. Para obtener más información sobre las opciones usadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.
App de terceros
Puedes usar una aplicación de terceros, como el navegador Chrome extensión Cartera para cada solicitud.
- Selecciona
GET
como el verbo HTTP. - Para el encabezado, selecciona la clave
content-type
y el valorapplication/json
. Usa la URL real en lugar de la variable de entorno, por ejemplo:
https://gateway-12345-uc.a.run.app/hello
Si no obtuviste una respuesta exitosa, consulta la página sobre cómo solucionar errores de respuesta.
¡Acabas de implementar y probar una API en Endpoints!
Realiza un seguimiento de la actividad de la API
Consulta los gráficos de actividad de tu API en Endpoints > Servicio en la consola de Google Cloud.
Ver los gráficos de actividad de Endpoints
La solicitud puede tardar unos minutos en reflejarse en los gráficos.
Consulta los registros de solicitud de tu API en la página Explorador de registros. Ver los registros de solicitud de Endpoints
Crea un portal de desarrolladores para la API
Puedes utilizar el Portal de Cloud Endpoints para crear un portal de desarrolladores, un sitio web en el que puedes interactuar con la API de muestra. Para obtener más información, consulta Descripción general del Portal de Cloud Endpoints.
Limpia
Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página.
Consulta Borrar una API y las instancias de la API para obtener información acerca de cómo detener los servicios que se usan en este instructivo.