Se usó la API de Cloud Translation para traducir esta página.

Comienza a usar Endpoints para Kubernetes con el ESP

OpenAPI | gRPC

En este instructivo, se muestra cómo implementar un ejemplo simple gRPC con las Proxy de servicio extensible (ESP) a un clúster de Kubernetes que no se está ejecutando en en Google Cloud. En este instructivo, se usa la versión de Python de la bookstore-grpc muestra. Consulta la sección Próximos pasos 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 ESP, 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 Configura Cloud Endpoints.
Implementa la configuración de Endpoints para crear un servicio de Endpoints. Consulta Cómo configurar Endpoints.
Crea credenciales para tu servicio de Endpoints. Consulta Crear credenciales para tu servicio.
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 Limpiar.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Endpoints

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

En este instructivo, se supone que ya configuraste un clúster de Kubernetes o Minikube. Para obtener más información, consulta la documentación de Kubernetes.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Anota el ID del proyecto de Google Cloud porque se necesita más tarde.
Instala e inicializa gcloud CLI
Actualiza gcloud CLI y, luego, instala los extremos o los componentes de la solución.
```
gcloud components update
```
Asegúrate de que Google Cloud CLI (gcloud) tenga autorización para acceder tus datos y servicios en Google Cloud:
```
gcloud auth login
```
En la pestaña nueva que se abre, selecciona una cuenta.
Configura el proyecto predeterminado como el ID de tu proyecto:
```
gcloud config set project
    YOUR_PROJECT_ID
```
Reemplaza YOUR_PROJECT_ID con tu ID del proyecto de Google Cloud.

Si tienes otros proyectos de Google Cloud y quieres usar gcloud para administrarlos, consulta Administra gcloud CLI parámetros de configuración.
Instala kubectl:
```
gcloud components install kubectl
```
Adquiere credenciales de usuario nuevo para usar como credenciales predeterminadas de la aplicación. Se necesitan las credenciales de usuario para autorizar a kubectl.
```
gcloud auth application-default login
```
Se abrirá una nueva pestaña del navegador donde debes elegir una cuenta.
Sigue los pasos en la Guía de inicio rápido de Python de gRPC para instalar gRPC y sus herramientas.

Configura Endpoints

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

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.
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 Configura Endpoints para obtener más información.

Implementa la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el gcloud endpoints services deploy kubectl. Este comando usa Service Infrastructure, la plataforma básica de servicios de Google, que Endpoints y otros servicios usan para crear y administrar las API y los servicios.

Make sure you are in the directory where the api_descriptor.pb and api_config.yaml files are located.
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
```
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.

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.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 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 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 Implementa la configuración de Endpoints para obtener más información.

Crear credenciales para tu servicio

A fin de proporcionar administración a tu API, el ESP y el ESPv2 requieren los servicios de la infraestructura del servicio. Para llamar a estos servicios, el ESP y el ESPv2 deben usar tokens de acceso. Cuando implementas el ESP o el ESPv2 Beta en entornos de Google Cloud, como GKE o Compute Engine, el ESP y el ESPv2 obtienen tokens de acceso mediante el servicio de metadatos de Google Cloud.

Cuando implementas el ESP o ESPv2 en un entorno que no es de Google Cloud, como como tu computadora de escritorio local, un clúster de Kubernetes local o cualquier otra nube debes proporcionar un archivo JSON de cuenta de servicio que contiene una clave privada. El ESP y el ESPv2 usan el cuenta de servicio para generar tokens de acceso y llamar a los servicios que necesita para administrar tu API.

Puedes usar la consola de Google Cloud o Google Cloud CLI para crear la cuenta de servicio y el archivo de claves privadas:

Console

En la consola de Google Cloud, abre la página Cuentas de servicio .
Ir a la página Cuentas de servicio
Haz clic en Seleccionar un proyecto.
Selecciona el proyecto en el que creaste tu API y haz clic en Abrir.
Haz clic en + Crear cuenta de servicio.
En el campo Nombre de la cuenta de servicio, ingresa el nombre de tu cuenta de servicio.
Haga clic en Crear.
Haz clic en Continuar.
Haz clic en Listo.
Haz clic en la dirección de correo electrónico de la cuenta de servicio recién creada.
Haga clic en Claves.
Haz clic en Agregar clave, luego haz clic en Crear clave nueva.
Haz clic en Crear. Se descargará un archivo de claves JSON en tu computadora.

Asegúrate de almacenar el archivo de claves de forma segura, ya que se puede usar para autenticarse como tu cuenta de servicio. Puedes mover y cambiar el nombre de este archivo como desees.
Haz clic en Cerrar.

`gcloud`

Ingresa lo siguiente para mostrar los ID de tus proyectos de Google Cloud:
```
gcloud projects list
```
Reemplaza PROJECT_ID en el comando siguiente para definir el proyecto predeterminado donde está tu API:
```
gcloud config set project PROJECT_ID
```
Importante: Debes crear la cuenta de servicio en el mismo proyecto que se encuentra tu API.
Asegúrate de que Google Cloud CLI (gcloud) tenga autorización para acceder a tu datos y servicios en Google Cloud:
```
gcloud auth login
```
Si tienes más de una cuenta, asegúrate de elegir la que está en el proyecto de Google Cloud en el que se encuentra la API. Si ejecutas gcloud auth list, la cuenta que seleccionaste se muestra como la cuenta activa para el proyecto.
Para crear una cuenta de servicio, ejecuta el comando siguiente y reemplaza SERVICE_ACCOUNT_NAME y My Service Account por el nombre y el nombre comercial que quieres usar:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
Con el comando, se asigna una dirección de correo electrónico para la cuenta de servicio en este formato:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Esta dirección de correo electrónico se requiere en los comandos posteriores.

Crea un archivo de claves de la cuenta de servicio:

gcloud iam service-accounts keys create ~/service-account-creds.json \
   --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

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?

Consulta gcloud iam service-accounts para obtener más información sobre los comandos.

Implementa el backend de la API

Hasta ahora, implementaste la configuración del servicio en Service Management, pero aún no implementaste el código que entregará el backend de la API. En esta sección, aprenderás a implementar contenedores compilados con anterioridad para el ESP y la API de muestra en Kubernetes.

Cómo proporcionar las credenciales de servicio al ESP

El ESP, que se ejecuta dentro de un contenedor, necesita acceder a las credenciales almacenadas de forma local en el archivo service-account-creds.json. Para proporcionar ESP con acceso a las credenciales, creas un Secreto de Kubernetes y activar el secreto de Kubernetes Volumen de Kubernetes.

Para crear el secreto de Kubernetes y activar el volumen, sigue estos pasos:

Si usaste la consola de Google Cloud para crear la cuenta de servicio, cambia el nombre el archivo JSON a service-account-creds.json. Muévelo al mismo directorio en el que se encuentran los archivos api_descriptor.pb y api_config.yaml.
Crea un Secreto de Kubernetes con las credenciales de la cuenta de servicio:
```
 kubectl create secret generic service-account-creds
      --from-file=service-account-creds.json
```
Si se realiza de forma correcta, verás el mensaje secret "service-account-creds" created.

El archivo de manifiesto de implementación que usas para implementar la API y el ESP en Kubernetes ya contiene el volumen secreto, como se muestra en las dos secciones siguientes del archivo:

volumes:
  - name: service-account-creds
    secret:
      secretName: service-account-creds

volumeMounts:
  - mountPath: /etc/nginx/creds
    name: service-account-creds
    readOnly: true

Cómo configurar el nombre de servicio y cómo iniciar el servicio

ESP necesita saber el nombre de tu servicio para buscar la configuración que implementaste con anterioridad con el comando gcloud endpoints services deploy.

Para configurar el nombre del servicio y luego iniciar el servicio, sigue estos pasos:

Guarda una copia del archivo de manifiesto de implementación, k8s-grpc-bookstore.yaml, en el mismo directorio que service-account-creds.json.
Abre k8s-grpc-bookstore.yaml y reemplaza SERVICE_NAME por el nombre de tu servicio de Endpoints. Este es el mismo nombre que configuraste en el campo name del archivo api_config.yaml.
```
containers:
  - name: esp
    image: gcr.io/endpoints-release/endpoints-runtime:1
    args: [
      "--http2_port=9000",
      "--service=SERVICE_NAME",
      "--rollout_strategy=managed",
      "--backend=grpc://127.0.0.1:8000",
      "--service_account_key=/etc/nginx/creds/service-account-creds.json"
    ]
```
La opción --rollout_strategy=managed configura el ESP para que use la última configuración del servicio implementada. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP. Si quieres obtener más detalles sobre los argumentos del ESP, consulta Opciones de inicio de ESP.

Nota: Si usas MiniKube, debes cambiar el campo type del servicio de LoadBalancer a NodePort en el archivo de configuración.
Nota: Te recomendamos configurar imagePullPolicy en la especificación del contenedor anterior como Always. Esto permitirá que los pods recién creados siempre extraigan la versión más reciente del ESP. Lee sobre las prácticas recomendadas de configuración para obtener más detalles. Cuando se lanza una versión nueva del ESP, puedes realizar un reinicio progresivo de todos los pods para garantizar que se use la versión más reciente.
Inicia el servicio para implementar el servicio en Kubernetes:
```
kubectl create -f k8s-grpc-bookstore.yaml
```
Podría aparecer un mensaje de error similar a este:
```
The connection to the server localhost:8080 was refused - did you specify the right host or port?
```
Esto indica que kubectl no está configurado de forma correcta. Consulta Configura kubectl para obtener más información.

Obtén 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.

Visualiza la dirección IP externa:
```
kubectl get service
```
Toma nota del valor de EXTERNAL-IP y guárdalo en una variable de entorno SERVER_IP como se usaba al momento de 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

Envía una solicitud a la API de muestra:
```
python bookstore_client.py --host SERVER_IP --port 80
```
- 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.
  
  Ir a la página Explorador 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 los extremos.
Configura DNS:
- Configura un DNS en el dominio cloud.goog.
- Verifica un nombre de dominio
Revisa la app de muestra de Bookstore con más detalle en GitHub. Tanto el cliente como 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