Comienza a usar Endpoints para Cloud Run con el ESPv2

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 Beta (ESPv2 Beta) como 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, ayuda a proteger tus servicios mediante la IAM de Cloud Run para que el ESPv2 Beta pueda invocarlos.

Con esta configuración, el ESPv2 Beta 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, ESPv2 Beta recopila y, luego, informa la telemetría. Puedes ver las métricas de tu servicio en la página Endpoints > Servicios de Google Cloud Console.

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

Migra a ESPv2 Beta

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

Lista de tareas

Usa la siguiente lista de tareas mientras trabajas en este instructivo. Todas las tareas son obligatorias para completar el instructivo.

  1. Crea un proyecto de Google Cloud y, si no has implementado tu propio Cloud Run, implementa un servicio de gRPC de backend de muestra. Consulta Antes de comenzar.
  2. Reserva un nombre de host de Cloud Run para el servicio de ESPv2 Beta. Consulta Reserva un nombre de host de Cloud Run.
  3. Crea un documento de configuración de la API de gRPC que describa tu API y configura las rutas a Cloud Run. Consulta Configura Endpoints.
  4. Implementa el documento de configuración de la API de gRPC a fin de crear un servicio administrado. Consulta Implementar la configuración de Endpoints.
  5. Compila una nueva imagen de Docker del ESPv2 Beta con tu configuración de servicio de Endpoints. Consulta Compila una imagen de ESPv2 Beta nueva.
  6. Implementa el contenedor de ESPv2 Beta en Cloud Run. Luego, otórgale al ESPv2 Beta el permiso de administración de identidades y accesos (IAM) para invocar tu servicio. Consulta Implementa el contenedor de ESPv2 Beta.
  7. Invoca un servicio. Consulta Cómo enviar una solicitud a la API.
  8. Realiza un seguimiento de la actividad de tus servicios. Consulta Realiza un seguimiento de la actividad de la API.
  9. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Cómo realizar una limpieza.

Antes de comenzar

Para realizar la configuración, sigue estos pasos:

  1. En Cloud Console, ve a la página Administrar recursos y crea un proyecto.

    Ir a la página Administración de recursos

  2. Asegúrate de tener habilitada la facturación para tu proyecto.

    Aprender a habilitar la facturación

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

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

  5. Instala el SDK de Cloud.

    Descarga el SDK de Cloud

  6. Sigue los pasos de la Guía de inicio rápido de Python de gRPC para instalar gRPC y las herramientas.

  7. Implementa el servicio de backend de gRPC de Cloud Run de python-grpc-bookstore-server para usarlo en 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 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 Beta 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 Beta en el mismo servicio de Cloud Run.

  1. Asegúrate de que el SDK de Cloud esté autorizado para acceder a tus datos y servicios.
    1. Accede.
      gcloud auth login
    2. En la nueva pestaña que se abre, elige una cuenta que tenga la función Editor o Propietario en el proyecto de Google Cloud que creaste para implementar ESPv2 Beta en Cloud Run.
  2. Configura la región.
    gcloud config set run/region us-central1
  3. 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 y gateway-12345-uc.a.run.app es CLOUD_RUN_HOSTNAME.

  4. Toma nota de CLOUD_RUN_SERVICE_NAME y CLOUD_RUN_HOSTNAME. Luego, implementarás ESPv2 Beta 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

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

  1. Crea un archivo descriptor protobuf autónomo desde tu archivo de servicio .proto:
    1. Guarda una copia de bookstore.proto del repositorio de ejemplo en tu directorio de trabajo actual. Este archivo define la API del servicio de Bookstore.
    2. Crea el siguiente directorio en el directorio de trabajo: mkdir generated_pb2
    3. Crea api_descriptor.pb, el archivo descriptor, mediante el compilador de búferes de protocolo protoc. Ejecuta el comando siguiente en el directorio donde guardaste 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 configura 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 a fin de que el compilador busque el directorio donde guardaste 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). Para mayor comodidad, en esta página se hace referencia al documento de configuración de la API de gRPC por ese nombre de archivo, pero puedes nombrarlo de otra manera si lo prefieres. Agrega 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://python-grpc-bookstore-server-HASH-uc.a.run.app
    
    La sangría es importante para el formato yaml. Por ejemplo, el campo name debe estar al mismo nivel que type.
  3. En el campo name, 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 incluyas el identificador de protocolo, como https:// o grpcs://.

  4. En el campo address de la sección backend.rules, reemplaza grpcs://python-grpc-bookstore-server-HASH-uc.a.run.app con la URL real del servicio de Cloud Run del gRPC del backend python-grpc-bookstore-server, en el que HASH es el código hash único generado cuando creaste el servicio.

    En este ejemplo se supone que usas el servicio de backend de Bookstore de gRPC creado en Antes de comenzar. Si es necesario, reemplaza este valor por la URL de tu servicio de Cloud Run.

  5. Ten en cuenta el valor de la propiedad title del archivo api_config.yaml:

    title: Cloud Endpoints + Cloud Run gRPC

    El valor de la propiedad title se convierte en el nombre del servicio de Endpoints después de que implementas la configuración.

  6. Guarda tu documento de configuración de la API de gRPC.

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

Implementar la configuración de Endpoints

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

  1. Asegúrate de estar en el directorio en el que se encuentran los archivos api_descriptor.pb y api_config.yaml.
  2. Confirma que el proyecto predeterminado que se usa actualmente en la herramienta de línea de comandos de gcloud sea el proyecto de Google Cloud en el que deseas implementar la configuración de Endpoints. Valida el ID del proyecto que se muestra en el comando siguiente para asegurarte de que el servicio no se cree en el proyecto equivocado.
    gcloud config list project
    

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando:

    gcloud config set project YOUR_PROJECT_ID
    
  3. Implementa el archivo proto descriptor y el archivo de configuración mediante la herramienta de línea de comandos de gcloud:
    gcloud endpoints services deploy api_descriptor.pb api_config.yaml
    

    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 [bookstore.endpoints.example-project.cloud.goog]

    CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó 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 consiste en una marca de fecha seguida de un número de revisión. Si implementas la configuración de Endpoints otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio.

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.com
gcloud 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 Endpoints en Cloud Console. 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 nueva imagen de ESPv2 Beta

Compila la configuración de servicio de Endpoints en una nueva imagen de Docker del ESPv2 Beta. Luego, implementarás esta imagen en el servicio reservado de Cloud Run.

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

  1. Descarga esta secuencia de comandos en tu máquina local donde está instalado el SDK de gcloud.

  2. 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
  3. La secuencia de comandos usa el comando de gcloud para descargar la configuración del servicio, compilarla en una imagen ESPv2 Beta 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 Beta, 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 Beta

  1. Implementa el servicio ESPv2 Beta 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
  2. Si quieres configurar Endpoints para usar opciones adicionales de inicio de ESPv2 Beta, 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 Beta.

  3. Otorga permiso al ESPv2 Beta 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 que creaste mediante la implementación de `gcr.io/endpointsv2/python-grpc-bookstore-server:2`, usa python-grpc-bookstore-server como este valor.
    • Reemplaza ESP_PROJECT_NUMBER por el número del proyecto que creaste para ESPv2 Beta. Una forma de hacerlo es ir a la página de IAM en Cloud Console y buscar la Cuenta de servicio predeterminada de Compute. , 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

Para obtener más información, consulta Administra el acceso mediante IAM.

Envía solicitudes a la API

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

  1. Clona el repositorio de Git donde se aloja el código del cliente gRPC:

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
  2. Cambia tu 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 muestra:

    python3 bookstore_client.py --host CLOUD_RUN_HOSTNAME --port 443 --use_tls true

    Especifica el nombre de host de tu servicio ESPv2 Beta de Cloud Run 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

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

  1. Consulta los gráficos de actividad de tu API en la página Endpoints > Servicios de Cloud Console.

    Ver los gráficos de actividad de Endpoints

    La solicitud puede tardar unos minutos en reflejarse en los gráficos.

  2. Consulta los registros de solicitud de tu API en la página Visor de registros.

    Ver los registros de solicitud de Endpoints

Crea un portal de desarrolladores para la API

Puedes usar el Portal de Cloud Endpoints a fin de crear un portal para desarrolladores, que es un sitio web en el que puedes interactuar con la API de muestra. Para obtener más información, consulta la descripción general del Portal de Cloud Endpoints.

Realiza una limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta guía de inicio rápido.

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.

Próximos pasos