Empezar a usar Endpoints para Compute Engine 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 contenedor Docker en Compute Engine.

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.

Crear una instancia de Compute Engine

Para crear una instancia de Compute Engine, sigue estos pasos:

1. In the Google Cloud console, go to the Create an instance page.

   Go to Create an instance

2. En la sección Cortafuegos, selecciona Permitir el tráfico HTTP y Permitir el tráfico HTTPS.
3. Para crear la VM, haz clic en Crear.



Espera un poco para que la instancia se inicie. Cuando esté lista, aparecerá en la página Instancias de VM con un icono de estado verde.

4. Asegúrate de que puedes conectarte a tu instancia de VM.
   1. In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.
   2. Ahora puedes usar el terminal para ejecutar comandos de Linux en tu instancia de Debian.
   3. Escribe exit para desconectarte de la instancia.
5. Anota el nombre de la instancia, la zona y la dirección IP externa, ya que los necesitarás más adelante.

Configurar Endpoints

Clona el repositorio de ejemplo 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

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. Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
2. Confirm that the default project that the gcloud command-line tool is currently using is the Google Cloud project that you want to deploy the Endpoints configuration to. Validate the project ID returned from the following command to make sure that the service doesn't get created in the wrong project.

   gcloud config list project
   

   If you need to change the default project, run the following command:

   gcloud config set project YOUR_PROJECT_ID
   

3. Deploy the proto descriptor file and the configuration file by using the Google Cloud CLI:

   gcloud endpoints services deploy api_descriptor.pb api_config.yaml
   

   As it is creating and configuring the service, Service Management outputs information to the terminal. When the deployment completes, a message similar to the following is displayed:

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

   CONFIG_ID is the unique Endpoints service configuration ID created by the deployment. For example:

   Service Configuration [2017-02-13r0] uploaded for service [bookstore.endpoints.example-project.cloud.goog]
   

   In the previous example, 2017-02-13r0 is the service configuration ID and bookstore.endpoints.example-project.cloud.goog is the service name. The service configuration ID consists of a date stamp followed by a revision number. If you deploy the Endpoints configuration again on the same day, the revision number is incremented in the service configuration ID.

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 instancia de VM y ejecutar el código backend de la API y ESPv2 en un contenedor Docker.

Instalar Docker en la instancia de máquina virtual

Para instalar Docker en la instancia de VM, sigue estos pasos:

1. Define la zona de tu proyecto ejecutando el siguiente comando:

   gcloud config set compute/zone YOUR_INSTANCE_ZONE
   

   Sustituye YOUR_INSTANCE_ZONE por la zona en la que se ejecuta tu instancia.

2. Conéctate a tu instancia con el siguiente comando:

   gcloud compute ssh INSTANCE_NAME
   

   Sustituye INSTANCE_NAME por el nombre de tu instancia de VM.

3. Consulta la documentación de Docker para configurar el repositorio de Docker. Sigue los pasos que correspondan a la versión y la arquitectura de tu instancia de VM:
   • Jessie o una versión posterior
   • x86_64 / amd64

Ejecutar la API de muestra y ESPv2 en un contenedor Docker

Para ejecutar el servicio gRPC de ejemplo con ESPv2 en un contenedor de Docker para que los clientes puedan usarlo, sigue estos pasos:

1. En la instancia de VM, crea tu propia red de contenedores llamada esp_net.

   sudo docker network create --driver bridge esp_net
   

2. Ejecuta el servidor de Bookstore de ejemplo que sirve la API de ejemplo:

   sudo docker run \
       --detach \
       --name=bookstore \
       --net=esp_net \
       gcr.io/endpointsv2/python-grpc-bookstore-server:1
   

3. Ejecuta el contenedor Docker de ESPv2 preempaquetado. En las opciones de inicio del ESPv2, sustituye SERVICE_NAME por el nombre de tu servicio. Es el mismo nombre que configuraste en el campo name del archivo api_config.yaml. Por ejemplo: bookstore.endpoints.example-project-12345.cloud.goog

   sudo docker run \
       --detach \
       --name=esp \
       --publish=80:9000 \
       --net=esp_net \
       gcr.io/endpoints-release/endpoints-runtime:2 \
       --service=SERVICE_NAME \
       --rollout_strategy=managed \
       --listener_port=9000 \
       --backend=grpc://bookstore:8000
   

   La opción --rollout_strategy=managed configura ESPv2 para que use la última configuración de servicio implementada. Si especificas esta opción, un minuto después de desplegar una nueva configuración de servicio, ESPv2 detectará el cambio y empezará a usarlo automáticamente. Te recomendamos que especifiques esta opción en lugar de proporcionar un ID de configuración específico para que lo use ESPv2. Para obtener más información sobre los argumentos de ESPv2, consulta las opciones de inicio de ESPv2.

Si aparece un mensaje de error, consulta Solucionar problemas de Endpoints en Compute Engine.

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.