Se usó la API de Cloud Translation para traducir esta página.

Configura gRPC de Cloud Endpoints para Cloud Run con ESPv2

OpenAPI | gRPC

En esta página, se muestra cómo configurar Cloud Endpoints para Cloud Run con un backend de gRPC. 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 compilado previamente y, Luego, ayuda a proteger tus servicios mediante la IAM de Cloud Run para que el ESPv2 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 > Servicios en la Google Cloud consola.

Arquitectura de Endpoints

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

Migra a ESPv2

Las versiones anteriores de Cloud Endpoints no eran compatibles con gRPC en Cloud Run con ESP. Para usar esta función, migra al proxy de servicio extensible V2.

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 Google Cloud proyecto y, si no has implementado tu propio Cloud Run, implementa un servicio de gRPC 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 configuración de la API de gRPC que describa tu API y configura las rutas a Cloud Run. Consulta Cómo configurar Endpoints.
Implementa el documento de configuración de la API de gRPC a fin de 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 apliquen cargos a tu cuenta de Google Cloud . Consulta 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.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza 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 crea un proyecto.
Ir a la página Administración de recursos
Asegúrate de tener habilitada la facturación para tu proyecto.
Aprende a habilitar la facturación
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 ESPv2_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 ESPv2_PROJECT_NUMBER.
Descarga e instala Google Cloud CLI.
Descarga la CLI de gcloud
Sigue los pasos de la Guía de inicio rápido de Python de gRPC para instalar gRPC y las herramientas.
Implementa el servicio de gRPC de backend de ejemplo python-grpc-bookstore-server de Cloud Run para usarlo con este instructivo. El servicio de gRPC usa la siguiente imagen de contenedor:

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

Sigue los pasos de la Guía de inicio rápido: Implementa un contenedor de muestra ya compilado para implementar el servicio. Asegúrate de reemplazar 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 implementaste el servicio. En el resto de esta página, este ID del proyecto se denomina BACKEND_PROJECT_ID. El nombre del servicio implementado de Cloud Run se conoce como BACKEND_SERVICE_NAME. Su nombre de host de Cloud Run se conoce como BACKEND_HOST_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 servicios.
1. Accede.
```
gcloud auth login
```
2. En la nueva pestaña del navegador que se abre, elige una cuenta que tenga el rol de Editor o Propietario en el proyecto Google Cloud que creaste para implementar ESPv2 en Cloud Run.

Configura la región.

gcloud config set run/region us-central1

Implementa la imagen de muestra gcr.io/cloudrun/hello en Cloud Run Reemplaza ESPv2_CLOUD_RUN_SERVICE_NAME por el nombre que deseas 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

Cuando el proceso finalice correctamente, el comando mostrará un mensaje similar a este:

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 configuras ESPv2_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 y gateway-12345-uc.a.run.app es v2_CLOUD_RUN_HOSTNAME.

Toma nota de ESPv2_CLOUD_RUN_SERVICE_NAME y ESPv2_CLOUD_RUN_HOSTNAME. Luego, implementarás ESPv2 en el servicio ESPv2_CLOUD_RUN_SERVICE_NAME de Cloud Run. Debes especificar ESPv2_CLOUD_RUN_HOSTNAME en el campo host del documento de OpenAPI.

Configura Endpoints

El ejemplo de bookstore-grpc contiene los archivos que necesitas copiar de forma local y configurar.

Create a self-contained protobuf descriptor file from your service .proto file:
1. Save a copy of bookstore.proto from the example repository to your current working directory. This file defines the Bookstore service's API.
2. Create the following directory under your working directory: mkdir generated_pb2
3. Create the descriptor file, api_descriptor.pb, by using the protoc protocol buffers compiler. Run the following command in the directory where you saved 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
```
  In the preceding command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved bookstore.proto.

Create a text file called api_config.yaml in your current working directory (the same directory that contains bookstore.proto). For convenience, this page refers to the gRPC API configuration document by that file name, but you can name it something else if you prefer. Add the following contents to the file:

# 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

Indentation is important for yaml format. For example the name field must be at the same level as type.

In the name field, specify CLOUD_RUN_HOSTNAME, the hostname portion of the URL that was reserved above in Reserving a Cloud Run hostname. Don't include the protocol identifier, such as https:// or grpcs://.
In the address field in the backend.rules section, replace BACKEND_HOST_NAME with the actual gRPC Bookstore Cloud Run service created in Before you begin.

Note: To use gRPC with TLS on Cloud Run, the address field must have the scheme grpcs:// instead of https://.
Note the value of the title property in the api_config.yaml file:
```
title: Cloud Endpoints + Cloud Run gRPC
```
The value of the title property becomes the name of the Endpoints service after you deploy the configuration.
Save your gRPC API configuration document.

Consulta Configurar Endpoints para obtener más información.

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Management a fin de crear un servicio administrado.

Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.
```
gcloud config list project
```
If you need to change the default project, run the following command:
```
gcloud config set project YOUR_PROJECT_ID
```
Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:
```
gcloud endpoints services deploy api_descriptor.pb api_config.yaml
```
As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:
```
Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:
```
Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
```
In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

Verifica los servicios requeridos

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:

Name	Título
`servicemanagement.googleapis.com`	API de Administración de servicios
`servicecontrol.googleapis.com`	Service Control API

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.
Implementaste la configuración de Endpoints en un proyecto deGoogle Cloud existente en el que estos servicios se inhabilitaron de forma explícita.

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.com
gcloud services enable servicecontrol.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 Endpoints 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 campo name de tu configuración de Endpoints de gRPC.

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

Si recibes un mensaje de error, consulta Solucionar problemas con la implementación de la configuración de Cloud Endpoints.

Consulta Implementar la configuración de Endpoints para obtener información adicional.

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.

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 escala a cero. Esto significa que cuando no hay tráfico, se borran todas las instancias. Cuando el tráfico aumenta, se crean instancias nuevas según se necesiten. Este tipo de creación de instancia de servicio también se denomina inicio en frío. Consulta la documentación sobre simultaneidad de Cloud Run para obtener más información.

Si la imagen de Docker no tuviera incorporada la configuración del servicio integrada, Cloud Run tendría que realizar dos llamadas a la API de Google ServiceManagement en el inicio en frío. Estas llamadas se descuentan de tu cuota de la API de Google ServiceManagement.

Cuando compilas la configuración del servicio en la imagen de Docker de ESPv2, quitas las dos llamadas a la API y no influyes en el recuento de cuotas del servicio de Google ServiceManagement. Con este paso, también se acelera la creación de la nueva instancia de servicio y se reduce la latencia de las solicitudes que esperan la instancia nueva.

Debes volver a ejecutar este paso completo y volver a implementar el contenedor nuevo:

Cada vez que modificas y vuelves a implementar la configuración del servicio de Endpoints. De lo contrario, los cambios en la configuración del servicio no se propagarán al ESPv2.
Cuando se lanza una nueva versión del ESPv2. De lo contrario, la versión anterior de ESPv2 permanecerá implementada.

Si quieres compilar la configuración de servicio en una imagen de Docker de ESPv2 nueva, sigue estos pasos:

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

Nota:
Para esta secuencia de comandos, se requiere Bash. Si no usas macOS o Linux, puedes ejecutarla 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:
Esta secuencia de comandos está diseñada para crear una carpeta dentro del directorio /tmp. Asegúrate de tener acceso de escritura para el directorio /tmp cuando ejecutes este script.

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

Para ESPv2_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 ESPv2_VERSION en el nombre de la imagen de salida. La imagen resultante se sube a la siguiente ubicación:
```
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 una ubicación de registro diferente.

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.

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/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 de gRPC usa cualquier protocolo de transmisión, agrega la marca --use-http2 al comando gcloud run deploy. Por el momento, esta marca solo se admite en gcloud beta run. Agrega esta marca cuando implementes servicios de ESPv2 y de backend de gRPC de Cloud Run.
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/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 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 al ESPv2 para invocar tus servicios de Cloud Run. Ejecuta el siguiente comando para cada servicio. En el siguiente comando, haz lo siguiente:
Nota:
Este paso no es necesario si el servicio de Cloud Run de ESPv2 se implementa sin usar la marca --service-account y si el servicio de backend BACKEND_SERVICE_NAME se implementa en el proyecto ESPv2_PROJECT_NUMBER.
- Reemplaza BACKEND_SERVICE_NAME por el nombre del servicio de Cloud Run que se invoca. Si usas el servicio que creaste mediante la implementación de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, usa python-grpc-bookstore-server como este valor.
- Reemplaza ESPv2_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 usa en la marca “member”.
```
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 Administra el acceso mediante IAM.

Envíe solicitudes a la API

To send requests to the sample API, you can use a sample gRPC client written in Python.

Clone the git repo where the gRPC client code is hosted:

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

Change your working directory:

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

Install dependencies:

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

Send a request to the sample API:
```
python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true
```
Specify the hostname of your ESPv2 Cloud Run service in CLOUD_RUN_HOSTNAME, without the protocol identifier. For example:
```
python3 bookstore_client.py --host espv2-grpc-HASH-uc.a.run.app --port 443 --use_tls true
```
- Look at the activity graphs for your API in the Endpoints > Services page.
  
  Go to the Endpoints Services page
  
  It may take a few moments for the request to be reflected in the graphs.
- Look at the request logs for your API in the Logs Explorer page.
  
  Go to the Logs Explorer page

Si no obtienes una respuesta correcta, consulta Solucionar errores en las respuestas.

¡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 la página Endpoints > Servicio de la Google Cloud consola.

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

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.