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

Configurar Cloud Endpoints gRPC para Cloud Run con ESPv2

OpenAPI | gRPC

En esta página se explica cómo configurar Cloud Endpoints para Cloud Run con un backend de gRPC. 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, puedes proteger 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 no se admitía gRPC en Cloud Run con ESP. Para usar esta función, migra a Extensible Service Proxy V2.

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 aún no has desplegado tu propio Cloud Run, despliega un servicio gRPC de 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 configuración de API de gRPC que describa tu API y configura las rutas a Cloud Run. Consulta Configurar Endpoints.
Despliega el documento de configuración de la API gRPC 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
Sigue los pasos que se indican en la guía de inicio rápido de gRPC Python para instalar gRPC y las herramientas de gRPC.
Despliega el backend de ejemplo python-grpc-bookstore-server como servicio gRPC de Cloud Run para usarlo en este tutorial. El servicio gRPC usa la siguiente imagen de contenedor:

gcr.io/endpointsv2/python-grpc-bookstore-server:2

Sigue los pasos que se indican en la guía de inicio rápido sobre cómo desplegar un contenedor de ejemplo prediseñado para desplegar el servicio. Sustituye la imagen de contenedor especificada en esa guía de inicio rápido por gcr.io/endpointsv2/python-grpc-bookstore-server:2.

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 de Cloud Run desplegado se denomina BACKEND_SERVICE_NAME. Su nombre de host de Cloud Run se denomina BACKEND_HOST_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

La muestra bookstore-grpc contiene los archivos que debes copiar de forma local y configurar.

Crea un archivo de descriptor protobuf independiente a partir de tu archivo .proto de servicio:
1. Guarda una copia de bookstore.proto del repositorio de ejemplo en tu directorio de trabajo actual. Este archivo define la API del servicio Bookstore.
2. Crea el siguiente directorio en tu directorio de trabajo: mkdir generated_pb2
3. Crea el archivo de descriptor, api_descriptor.pb, con el compilador de búferes de protocolo protoc. Ejecuta el siguiente comando en el directorio donde hayas guardado bookstore.proto:
```
python3 -m grpc_tools.protoc \
    --include_imports \
    --include_source_info \
    --proto_path=. \
    --descriptor_set_out=api_descriptor.pb \
    --python_out=generated_pb2 \
    --grpc_python_out=generated_pb2 \
    bookstore.proto
```
  En el comando anterior, --proto_path se define como el directorio de trabajo actual. En tu entorno de compilación de gRPC, si usas un directorio diferente para los archivos de entrada .proto, cambia --proto_path para que el compilador busque en el directorio donde hayas guardado bookstore.proto.

Crea un archivo de texto llamado api_config.yaml en tu directorio de trabajo actual (el mismo directorio que contiene bookstore.proto). Por comodidad, en esta página se hace referencia al documento de configuración de la API gRPC con ese nombre de archivo, pero puedes darle otro nombre si lo prefieres. Añade el siguiente contenido al archivo:

# The configuration schema is defined by the service.proto file.
# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto

type: google.api.Service
config_version: 3
name: CLOUD_RUN_HOSTNAME
title: Cloud Endpoints + Cloud Run gRPC
apis:
  - name: endpoints.examples.bookstore.Bookstore
usage:
  rules:
  # ListShelves methods can be called without an API Key.
  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
    allow_unregistered_calls: true
backend:
  rules:
    - selector: "*"
      address: grpcs://BACKEND_HOST_NAME

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

En el campo name, especifica 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, como https:// o grpcs://.
En el campo address de la sección backend.rules, sustituye BACKEND_HOST_NAME por el servicio gRPC Bookstore Cloud Run real que has creado en Antes de empezar.

Nota: Para usar gRPC con TLS en Cloud Run, el campo address debe tener el esquema grpcs:// en lugar de https://.
Toma nota del valor de la propiedad title en el archivo api_config.yaml:
```
title: Cloud Endpoints + Cloud Run gRPC
```
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 configuración de la API gRPC.

Para obtener más información, 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 Gestión de servicios para crear un servicio gestionado.

Asegúrate de que te encuentras en el directorio en el que están los archivos api_descriptor.pb y api_config.yaml.
Confirma que el proyecto predeterminado que está usando la herramienta de línea de comandos gcloud es el proyecto Google Cloud en el que quieres desplegar la configuración de Endpoints. Valida el ID del proyecto devuelto por el siguiente comando para asegurarte de que el servicio no se crea en el proyecto incorrecto.
```
gcloud config list project
```
Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando:
```
gcloud config set project YOUR_PROJECT_ID
```
Despliega el archivo proto descriptor y el archivo de configuración con la CLI de Google Cloud:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
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 [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID es el ID único de configuración del servicio Endpoints que se crea durante la implementación. Por ejemplo:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y bookstore.endpoints.example-project.cloud.goog es el nombre del servicio. El ID de configuración del servicio consta de una marca de fecha seguida de un número de revisión. Si vuelves a desplegar la configuración de Endpoints el mismo día, el número de revisión se incrementará en el ID de configuración del servicio.

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.

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

Para obtener más información, consulta el artículo sobre cómo desplegar la configuración de Endpoints.

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 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 CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
  --allow-unauthenticated \
  --platform managed \
  --project=ESPv2_PROJECT_ID
```
Nota:
Si tu servicio gRPC usa algún protocolo de streaming, añade la marca --use-http2 al comando gcloud run deploy. Actualmente, esta marca solo se admite en gcloud beta run. Añade esta marca al desplegar tanto ESPv2 como los servicios de Cloud Run de backend de gRPC.
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 CLOUD_RUN_SERVICE_NAME \
  --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-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 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 despliega sin usar la marca --service-account y el servicio backend BACKEND_SERVICE_NAME se despliega 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 creado desplegando `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, usa python-grpc-bookstore-server 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

Para enviar solicitudes a la API de ejemplo, puedes usar un cliente gRPC de ejemplo escrito en Python.

Clona el repositorio de Git en el que se aloja el código del cliente de gRPC:
```
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
```

Cambia el directorio de trabajo:

cd python-docs-samples/endpoints/bookstore-grpc/

Instala las dependencias:

pip3 install virtualenv
virtualenv env
source env/bin/activate
pip3 install -r requirements.txt

Envía una solicitud a la API de ejemplo:
```
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
```
Especifica el nombre de host de tu servicio de Cloud Run de ESPv2 en CLOUD_RUN_HOSTNAME, sin el identificador de protocolo. Por ejemplo:
```
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
```
- Consulta los gráficos de actividad de tu API en la página Endpoints > Services (Endpoints > Servicios).
  
  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 Explorador de registros.
  
  Ir a la página Explorador de registros

Si no recibes una respuesta correcta, consulta el artículo Solucionar 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.