Comienza a usar gRPC de Cloud Endpoints para el grupo de instancias administrado con el ESPv2

En este instructivo, se muestra cómo implementar un ejemplo simple del servicio gRPC con el proxy de servicio extensible V2 (ESPv2) en un grupo de instancias administrado

En este instructivo, se usa la versión de Python de la muestra bookstore-grpc. Consulta la sección Próximos pasos para ver muestras de gRPC en otros lenguajes.

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

Objetivos

Usa la siguiente lista de tareas de alto nivel a medida que avanzas en el instructivo. Todas las tareas son necesarias para enviar solicitudes a la API con éxito.

  1. Configura un proyecto de Google Cloud y descarga el software necesario. Consulta Antes de comenzar.
  2. Copia y configura los archivos de la muestra bookstore-grpc. Consulta Configurar Endpoints.
  3. Implementa la configuración de Endpoints para crear un servicio de este sistema. Consulta Cómo configurar Endpoints.
  4. Implementa la API y el ESPv2 en el backend del grupo de instancias administrado. Consulta Cómo implementar el backend de la API.
  5. Envía una solicitud a la API. Consulta Cómo enviar una solicitud a la API.
  6. Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Limpiar.

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 nuevos de Google Cloud califiquen para obtener una prueba gratuita.

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

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  5. Make sure that billing is enabled for your Google Cloud project.

  6. Toma nota del ID del proyecto, ya que será necesario más tarde.
  7. Instala y, luego, inicializa Google Cloud CLI.
  8. Actualiza la gcloud CLI y, luego, instala los componentes de Endpoints: 
    gcloud components update
  9. Asegúrate de que Google Cloud CLI (gcloud) esté autorizado para acceder a tus datos y servicios en Google Cloud: 
    gcloud auth login
     En la nueva pestaña del navegador que se abre, selecciona una cuenta.
  10. Configura el proyecto predeterminado con tu ID del proyecto. 
    gcloud config set project YOUR_PROJECT_ID

    Reemplaza YOUR_PROJECT_ID con el ID del proyecto. Si tienes otros proyectos de Google Cloud y deseas usar gcloud para administrarlos, consulta Cómo gcloud CLI de gcloud.

  11. Sigue los pasos en la Guía de inicio rápido de Python de gRPC para instalar gRPC y sus herramientas.

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.

Configura Endpoints

Clona el repositorio de muestra bookstore-grpc de GitHub.

Para configurar Endpoints, haz lo siguiente:

  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. Este archivo define la API del servicio de Bookstore.
    2. Crea el directorio siguiente: 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: 
      python -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 configuración YAML para la API de gRPC:
    1. Guarda una copia del archivo api_config.yaml. Este archivo define la configuración de la API de gRPC para el servicio de Bookstore.
    2. Reemplaza MY_PROJECT_ID en tu archivo api_config.yaml con el ID de tu proyecto de Google Cloud. Por ejemplo: 
      #
# Name of the service configuration.
#
name: bookstore.endpoints.example-project-12345.cloud.goog

      Ten en cuenta que el valor del campo apis.name en este archivo coincide con exactitud con el nombre de API calificado por completo del archivo .proto; de lo contrario, la implementación no funcionará. El servicio de Bookstore se define en bookstore.proto dentro del paquete endpoints.examples.bookstore. Su nombre de API calificado por completo es endpoints.examples.bookstore.Bookstore, tal como aparece en el archivo api_config.yaml.

      apis:
  - name: endpoints.examples.bookstore.Bookstore

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.

  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 con la CLI de Google Cloud: 
    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 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.

  • 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

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 Cómo implementar la configuración de Endpoints para obtener información adicional.

Implementar el backend de la API

Hasta ahora, implementaste la configuración de API en Service Management, pero aún no implementaste el código que entrega el backend de la API. En esta sección, aprenderás a configurar Docker en tu grupo de instancias administrado y a ejecutar el código del backend de la API y el ESPv2 en un contenedor de Docker.

Crea una plantilla de instancias

Crea una plantilla que usarás para crear un grupo de instancias de VM. Cada instancia que se crea a partir de la plantilla inicia un ESPv2 y un servidor de aplicaciones de backend.

  1. En la consola de Google Cloud, ve a la página Plantillas de instancia.

    Ir a Plantillas de instancia

  2. Haga clic en Crear plantilla de instancias.

  3. En Nombre, ingresa load-balancing-espv2-template.

  4. En Configuración de máquina, establece el Tipo de máquina en e2-micro.

  5. En Disco de arranque, configura la Imagen como Container Optimized OS stable version.

  6. En Firewall, selecciona Permitir tráfico HTTP.

  7. Haz clic en Administración, seguridad, discos, redes, instancia única para ver la configuración avanzada.

  8. Haz clic en la pestaña Administración. En Automatización, ingresa la siguiente secuencia de comandos de inicio. Recuerda actualizar ENDPOINTS_SERVICE_NAME.

    sudo docker network create --driver bridge esp_net
sudo docker run \
  --detach \
  --name=bookstore \
  --net=esp_net \
  gcr.io/endpointsv2/python-grpc-bookstore-server:1
sudo docker run \
  --detach \
  --name=esp \
  --publish=80:9000 \
  --net=esp_net \
  gcr.io/endpoints-release/endpoints-runtime:2 \
  --service=ENDPOINTS_SERVICE_NAME \
  --rollout_strategy=managed \
  --listener_port=9000 \
  --healthz=/healthz \
  --backend=grpc://bookstore:8000

    La secuencia de comandos obtiene, instala y, luego, inicia el servidor de aplicaciones Echo y el servidor proxy ESPv2 cuando se inicia la instancia.

  9. Haga clic en Crear.

Espera hasta que se haya creado la plantilla antes de continuar.

Crea un grupo de instancias administrado regional.

Para ejecutar la aplicación, usa la plantilla de instancias a fin de crear un grupo de instancias administrado regional:

  1. En la consola de Google Cloud, ve a la página Grupos de instancias.

    Ir a Grupos de instancias

  2. Haga clic en Crear grupo de instancias.

  3. En Nombre, ingresa load-balancing-espv2-group.

  4. En Ubicación, selecciona Varias zonas.

  5. En Región, selecciona us-central1.

  6. Haz clic en el menú desplegable Configurar zonas para mostrar las Zonas. Selecciona las siguientes zonas:

    • us-central1-b
    • us-central1-c
    • us-central1-f

  7. En Plantilla de instancias, selecciona load-balancing-espv2-template.

  8. En Ajuste de escala automático, selecciona No ajustar la escala de forma automática.

  9. En Número de instancias, ingresa 3.

  10. En Redistribución de instancias, selecciona Activada.

  11. En Reparación automática y Verificación de estado, selecciona Sin verificación de estado.

  12. Haz clic en Crear. Esto te redirecciona a la página Grupos de instancias.

Crea un balanceador de cargas

En esta sección, se explican los pasos necesarios para crear un balanceador de cargas regional que dirija el tráfico de TCP a tu grupo de instancias.

  1. En la consola de Google Cloud, ve a la página Crear un balanceador de cargas.

    Ir a Crea un balanceador de cargas

  2. En Balanceo de cargas TCP, haga clic en Iniciar configuración.

  3. En Orientado a Internet o solo interno, selecciona De Internet a mis VM.

  4. En Varias regiones o una sola región, selecciona Solo en una región.

  5. En Tipo de backend, selecciona Servicio de backend.

  6. Haga clic en Continuar.

  7. En Nombre, ingresa espv2-load-balancer.

  8. En Configuración de backend, selecciona la región us-central1.

  9. Selecciona el grupo de instancias load-balancing-espv2-group.

  10. En Verificación de estado, crea una verificación de estado nueva.

    • En Nombre, ingresa espv2-load-balancer-check.
    • Confirme que el Protocolo sea TCP, que el Puerto sea 80.

  11. En Configuración de frontend, ingresa el número de puerto 80.

  12. En Revisar y finalizar, verifica lo siguiente:

    • El Grupo de instancias es load-balancing-espv2-group.
    • La región es us-central1.
    • El Protocolo es TCP.
    • El IP:Puerto es EPHEMERAL:80.

  13. Después de crear el balanceador de cargas, busca la dirección IP de la página Balanceador de cargas.

    Ir al balanceador de cargas

Envía una solicitud a la API

Si envías la solicitud desde la misma instancia en la que se ejecutan los contenedores de Docker, puedes reemplazar SERVER_IP por localhost. De lo contrario, reemplaza SERVER_IP por la IP externa de la instancia.

Para buscar la dirección IP externa, ejecuta el comando siguiente:

gcloud compute instances list

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: 

    pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt

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

    python bookstore_client.py --host SERVER_IP --port 80

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

¡Acabas de implementar y probar una API en Endpoints!

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

  1. Asegúrate de que gcloud CLI (gcloud) esté autorizada para acceder a tus datos y servicios en Google Cloud:

    gcloud auth login

  2. Ingresa lo siguiente para mostrar los ID de tus proyectos de Google Cloud:

    gcloud projects list

  3. Con el ID del proyecto aplicable del paso anterior, establece el proyecto de Google Cloud en el que se encuentra tu aplicación como predeterminado:

    gcloud config set project [YOUR_PROJECT_ID]

  4. Obtén el nombre de todos los servicios administrados en tu proyecto de Google Cloud:

    gcloud endpoints services list

  5. Borra el servicio de Administración de servicios. Reemplaza SERVICE_NAME por el nombre del servicio que deseas quitar.

    gcloud endpoints services delete SERVICE_NAME

    La ejecución de gcloud endpoints services delete no borra de inmediato el servicio administrado. La Administración de servicios inhabilita el servicio administrado durante 30 días, lo que te da tiempo para restablecerlo si es necesario. Luego de 30 días, la Administración de servicios borra el servicio administrado de forma permanente.

  6. Ve a la página Balanceador de cargas.

    Ir al balanceador de cargas

    Borrar el balanceador de cargas espv2-load-balancer con la verificación de estado espv2-load-balancer-check.

  7. Ir a la página Grupos de instancias.

    IR A GRUPOS DE INSTANCIAS

    Borra load-balancing-espv2-group

  8. Ve a la página Plantilla de instancias.

    Ir a Plantillas de instancias

    Borrar load-balancing-espv2-template.

¿Qué sigue?