En este instructivo, se muestra cómo implementar un ejemplo simple del servicio gRPC con el proxy de servicio extensible V2 (ESPv2) en Google Kubernetes Engine (GKE). Este instructivo
usa la versión de Python del
bookstore-grpc
muestra. Consulta la sección Pasos siguientes para ver muestras de gRPC en otros lenguajes.
Además, se usan imágenes de contenedor compiladas con anterioridad del código de muestra y el ESPv2, que se almacenan en Container Registry. Si no estás familiarizado con los contenedores, consulta las páginas siguientes para obtener más información:
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.
- Configura un proyecto de Google Cloud y descarga el software necesario. Consulta Antes de comenzar.
- Copia y configura archivos del
bookstore-grpc
muestra. Consulta Cómo configurar Endpoints. - Implementa la configuración de Endpoints para crear un servicio de Endpoints. Consulta Cómo configurar Endpoints.
- Crea un backend para entregar la API y, luego, implementarla. Consulta Implementa el backend de la API.
- Obtén la dirección IP externa del servicio. Consulta Cómo obtener la dirección IP externa del servicio.
- Envía una solicitud a la API. Consulta Enviar una solicitud a la API.
- Evita que se generen cargos en tu cuenta de Google Cloud. Consulta Realiza una limpieza.
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.
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
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.
- Toma nota del ID del proyecto de Google Cloud, ya que lo necesitarás más adelante.
- Instala y, luego, inicializa Google Cloud CLI.
- Actualiza la CLI de gcloud y, luego, instala los componentes de Endpoints.
gcloud components update
- Asegúrate de que Google Cloud CLI (
gcloud
) tenga autorización para acceder tus datos y servicios en Google Cloud: Se abrirá una nueva pestaña del navegador y se te solicitará que elijas una cuenta.gcloud auth login
- Configura el proyecto predeterminado con el ID de tu 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 quieres usar
gcloud
para administrarlos, consulta Administra parámetros de configuración de gcloud CLI. - Instala
kubectl
:gcloud components install kubectl
- Adquiere nuevas credenciales de usuario para usar como credenciales predeterminadas de la aplicación. Las credenciales del usuario son necesarias para autorizar
kubectl
. En la nueva pestaña del navegador que se abre, elige una cuenta.gcloud auth application-default login
- Sigue los pasos en la Guía de inicio rápido de Python de gRPC para instalar gRPC y sus herramientas.
Configura Endpoints
La bookstore-grpc
muestra contiene los archivos que debes copiar y configurar de forma local.
- Crea un archivo descriptor protobuf autónomo desde tu archivo de servicio
.proto
:- Guarda una copia de
bookstore.proto
del repositorio de ejemplo. Este archivo define la API del servicio de Bookstore. - Crea el directorio siguiente:
mkdir generated_pb2
- Crea
api_descriptor.pb
, el archivo descriptor, mediante el compilador de búferes de protocoloprotoc
. Ejecuta el comando siguiente en el directorio donde guardastebookstore.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 guardastebookstore.proto
.
- Guarda una copia de
- Crea un archivo de configuración YAML para la API de gRPC:
- Guarda una copia del archivo
api_config.yaml
. Este archivo define la configuración de la API de gRPC para el servicio de Bookstore. - 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 enbookstore.proto
dentro del paqueteendpoints.examples.bookstore
. Su nombre de API calificado por completo esendpoints.examples.bookstore.Bookstore
, tal como aparece en el archivoapi_config.yaml
.apis: - name: endpoints.examples.bookstore.Bookstore
- Guarda una copia del archivo
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.
- Asegúrate de estar en el directorio en el que se encuentran los archivos
api_descriptor.pb
yapi_config.yaml
. - 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
- 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 ybookstore.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 | Cargo |
---|---|
servicemanagement.googleapis.com |
API de Administración de servicios |
servicecontrol.googleapis.com |
API de Control de servicios |
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.comgcloud 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 Extremos 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 camponame
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 Implementar la configuración de Endpoints para obtener información adicional.
Implemente el backend de la API
Hasta ahora, implementaste la configuración de servicio en la Administración de servicios, pero aún no implementaste el código que entrega 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, así, implementar la API.
Cómo crear un clúster de contenedores
El clúster necesita un alias de IP para usar el balanceo de cargas nativo del contenedor. Para crear un clúster de contenedores con un alias de IP destinado a nuestro ejemplo:
gcloud container clusters create espv2-demo-cluster \ --enable-ip-alias \ --create-subnetwork="" \ --network=default \ --zone=us-central1-a
En el comando anterior, se crea un clúster, espv2-demo-cluster
, con una subred aprovisionada de forma automática en la zona us-central1-a
.
Autentica kubectl
al clúster del contenedor
Si quieres usar kubectl
para crear y administrar recursos de clústeres, necesitas obtener credenciales para tu clúster y hacer que estén disponibles para kubectl
. Para hacer esto, ejecuta el siguiente comando y reemplaza NAME por tu nuevo nombre de clúster y ZONE por su zona de clúster.
gcloud container clusters get-credentials NAME --zone ZONE
Verifica los permisos necesarios
El ESP y el ESPv2 llaman a los servicios de Google que usan IAM para verificar si la identidad de llamada tiene los permisos suficientes para acceder a los recursos de IAM usados. La identidad de llamada es la cuenta de servicio conectada que implementa el ESP y el ESPv2.
Cuando se implementa en el Pod de GKE, la cuenta de servicio conectada es la cuenta de servicio de nodo. Por lo general, 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 de nodo para comunicarse con los servicios de Google. Puedes crear una cuenta de servicio de Kubernetes para que el pod ejecute el ESP y el ESPv2, una cuenta de servicio de Google y puedes 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 a una cuenta de servicio de Google. Esta cuenta de servicio de Google es la cuenta de servicio conectada.
Si la cuenta de servicio conectada es la cuenta de servicio predeterminada de Compute Engine del proyecto, y la configuración del servicio de extremo se implementa en el mismo proyecto, la cuenta de servicio debe tener los permisos suficientes para acceder a los recursos de IAM. Se puede omitir el siguiente paso de configuración de las funciones de IAM. De lo contrario, se deben agregar las siguientes funciones de IAM a la cuenta de servicio conectada.
Agrega las funciones requeridas de IAM:
En esta sección, se describen los recursos de IAM que usan el ESP y el ESPv2 y las funciones de IAM necesarias para que la cuenta de servicio conectada acceda a estos recursos.
Configuración del servicio de extremo
El ESP y el ESPv2 llaman al Control de servicios que usa la configuración del servicio de extremo. La configuración del servicio de extremo es un recurso de IAM, por lo que el ESP y el ESPv2 necesitan la función de Controlador de servicio para acceder a él.
La función de IAM se encuentra en la configuración del servicio de extremo, no en el proyecto. Un proyecto puede tener múltiples opciones de configuración de servicio de extremo.
Usa el siguiente comando de gcloud a fin de agregar la función a la cuenta de servicio conectada para la configuración del servicio de extremo.
gcloud endpoints services add-iam-policy-binding SERVICE_NAME \ --member serviceAccount:SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com \ --role roles/servicemanagement.serviceController
En el ejemplo anterior
* SERVICE_NAME
es el nombre del servicio de extremo
* SERVICE_ACCOUNT_NAME@DEPLOY_PROJECT_ID.iam.gserviceaccount.com
es la cuenta de servicio conectada
Cloud Trace
El ESP y el ESPv2 llaman al servicio de Cloud Trace para exportar Trace a un proyecto. Este proyecto se llama proyecto de seguimiento. En el ESP, el proyecto de seguimiento y el proyecto que posee la configuración del servicio de extremo son los mismos. En el ESPv2, el proyecto de seguimiento se puede especificar con la marca --tracing_project_id
y, de forma predeterminada, se establece el proyecto de implementación.
ESP y ESPv2 requieren el agente de Cloud Trace para habilitar Cloud Trace.
Usa el siguiente comando de gcloud para agregar la función a la cuenta de servicio conectada:
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 conectada.
Para obtener más información, consulta
¿Qué son los roles y los permisos?
Configura tus claves y certificados SSL
El balanceo de cargas nativo del contenedor usa el balanceador de cargas de HTTP2, que debe estar encriptado mediante TLS. Esto requería la implementación de un certificado TLS en Ingress de GKE y en el ESPv2. Puedes usar tu propio certificado o uno autofirmado.
Crea una clave y un certificado autofirmado con openssl. Asegúrate de haber ingresado el mismo FQDN
bookstore.endpoints.MY_PROJECT_ID.cloud.goog
cuando se te solicite 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
Crea un secreto de Kubernetes con tu clave y certificado SSL. Ten en cuenta que el certificado se copia en dos lugares,
server.crt
ytls.crt
, ya que el secreto se proporciona al Ingress de GKE y al ESPv2. Ingress de GKE busca la ruta de certificadotls.crt
y el ESPv2 busca la ruta de certificadoserver.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
Implementa la API de muestra y el ESPv2 en el clúster
Para implementar el servicio gRPC de muestra en el clúster de manera que los clientes puedan usarlo, sigue estos pasos:
git clone
este repositorio y abre para editar el archivo de manifiesto de implementación grpc-bookstore.yaml.- Reemplaza SERVICE_NAME por el nombre de tu servicio de Endpoints para la entrada y el contenedor de ESPv2.
Este es el mismo nombre que configuraste en el campo
name
del archivoapi_config.yaml
.La opción
--rollout_strategy=managed
configura el ESPv2 para que use la última configuración del servicio implementada. Cuando especificas esta opción, el ESPv2 detecta el cambio y comienza a aplicarlo de forma automática dentro del minuto siguiente a la implementación de una configuración de servicio nueva. Te recomendamos que especifiques esta opción en lugar de proporcionar un ID de configuración específico para que use el ESPv2. Si quieres obtener más detalles sobre los argumentos del ESPv2, consulta las opciones de inicio del 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" ]
- Inicia el servicio:
kubectl create -f grpc-bookstore.yaml
Si recibes un mensaje de error, consulta Cómo solucionar problemas de Cloud Endpoints en GKE.
Cómo obtener la dirección IP externa de la API
Necesitas la dirección IP externa del servicio para enviar solicitudes a la API de muestra. Es posible que la dirección IP externa tarde unos minutos en estar lista después de que inicies tu servicio en el contenedor.
Para ver la dirección IP externa, sigue estos pasos:
kubectl get ingress
Toma nota del 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 muestra.export SERVER_IP=YOUR_EXTERNAL_IP
Envía una solicitud a la API
Para enviar solicitudes a la API de muestra, puedes usar un cliente gRPC de muestra escrito en Python.
Clona el repositorio de Git donde se aloja el código del cliente gRPC:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Cambia tu directorio de trabajo:
cd python-docs-samples/endpoints/bookstore-grpc/
Instala las dependencias:
pip install virtualenv
virtualenv env
source env/bin/activate
python -m pip install -r requirements.txt
Crea una CA raíz para el certificado autofirmado
openssl x509 -in server.crt -out client.pem -outform PEM
Envía una solicitud a la API de muestra:
python bookstore_client.py --host SERVER_IP --port 443 \ --servername bookstore.endpoints.MY_PROJECT_ID.cloud.goog --use_tls true --ca_path=client.pem
Para ver los grafos de actividad de tu API, ve a la página Endpoints > Servicios.
Ir a la página Servicios de Endpoints
La solicitud puede tardar unos minutos en reflejarse en los gráficos.
Revisa los registros de solicitud de tu API en la página del visor de registros.
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.
Borra la API:
gcloud endpoints services delete SERVICE_NAME
Reemplaza SERVICE_NAME por el nombre de tu API.
Borra el clúster de GKE:
gcloud container clusters delete NAME --zone ZONE
¿Qué sigue?
- Descubre cómo configurar tu propia API de gRPC para Cloud Endpoints
- Mirar la muestra de la Librería 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: