Esta página se ha traducido con Cloud Translation API.

Empezar a usar Endpoints para Kubernetes 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 clúster de Kubernetes que no se ejecuta enGoogle Cloud. En el 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:

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 localmente y configurar.

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.
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 el artículo sobre cómo 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 Service Infrastructure, la plataforma de servicios básica de Google que usan Endpoints y otros servicios para crear y gestionar APIs y servicios.

Asegúrate de que te encuentras en el directorio en el que están los archivos api_descriptor.pb y api_config.yaml.
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
```
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.

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.

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.

Crear credenciales para tu servicio

Para gestionar tu API, tanto ESP como ESPv2 requieren los servicios de Infraestructura de servicios. Para llamar a estos servicios, ESP y ESPv2 deben usar tokens de acceso. Cuando despliegas ESP o ESPv2 en entornos como GKE o Compute Engine, ESP y ESPv2 obtienen tokens de acceso a través del servicio de metadatos. Google Cloud Google Cloud

Cuando implementas ESP o ESPv2 en un entorno que no es deGoogle Cloud , como tu ordenador local, un clúster de Kubernetes local u otro proveedor de servicios en la nube, debes proporcionar un archivo JSON de cuenta de servicio que contenga una clave privada. ESP y ESPv2 usan la cuenta de servicio para generar tokens de acceso con los que llamar a los servicios que necesita para gestionar tu API.

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

Consola

En la Google Cloud consola, 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 se creó la API y haz clic en Abrir.
Haz clic en + Crear cuenta de servicio.
En el campo Nombre de cuenta de servicio, introduce el nombre de tu cuenta de servicio.
Haz clic en Crear.
Haz clic en Continuar.
Haz clic en Listo.
Haz clic en la dirección de correo de la cuenta de servicio que acabas de crear.
Haz clic en Teclas.
Haz clic en Añadir clave y, a continuación, en Crear clave.
Haz clic en Crear. Se descargará un archivo de clave JSON en tu ordenador.

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

`gcloud`

Introduce lo siguiente para mostrar los IDs de tus Google Cloud proyectos:
```
gcloud projects list
```
Sustituye PROJECT_ID en el siguiente comando para definir el proyecto predeterminado como aquel en el que se encuentra tu API:
```
gcloud config set project PROJECT_ID
```
Importante: Debes crear la cuenta de servicio en el mismo proyecto en el que se encuentra tu API.
Asegúrate de que la CLI de Google Cloud (gcloud) tenga autorización para acceder a tus datos y servicios en Google Cloud:
```
gcloud auth login
```
Si tienes más de una cuenta, asegúrate de elegir la cuenta que esté en el Google Cloud proyecto en el que se encuentra la API. Si ejecutas gcloud auth list, la cuenta que hayas seleccionado se mostrará como la cuenta activa del proyecto.
Para crear una cuenta de servicio, ejecuta el siguiente comando y sustituye SERVICE_ACCOUNT_NAME y My Service Account por el nombre y el nombre visible que quieras usar:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
   --display-name "My Service Account"
```
El comando asigna una dirección de correo a la cuenta de servicio con el siguiente formato:

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Esta dirección de correo es obligatoria en los comandos posteriores.

Crea un archivo de clave de cuenta de servicio:

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

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?

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

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 sirve de backend de la API. En esta sección se explica cómo desplegar contenedores precompilados para la API de muestra y ESPv2 en Kubernetes.

Proporcionar las credenciales de servicio a ESPv2

ESPv2, que se ejecuta en un contenedor, necesita acceder a las credenciales almacenadas de forma local en el archivo service-account-creds.json. Para proporcionar acceso a las credenciales a ESPv2, crea un secreto de Kubernetes y lo monta como un volumen de Kubernetes.

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

Si has usado la consola de Google Cloud para crear la cuenta de servicio, cambia el nombre del archivo JSON a service-account-creds.json. Mueve el archivo al mismo directorio donde 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 completa correctamente, se muestra el siguiente mensaje:

secret "service-account-creds" created

El archivo de manifiesto de implementación que usas para implementar la API y ESPv2 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/esp/creds
  name: service-account-creds
  readOnly: true

Configurar el nombre del servicio e iniciarlo

ESPv2 necesita saber el nombre de tu servicio para encontrar la configuración que desplegaste anteriormente con el comando gcloud endpoints services deploy.

Para configurar el nombre del servicio e iniciarlo, sigue estos pasos:

Guarda una copia del archivo de manifiesto de la implementación, grpc-bookstore.yaml, en el mismo directorio que service-account-creds.json.
Abre grpc-bookstore.yaml y sustituye SERVICE_NAME por el nombre de tu servicio de Endpoints. 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:2
  args: [
    "--listener_port=9000",
    "--service=SERVICE_NAME",
    "--rollout_strategy=managed",
    "--backend=grpc://127.0.0.1:8000",
    "--non_gcp",
    "--service_account_key=/etc/esp/creds/service-account-creds.json",
  ]
```
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.

Nota: Si usas MiniKube, debes cambiar el campo type del servicio de LoadBalancer a NodePort en el archivo de configuración.
Nota: 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 usa la versión más reciente.
Inicia el servicio para desplegarlo en Kubernetes:
```
kubectl create -f grpc-bookstore.yaml
```
Si aparece un mensaje de error similar al siguiente:
```
The connection to the server localhost:8080 was refused - did you specify the right host or port?
```
Esto indica que kubectl no está configurado correctamente. Para obtener más información, consulta Configurar kubectl.

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.

Para ver la dirección IP externa, haz lo siguiente:
```
kubectl get service
```
Anota el valor de EXTERNAL-IP y guárdalo en una variable de entorno SERVER_IP para usarlo al 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.

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

Cambia el 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 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.