Empezar a usar Endpoints para GKE 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 Google Kubernetes Engine (GKE). 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.

En el tutorial se usan imágenes de contenedor precompiladas del código de ejemplo y ESPv2, que se almacenan en Artifact Registry. Si no conoces los contenedores, consulta la siguiente información:

• Desplegar una aplicación web en contenedores
• Imágenes de contenedor de Kubernetes

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

Configurar Endpoints

La muestra bookstore-grpc contiene los archivos que debes copiar de forma local y configurar.

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 del servicio 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 crear un clúster de GKE para alojar el backend de la API y desplegar la API.

Crear un clúster de contenedores

El clúster necesita un alias de IP para usar el balanceo de carga nativo de contenedores. Para crear un clúster de contenedores con un alias de IP para nuestro ejemplo, sigue estos pasos:

gcloud container clusters create espv2-demo-cluster \
    --enable-ip-alias \
    --create-subnetwork="" \
    --network=default \
    --zone=us-central1-a

El comando anterior crea un clúster, espv2-demo-cluster, con una subred aprovisionada automáticamente en la zona us-central1-a.

Autenticar kubectl en el clúster de contenedores

Para usar kubectl y crear y gestionar recursos de clúster, debes obtener las credenciales del clúster y ponerlas a disposición de kubectl. Para ello, ejecuta el siguiente comando, sustituyendo NAME por el nombre del nuevo clúster y ZONE por la zona del clúster.

gcloud container clusters get-credentials NAME --zone ZONE

Comprobando los permisos necesarios

ESP y ESPv2 llaman a servicios de Google que usan IAM para verificar si la identidad que llama tiene suficientes permisos para acceder a los recursos de IAM utilizados. La identidad de llamada es la cuenta de servicio adjunta que implementa ESP y ESPv2.

Cuando se implementa en un pod de GKE, la cuenta de servicio adjunta es la cuenta de servicio del nodo. Normalmente, es la cuenta de servicio predeterminada de Compute Engine. Sigue esta recomendación de permisos para elegir una cuenta de servicio de nodo adecuada.

Si se usa Workload Identity, se puede usar una cuenta de servicio distinta de la cuenta de servicio del nodo para comunicarse con los servicios de Google. Puedes crear una cuenta de servicio de Kubernetes para que el pod ejecute ESP y ESPv2, crear una cuenta de servicio de Google y asociar la cuenta de servicio de Kubernetes a la cuenta de servicio de Google.

Sigue estos pasos para asociar una cuenta de servicio de Kubernetes con una cuenta de servicio de Google. Esta cuenta de servicio de Google es la cuenta de servicio adjunta.

Si la cuenta de servicio vinculada es la cuenta de servicio predeterminada de Compute Engine del proyecto y la configuración del servicio de endpoint se ha implementado en el mismo proyecto, la cuenta de servicio debería tener suficientes permisos para acceder a los recursos de gestión de identidades y accesos. Por lo tanto, se puede omitir el paso de configuración de los roles de gestión de identidades y accesos. De lo contrario, se deben añadir los siguientes roles de gestión de identidades y accesos a la cuenta de servicio asociada.

Añade los roles de gestión de identidades y accesos necesarios:

En esta sección se describen los recursos de gestión de identidades y accesos que usan ESP y ESPv2, así como los roles de gestión de identidades y accesos que necesita la cuenta de servicio asociada para acceder a estos recursos.

Configuración del servicio de endpoint

ESP y ESPv2 llaman a Service Control, que usa la configuración del servicio de endpoint. La configuración del servicio de endpoint es un recurso de gestión de identidades y accesos, y ESP y ESPv2 necesitan el rol Service Controller para acceder a él.

El rol de IAM está en la configuración del servicio de endpoint, no en el proyecto. Un proyecto puede tener varias configuraciones de servicio de endpoint.

Usa el siguiente comando de gcloud para añadir el rol a la cuenta de servicio adjunta en la configuración del servicio de endpoint.

gcloud endpoints services add-iam-policy-binding SERVICE_NAME \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/servicemanagement.serviceController

Donde
* SERVICE_NAME es el nombre del servicio de endpoint
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com es la cuenta de servicio asociada.

Cloud Trace

ESP y ESPv2 llaman al servicio Cloud Trace para exportar el seguimiento a un proyecto. Este proyecto se llama proyecto de seguimiento. En ESP, el proyecto de seguimiento y el proyecto propietario de la configuración del servicio de endpoint son el mismo. En ESPv2, el proyecto de seguimiento se puede especificar mediante la marca --tracing_project_id y, de forma predeterminada, se usa el proyecto de implementación.

ESP y ESPv2 requieren el rol Agente de Cloud Trace para habilitar Cloud Trace.

Usa el siguiente comando de gcloud para añadir el rol a la cuenta de servicio adjunta:

gcloud projects add-iam-policy-binding TRACING_PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudtrace.agent

Donde
* TRACING_PROJECT_ID es el ID del proyecto de seguimiento
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com es la cuenta de servicio adjunta. Para obtener más información, consulta ¿Qué son los roles y los permisos?

Configurar las claves y los certificados SSL

El balanceo de carga nativo de contenedor usa el balanceo de carga HTTP/2, que debe cifrarse con TLS. Para ello, se tuvo que implementar un certificado TLS en el ingress de GKE y en ESPv2. Puedes usar tu propio certificado o un certificado autofirmado.

1. Crea un certificado y una clave autofirmados con openssl. Asegúrate de haber introducido el mismo FQDN bookstore.endpoints.MY_PROJECT_ID.cloud.goog cuando se te pida el nombre común(CN). Los clientes usan este nombre para verificar el certificado del servidor.

   openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
   -keyout ./server.key -out ./server.crt

2. Crea un secreto de Kubernetes con tu clave y certificado SSL. Ten en cuenta que el certificado se copia en dos ubicaciones, server.crt y tls.crt, ya que el secreto se proporciona tanto al ingress de GKE como a ESPv2. El ingress de GKE busca la ruta del certificado tls.crt y ESPv2 busca la ruta del certificado server.crt.

   kubectl create secret generic esp-ssl \
   --from-file=server.crt=./server.crt --from-file=server.key=./server.key \
   --from-file=tls.crt=./server.crt --from-file=tls.key=./server.key

Desplegar la API de ejemplo y ESPv2 en el clúster

Nota: En el caso de flotas de endpoints singulares o más pequeñas, usa --rollout_strategy=managed con SERVICE_NAME. En el caso de flotas de endpoints grandes, monta la configuración del servicio tal como se muestra en la siguiente sección.

Para desplegar el servicio gRPC de ejemplo en el clúster de forma que los clientes puedan usarlo, sigue estos pasos:

1. git clone este repositorio y abre el archivo de manifiesto de implementación grpc-bookstore.yaml para editarlo.
2. Sustituye SERVICE_NAME por el nombre de tu servicio de Endpoints para el contenedor de entrada y ESPv2. Es el mismo nombre que has configurado en el campo name del archivo api_config.yaml.
   # Copyright 2016 Google Inc.
   #
   # Licensed under the Apache License, Version 2.0 (the "License");
   # you may not use this file except in compliance with the License.
   # You may obtain a copy of the License at
   #
   #     http://www.apache.org/licenses/LICENSE-2.0
   #
   # Unless required by applicable law or agreed to in writing, software
   # distributed under the License is distributed on an "AS IS" BASIS,
   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   # See the License for the specific language governing permissions and
   # limitations under the License
   
   # Use this file to deploy the container for the grpc-bookstore sample
   # and the container for the Extensible Service Proxy (ESP) to
   # Google Kubernetes Engine (GKE).
   
   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: esp-grpc-bookstore
     annotations:
       kubernetes.io/ingress.class: "gce"
       kubernetes.io/ingress.allow-http: "false"
   spec:
     tls:
     - hosts:
       - SERVICE_NAME
       secretName: esp-ssl
     backend:
       serviceName: esp-grpc-bookstore
       servicePort: 443
   ---
   apiVersion: cloud.google.com/v1
   kind: BackendConfig
   metadata:
     name: esp-grpc-bookstore
   spec:
     healthCheck:
       type: HTTP2
       requestPath: /healthz
       port: 9000
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: esp-grpc-bookstore
     annotations:
       service.alpha.kubernetes.io/app-protocols: '{"esp-grpc-bookstore":"HTTP2"}'
       cloud.google.com/neg: '{"ingress": true, "exposed_ports": {"443":{}}}'
       cloud.google.com/backend-config: '{"default": "esp-grpc-bookstore"}'
   spec:
     ports:
     # Port that accepts gRPC and JSON/HTTP2 requests over TLS.
     - port: 443
       targetPort: 9000
       protocol: TCP
       name: esp-grpc-bookstore
     selector:
       app: esp-grpc-bookstore
     type: ClusterIP
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: esp-grpc-bookstore
   spec:
     replicas: 1
     selector:
       matchLabels:
         app: esp-grpc-bookstore
     template:
       metadata:
         labels:
           app: esp-grpc-bookstore
       spec:
         volumes:
         - name: esp-ssl
           secret:
             secretName: esp-ssl
         containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:2
           args: [
             "--listener_port=9000",
             "--service=SERVICE_NAME",
             "--rollout_strategy=managed",
             "--backend=grpc://127.0.0.1:8000",
             "--healthz=/healthz",
             "--ssl_server_cert_path=/etc/esp/ssl",
           ]
           ports:
             - containerPort: 9000
           volumeMounts:
           - mountPath: /etc/esp/ssl
             name:  esp-ssl
             readOnly: true
         - name: bookstore
           image: gcr.io/endpointsv2/python-grpc-bookstore-server:1
           ports:
             - containerPort: 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.

   Por ejemplo:

       spec:
         containers:
         - name: esp
           image: gcr.io/endpoints-release/endpoints-runtime:2
           args: [
             "--listener_port=9000",
             "--service=bookstore.endpoints.example-project-12345.cloud.goog",
             "--rollout_strategy=managed",
             "--backend=grpc://127.0.0.1:8000"
           ]

   Te recomendamos que definas imagePullPolicy en la especificación del contenedor anterior como Always. De esta forma, los pods recién creados siempre extraerán la versión más reciente de ESPv2. Consulta las prácticas recomendadas de configuración para obtener más información. Cuando se lanza una nueva versión de ESPv2, puedes realizar un reinicio gradual de todos los pods para asegurarte de que se utiliza la versión más reciente.

   Desplegar configuraciones de servicio en Endpoints

   Si gestionas una flota grande de Endpoints (más de 100) en el mismo proyecto de Google Cloud, te recomendamos que montes la configuración del servicio en el contenedor en lugar de usar la marca --rollout_strategy=managed para extraer la configuración del servicio de la API Service Management.

   La API Service Management tiene una cuota predeterminada. Si una flota grande de proxies ESPv2 usa --rollout_strategy=managed, todos ellos buscarán la configuración de servicio más reciente. La flota puede superar la cuota y, por lo tanto, provocar errores en la actualización de la configuración del servicio.

   Sigue los pasos que se indican a continuación para montar la configuración del servicio:
   1. Descarga la configuración JSON del servicio.

   curl -o "/tmp/service_config.json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://servicemanagement.googleapis.com/v1/services/SERVICE/configs/CONFIG_ID?view=FULL"
   

   2. Crea un recurso de mapa de configuración de Kubernetes a partir de la configuración JSON.

   kubectl create configmap service-config-configmap \
     --from-file=service_config.json:/tmp/service_config.json
   

   3. Monta el recurso de mapa de configuración en el contenedor y usa la marca --service_config_path para especificar la ruta del archivo de configuración.

   Por ejemplo:

     containers:
     - args:
       - --listener_port=8081
       - --backend=http://127.0.0.1:8080
       - --service_json_path=/etc/espv2_config/service_config.json
       - --healthz=/healthz
       image: gcr.io/endpoints-release/endpoints-runtime:2
       name: esp
       ports:
       - containerPort: 8081
         protocol: TCP
       volumeMounts:
       - mountPath: /etc/espv2_config
         name: service-config-volume
     volumes:
     - configMap:
         defaultMode: 420
         name: service-config-configmap
       name: service-config-volume
   

3. Inicia el servicio:

   kubectl create -f grpc-bookstore.yaml
   

Si aparece un mensaje de error, consulta Solucionar problemas de endpoints en GKE.

Obtener la dirección IP externa del servicio

Necesitas la dirección IP externa del servicio para enviar solicitudes a la API de ejemplo. Pueden pasar unos minutos después de iniciar el servicio en el contenedor antes de que la dirección IP externa esté lista.

1. Para ver la dirección IP externa, haz lo siguiente:

   kubectl get ingress

2. Anota el valor de EXTERNAL-IP y guárdalo en una variable de entorno SERVER_IP. La dirección IP externa se usa para enviar solicitudes a la API de ejemplo.

   export SERVER_IP=YOUR_EXTERNAL_IP
   

Enviar una solicitud a la API

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. Crear una AC raíz para el certificado autofirmado

   openssl x509 -in server.crt -out client.pem -outform PEM
     

5. Envía una solicitud a la API de ejemplo:

   python bookstore_client.py --host SERVER_IP --port 443 \
   --servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
   

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