Empezar a usar Cloud Endpoints gRPC en grupos de instancias gestionados con ESPv2

OpenAPI   |  gRPC

En este tutorial se muestra cómo desplegar un servicio gRPC de ejemplo sencillo con Extensible Service Proxy V2 (ESPv2) en un grupo de instancias gestionado.

En este tutorial se usa la versión de Python del ejemplo bookstore-grpc. Consulta la sección Pasos siguientes para ver ejemplos de gRPC en otros idiomas.

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

Configurar Endpoints

Clona el repositorio de ejemplo bookstore-grpc de GitHub.

Para configurar Endpoints, haz lo siguiente:

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. Este archivo define la API del servicio Bookstore.
   2. Crea el siguiente directorio: 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:

      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 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 YAML de configuración de API gRPC:
   1. Guarda una copia del api_config.yamlarchivo. Este archivo define la configuración de la API gRPC del servicio Bookstore.
   2. Sustituye MY_PROJECT_ID en tu archivo api_config.yaml por el ID de tu proyecto 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 de este archivo coincide exactamente con el nombre de API completo del archivo .proto. De lo contrario, la implementación no funcionará. El servicio Bookstore se define en bookstore.proto dentro del paquete endpoints.examples.bookstore. Su nombre de API completo es endpoints.examples.bookstore.Bookstore, tal como aparece en el archivo api_config.yaml.

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

Para obtener más información, consulta Configurar endpoints.

Desplegar la configuración de Endpoints

Para desplegar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Gestión de servicios para crear un servicio gestionado.

1. Asegúrate de que te encuentras en el directorio en el que están los archivos api_descriptor.pb y api_config.yaml.
2. Confirma que el proyecto predeterminado que está usando la herramienta de línea de comandos gcloud es el proyecto Google Cloud en el que quieres desplegar la configuración de Endpoints. Valida el ID del proyecto devuelto por el siguiente comando para asegurarte de que el servicio no se crea en el proyecto incorrecto.

   gcloud config list project
   

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

   gcloud config set project YOUR_PROJECT_ID
   

3. Despliega 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 crea y configura el servicio, Gestión de servicios muestra información en la terminal. Cuando se complete la implementación, se mostrará un mensaje similar al siguiente:

   Service Configuration [CONFIG_ID] uploaded for service [bookstore.endpoints.example-project.cloud.goog]

   CONFIG_ID es el ID único de configuración del servicio Endpoints que se crea durante 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 consta de una marca de fecha seguida de un número de revisión. Si vuelves a desplegar la configuración de Endpoints el mismo día, el número de revisión se incrementará en el ID de configuración del servicio.

Comprobando los servicios necesarios

Como mínimo, Endpoints y ESP requieren que los siguientes servicios de Google estén habilitados:

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

En la mayoría de los casos, el comando gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa correctamente, pero no habilita los servicios necesarios en las siguientes circunstancias:

• Si has usado una aplicación de terceros, como Terraform, y no incluyes estos servicios.

• Has desplegado la configuración de Endpoints en unGoogle Cloud proyecto en el que estos servicios se han inhabilitado explícitamente.

Usa el siguiente comando para confirmar que los servicios necesarios están habilitados:

gcloud services list

Si no ves los servicios necesarios, habilítalos:

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

También debes habilitar el servicio Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar el ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

• Después de desplegar la configuración de Endpoints, ve a la página Endpoints de la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.

• En OpenAPI, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo host de tu especificación de OpenAPI. En gRPC, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el campo name de tu configuración de endpoints de gRPC.

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

Si aparece un mensaje de error, consulta Solucionar problemas de despliegue de la configuración de Endpoints. Para obtener más información, consulta el artículo sobre cómo desplegar la configuración de Endpoints.

Desplegar el backend de la API

Hasta ahora, has desplegado la configuración de la API en Service Management, pero aún no has desplegado el código que proporciona el backend de la API. En esta sección se explica cómo configurar Docker en tu grupo de instancias gestionado y cómo ejecutar el código de backend de la API y ESPv2 en un contenedor Docker.

Crear una plantilla de instancia

Crea una plantilla que usarás para crear un grupo de instancias de máquina virtual. Cada instancia creada a partir de la plantilla inicia un ESPv2 y un servidor de aplicaciones backend.

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

   Ir a Plantillas de instancia

2. Haz clic en Crear plantilla de instancia.

3. En Name (Nombre), introduce load-balancing-espv2-template.

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

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

6. En Cortafuegos, selecciona Permitir el tráfico HTTP.

7. Haz clic en Gestión, seguridad, discos, redes, único cliente para ver la configuración avanzada.

8. Haga clic en la pestaña Gestión. En Automatización, introduce la siguiente secuencia de comandos de inicio. No olvides 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 e inicia el servidor de aplicaciones de eco y el servidor proxy ESPv2 al iniciar la instancia.

9. Haz clic en Crear.

Espera a que se cree la plantilla antes de continuar.

Crear un grupo de instancias gestionado regional

Para ejecutar la aplicación, usa la plantilla de instancia para crear un grupo de instancias gestionado regional:

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

   Ir a Grupos de instancias

2. Haz clic en Crear grupo de instancias.

3. En Name (Nombre), introduce load-balancing-espv2-group.

4. En Ubicación, selecciona Varias zonas.

   Consejo: Para asegurarse de que su aplicación esté disponible durante eventos extremos, como interrupciones zonales, Compute Engine le recomienda que distribuya su aplicación en varias zonas.

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

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

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

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

8. En Autoescalado, selecciona No autoescalar.

9. Define Número de instancias en 3.

   Nota: Al crear un grupo de instancias gestionado regional, Compute Engine recomienda aprovisionar suficientes instancias para que, si todas las instancias de una zona no están disponibles, las instancias restantes sigan cumpliendo el número mínimo de instancias que necesitas. Sin embargo, aprovisionar más instancias de las que necesitas puede conllevar costes adicionales. Para obtener más información, consulta Seleccionar el tamaño del grupo de instancias para asegurar la disponibilidad.

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

11. En Autorreparación y Comprobación del estado, selecciona Ninguna comprobación del estado.

12. Haz clic en Crear. Se te redirigirá a la página Grupos de instancias.

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

Crear un balanceador de carga

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

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

   Ir a Crear un balanceador de carga

2. En Balanceo de carga de TCP, haz clic en Iniciar configuración.

3. En Orientado a Internet o solo de uso interno, selecciona De Internet a mis máquinas virtuales.

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

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

6. Haz clic en Continuar.

7. En Name (Nombre), introduce 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 Comprobación del estado, crea una comprobación del estado.

    • En Nombre, introduce espv2-load-balancer-check.
    • Comprueba que Protocol (Protocolo) sea TCP y que Port (Puerto) sea 80.

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

12. En Revisar y finalizar, comprueba 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. Una vez creado el balanceador de carga, busca la dirección IP en la página Balanceador de carga.

    Ir a Balanceador de carga

Enviar una solicitud a la API

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

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

gcloud compute instances list

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:

   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 ejemplo:

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

   • Consulta los gráficos de actividad de tu API en la página Endpoints > Services (Endpoints > Servicios).
     

     Ir a la página Servicios de Endpoints

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

   • Consulta los registros de solicitudes de tu API en la página Explorador de registros.
     

     Ir a la página Explorador de registros

Si no recibes una respuesta correcta, consulta el artículo Solucionar errores de respuesta.

Acabas de desplegar y probar una API en Endpoints.

Nota: Si quieres decirnos qué te ha gustado de este tutorial, puedes enviarnos tus comentarios en la parte inferior de esta página. Tus comentarios nos ayudan a mejorar estos tutoriales.
Si has recibido un error, únete al google-cloud-endpoints grupo de Google e infórmanos de lo que ha ido mal. Este grupo recibe respuestas de otros usuarios de Endpoints y de ingenieros de Google, que monitorizan el grupo.