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

---

OpenAPI   |  gRPC

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 del bookstore-grpc de muestra. 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 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 instructivo, se usan los siguientes componentes facturables de Google Cloud:

• Compute Engine
• Extremos

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 este instructivo, podrás borrar los recursos creados para evitar que se te siga facturando. Para obtener más información, consulta Cómo realizar una limpieza.

Antes de comenzar

1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

4. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

5. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Obtén información sobre cómo verificar si la facturación está habilitada en un proyecto.

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 CLI de gcloud y, luego, instala los componentes de Endpoints con el comando siguiente:

   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 pestaña del navegador nueva 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 administrar configuraciones de gcloud CLI.

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

Cuando finalices este instructivo, podrás borrar los recursos creados para evitar que se te siga facturando. 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. Create a self-contained protobuf descriptor file from your service .proto file:
   1. Save a copy of bookstore.proto from the example repository. This file defines the Bookstore service's API.
   2. Create the following 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:

      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
      

      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.

2. Create a gRPC API configuration YAML file:
   1. Save a copy of the api_config.yamlfile. This file defines the gRPC API configuration for the Bookstore service.
   2. Replace MY_PROJECT_ID in your api_config.yaml file with your Google Cloud project ID. For example:

      #
      # Name of the service configuration.
      #
      name: bookstore.endpoints.example-project-12345.cloud.goog
      

      Note that the apis.name field value in this file exactly matches the fully-qualified API name from the .proto file; otherwise deployment won't work. The Bookstore service is defined in bookstore.proto inside package endpoints.examples.bookstore. Its fully-qualified API name is endpoints.examples.bookstore.Bookstore, just as it appears in the api_config.yaml file.

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

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   Mientras se crea y configura el servicio, Administración de servicios 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 el ESP requieren que se habiliten los siguientes servicios de Google:

Nombre	Título
servicemanagement.googleapis.com	API de Service Management
servicecontrol.googleapis.com	API de Service Control
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 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 Google Cloud Console, 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. Haz 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.

   Sugerencia profesional: Para garantizar que tu aplicación esté disponible durante eventos extremos, como interrupciones zonales, Compute Engine recomienda que distribuyas tu aplicación en 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.

   Sugerencia profesional: Cuando se crea un grupo de instancias administrado regional, Compute Engine recomienda aprovisionar suficientes instancias para que, si todas las instancias de una zona dejan de estar disponibles, las instancias restantes puedan satisfacer la cantidad mínima de instancias que necesitas. Sin embargo, el aprovisionamiento de más instancias que las necesarias podría generar costos adicionales. Si deseas obtener más información, consulta Aprovisiona el tamaño correcto del grupo de instancias administrado para garantizar la disponibilidad.

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.

    Nota: Es posible que debas esperar unos minutos hasta que todas las instancias del grupo estén en ejecución y listas para mostrar la aplicación web.

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

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

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

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

2. Change your working directory:

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

3. Install dependencies:

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

4. Send a request to the sample API:

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

   • 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!

Nota: Si quieres contarnos qué te gustó de este instructivo, envíanos tus comentarios al final de esta página. Tus comentarios nos ayudarán a mejorar estos instructivos.
Si recibiste un error, únete al grupo de Google google-cloud-endpoints y cuéntanos cuál fue el problema. En este grupo hay respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

Realiza una limpieza

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 la CLI de gcloud (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 predeterminado de Cloud en el que se encuentra tu aplicación:

   gcloud config set project [YOUR_PROJECT_ID]
   

4. Obtén el nombre de todos los servicios administrados en tu proyecto de 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?

• Obtén información sobre cómo configurar tu propia API de gRPC para Endpoints.
• Mira la muestra de Bookstore con más detalle en GitHub. El cliente y el servidor están disponibles en Python y Java.
• La muestra getting-started-grpc está disponible en GitHub en los lenguajes siguientes:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js