Empezar a usar API Gateway y Cloud Run para gRPC

En esta página se muestra cómo configurar API Gateway para gestionar y proteger un servicio de backend de Cloud Run con gRPC.

Lista de tareas

Usa la siguiente lista de tareas mientras sigues el tutorial. Todas las tareas son necesarias para desplegar una pasarela de API para tu servicio de backend de Cloud Run con gRPC.

  1. Crea o selecciona un Google Cloud proyecto.
  2. Si no has desplegado tu propio servicio de Cloud Run, despliega un servicio gRPC de backend de ejemplo. Consulta el paso 7 de la sección Antes de empezar.
  3. Habilita los servicios de API Gateway necesarios.
  4. Crea un documento de configuración de API de gRPC que describa tu API y configure las rutas a tu Cloud Run. Consulta Configurar una configuración de API con gRPC.
  5. Despliega una pasarela de API con tu configuración de API. Consulta Desplegar una pasarela de API.
  6. Prueba la implementación de la API enviando una solicitud. Consulta Enviar una solicitud a la API.
  7. Monitorizar la actividad de tus servicios. Consulta Monitorizar la actividad de las APIs.
  8. Evita que se te apliquen cargos en tu cuenta de Google Cloud . Consulta Liberar espacio.

Antes de empezar

  1. En la Google Cloud consola, ve a la página Panel de control y selecciona o crea un Google Cloud proyecto.

    Ir al panel de control

  2. Comprueba que la facturación esté habilitada en tu proyecto.

    Habilitar la facturación

  3. 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 PROJECT_ID.

  4. 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 PROJECT_NUMBER.

  5. Descarga e instala Google Cloud CLI.

    Descargar gcloud CLI

  6. 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.

  7. 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 URL del servicio, así como la región y el ID del proyecto en el que se ha implementado.

Habilitar los servicios necesarios

API Gateway requiere que habilites los siguientes servicios de Google:

Nombre Título
apigateway.googleapis.com API de API Gateway
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control

Para confirmar que los servicios necesarios están habilitados, sigue estos pasos:

gcloud services list

Si no ves los servicios necesarios, habilítalos:

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

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

Crear una configuración de API con gRPC

La muestra bookstore-grpc contiene los archivos que debes copiar localmente y configurar.

  1. 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.

  2. 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: "*.apigateway.PROJECT_ID.cloud.goog"
title: API Gateway + 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://python-grpc-bookstore-server-HASH-uc.a.run.app
     La indentación es importante en el formato YAML. Por ejemplo, el campo name debe estar al mismo nivel que type.
  3. En el campo name, se muestra un servicio llamado *.apigateway.PROJECT_ID.cloud.goog donde PROJECT_ID es el nombre de tu Google Cloud ID de proyecto.

  4. En el campo address de la sección backend.rules, sustituye grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app por la URL real del servicio de backend python-grpc-bookstore-server de gRPC de Cloud Run, donde HASH es el código hash único generado al crear el servicio.

    En este ejemplo se da por hecho que usas el servicio backend de gRPC Bookstore creado en la sección Antes de empezar. Si es necesario, sustituye este valor por la URL de tu servicio de Cloud Run.

  5. Guarda el documento de configuración de la API gRPC.
  6. Crea la configuración de la API: 
    gcloud api-gateway api-configs create CONFIG_ID \
--api=API_ID --project=PROJECT_ID \
--grpc-files=api_descriptor.pb,api_config.yaml
     donde:
    • CONFIG_ID especifica el nombre de la configuración de la API.
    • API_ID especifica el nombre de tu API.
    • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.
    Por ejemplo: 
    gcloud api-gateway api-configs create grpc-config \
--api=grpc-test --project=my-test-project \
--grpc-files=api_descriptor.pb,api_config.yaml

Desplegar una pasarela de APIs

Para desplegar la configuración de la API gRPC en una pasarela, ejecuta el siguiente comando:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

donde:

  • GATEWAY_ID especifica el nombre de la pasarela.
  • API_ID especifica el nombre de la API de API Gateway asociada a esta pasarela.
  • CONFIG_ID especifica el nombre de la configuración de API desplegada en la pasarela.

  • GCP_REGION es la Google Cloud región de la pasarela implementada.

  • PROJECT_ID especifica el nombre de tu Google Cloud proyecto.

Por ejemplo:

gcloud api-gateway gateways create bookstore-grpc \
  --api=grpc-test --api-config=grpc-config \
  --location=us-central1 --project=my-project

Cuando se haya completado correctamente, puedes usar el siguiente comando para ver los detalles de la pasarela:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Anota el valor de la propiedad defaultHostname en el resultado de este comando. Esta es la parte del nombre de host de la URL de la pasarela que usarás para probar tu implementación en el siguiente paso.

Por ejemplo: 

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Enviar una solicitud a la API

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

  1. 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

  2. Cambia el directorio de trabajo:

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

  3. Instala las dependencias:

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

  4. Envía una solicitud a la API de ejemplo:

    python3 bookstore_client.py --host=DEFAULT_HOSTNAME --port 443 --use_tls true

    Especifica la propiedad defaultHostname de tu pasarela en DEFAULT_HOSTNAME, sin el identificador de protocolo. Por ejemplo:

    python3 bookstore_client.py --host=my-gateway-a12bcd345e67f89g0h.uc.gateway.dev --port 443 --use_tls true

Monitorizar la actividad de la API

  1. Consulta los gráficos de actividad de tu API en la página API Gateway de laGoogle Cloud consola. Haz clic en tu API para ver sus gráficos de actividad en la página Vista general. Las solicitudes pueden tardar unos instantes en reflejarse en los gráficos.

  2. Consulta los registros de solicitudes de tu API en la página Explorador de registros. Puedes encontrar un enlace a la página Explorador de registros en la página API Gateway de la consolaGoogle Cloud .

    Ir a API Gateway

    Una vez que estés en la página de API Gateway:

    1. Selecciona la API que quieras ver.
    2. Haga clic en la pestaña Detalles.
    3. Haz clic en el enlace de Registros.

Acabas de desplegar y probar una API en API Gateway con gRPC.

Limpieza

Para evitar que se apliquen cargos en tu Google Cloud cuenta por los recursos utilizados en esta guía de inicio rápido, puedes hacer lo siguiente:

También puedes eliminar el Google Cloud proyecto que has usado en este tutorial.