En este tutorial se muestra cómo configurar y desplegar una API de ejemplo y Extensible Service Proxy V2 (ESPv2) en un clúster de Google Kubernetes Engine (GKE).
La API REST del código de ejemplo se describe mediante la especificación de OpenAPI. En el tutorial también se explica cómo crear una clave de API y usarla al enviar solicitudes a la API.
En el tutorial se usan imágenes de contenedor precompiladas del código de ejemplo y ESPv2, que se almacenan en Artifact Registry.
Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y Arquitectura de Endpoints.
Descargar el código de ejemplo
Para ayudarte a ponerte en marcha rápidamente, se proporciona código de ejemplo en varios idiomas. Para descargar el código de muestra en tu máquina local, sigue estos pasos:
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/GoogleCloudPlatform/java-docs-samples
También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.
- Accede al directorio que contiene el código de muestra:
cd java-docs-samples/endpoints/getting-started
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/GoogleCloudPlatform/python-docs-samples
También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.
- Accede al directorio que contiene el código de muestra:
cd python-docs-samples/endpoints/getting-started
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Asegúrate de que la
variable de entorno
GOPATHesté definida. - Clona el repositorio de aplicaciones de muestra en la máquina local:
go get -d github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
- Accede al directorio que contiene el código de muestra:
cd $GOPATH/src/github.com/GoogleCloudPlatform/golang-samples/endpoints/getting-started
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/GoogleCloudPlatform/php-docs-samples
También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.
- Accede al directorio que contiene el código de muestra:
cd php-docs-samples/endpoints/getting-started
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples
También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.
- Accede al directorio que contiene el código de muestra:
cd ruby-docs-samples/endpoints/getting-started
Para clonar o descargar la API de ejemplo, sigue estos pasos:
- Clona el repositorio de aplicaciones de muestra en la máquina local:
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples
También puedes descargar el archivo de ejemplo como archivo ZIP y extraerlo.
- Accede al directorio que contiene el código de muestra:
cd nodejs-docs-samples/endpoints/getting-started
Configurar Endpoints
El código de ejemplo incluye el archivo de configuración de OpenAPI, openapi.yaml, que se basa en la especificación de OpenAPI v2.0.
Para configurar Endpoints, haz lo siguiente:
- En el directorio de código de ejemplo, abre el archivo de configuración
openapi.yaml.Java Python Ir PHP Ruby NodeJS Ten en cuenta lo siguiente:
- En el ejemplo de configuración se muestran las líneas cercanas al campo
host, que debe modificar. Para desplegar el archivoopenapi.yamlen Endpoints, se necesita el documento OpenAPI completo. - El archivo de ejemplo
openapi.yamlcontiene una sección para configurar la autenticación que no es necesaria en este tutorial. No es necesario configurar las líneas con YOUR-SERVICE-ACCOUNT-EMAIL y YOUR-CLIENT-ID. - OpenAPI es una especificación independiente del lenguaje. El mismo archivo
openapi.yamlse encuentra en el ejemplogetting-startedde cada repositorio de GitHub de idioma para mayor comodidad.
- En el ejemplo de configuración se muestran las líneas cercanas al campo
- En el campo
host, sustituye el texto por el nombre del servicio Endpoints, que debe tener el siguiente formato:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog"
Sustituye YOUR_PROJECT_ID por el ID de tu proyecto. Google Cloud Por ejemplo:
host: "echo-api.endpoints.example-project-12345.cloud.goog"
Ten en cuenta que echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
es el nombre del servicio Endpoints. No es el nombre de dominio completo (FQDN) que usas para enviar solicitudes a la API.
Para obtener información sobre los campos del documento OpenAPI que requiere Endpoints, consulta Configurar Endpoints.
Una vez que hayas completado todos los pasos de configuración que se indican a continuación para poder enviar solicitudes a la API de ejemplo correctamente mediante una dirección IP, consulta Configurar el DNS de los endpoints para obtener información sobre cómo configurar echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog como FQDN.
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.
Para desplegar la configuración de Endpoints, sigue estos pasos:
- Asegúrate de que estás en el directorio
endpoints/getting-started. - Sube la configuración y crea un servicio gestionado:
gcloud endpoints services deploy openapi.yaml
El comando gcloud llama a la API Service Management para crear un servicio gestionado con el nombre que has especificado en el campo host del archivo openapi.yaml.
Gestión de servicios configura el servicio según los ajustes del archivo openapi.yaml. Cuando hagas cambios en openapi.yaml, debes volver a implementar el archivo para actualizar el servicio Endpoints.
Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Puedes ignorar las advertencias sobre las rutas del archivo openapi.yaml que no requieren una clave de API.
Cuando termine de configurar el servicio, Service Management mostrará un mensaje con el ID de configuración del servicio y el nombre del servicio, similar al siguiente:
Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]
En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el servicio Endpoints. El ID de configuración del servicio consta de una marca de fecha seguida de un número de revisión. Si vuelves a implementar el archivo openapi.yaml el mismo día, el número de revisión se incrementará en el ID de configuración del servicio. Puedes ver la configuración del servicio Endpoints en la página Endpoints > Services (Servicios) de la consola de Google Cloud .
Si aparece un mensaje de error, consulta Solucionar problemas de despliegue de 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.comTambié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
hostde tu especificación de OpenAPI. En gRPC, ENDPOINTS_SERVICE_NAME es el valor que has especificado en el camponamede tu configuración de endpoints de gRPC.
Para obtener más información sobre los comandos de gcloud, consulta los servicios de gcloud.
Desplegar el backend de la API
Hasta ahora, has implementado el documento OpenAPI en Service Management, pero aún no has implementado 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 ejemplo y ESPv2 en el clúster.
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?
Desplegar los contenedores en el clúster
Los contenedores constituyen un mecanismo de empaquetado lógico en el que puedes abstraer las aplicaciones del entorno en el que se ejecutan realmente. Para desplegar la API de ejemplo y ESPv2 en el clúster, sigue este procedimiento. Para desplegar los contenedores en el clúster, sigue estos pasos:
- Obtén las credenciales del clúster y ponlas a disposición de
kubectl:gcloud container clusters get-credentials NAME --zone ZONE - Despliega un servicio de Kubernetes en el clúster de GKE. El servicio de Kubernetes implementa la API.
git cloneeste repositorio,cd getting-started/a la carpeta y edita el archivo de configuración de KubernetesLANG-deployment.yaml, y sustituye SERVICE_NAME en las opciones de inicio del ESPv2 por el nombre de tu servicio.Java Python Ir PHP Ruby NodeJS Por ejemplo:
args: [ "--listener_port=8081", "--backend=http://127.0.0.1:8080", "--service=echo-api.endpoints.example-project-12345.cloud.goog ", "--rollout_strategy=managed", ]La opción
--rollout_strategy=managedconfigura 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 información sobre las otras opciones de ESPv2 que se usan, consulta Opciones de inicio de ESPv2.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=managedpara 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
Sigue los pasos que se indican a continuación para montar la configuración del servicio:--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.- Descarga la configuración JSON del servicio.
- Crea un recurso de mapa de configuración de Kubernetes a partir de la configuración JSON.
- Monta el recurso de mapa de configuración en el contenedor y usa la marca
--service_config_pathpara especificar la ruta del archivo de configuración.
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"
kubectl create configmap service-config-configmap \ --from-file=service_config.json:/tmp/service_config.json
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 - Inicia el servicio de Kubernetes con el comando
kubectl apply:Java kubectl apply -f java-deployment.yaml
Python kubectl apply -f python-deployment.yaml
Ir kubectl apply -f golang-deployment.yaml
PHP kubectl apply -f php-deployment.yaml
Ruby kubectl apply -f ruby-deployment.yaml
NodeJS kubectl apply -f nodejs-deployment.yaml
Si aparece un mensaje de error, consulta Solucionar problemas de endpoints en GKE. Consulta más información en el artículo sobre desplegar el backend de la API.
Obtener la dirección IP externa del clúster
Para enviar solicitudes a la API, necesitas la IP externa del servicio. Pueden pasar unos minutos desde que inicies el servicio en el contenedor hasta que la dirección IP externa esté lista.
- Para ver la dirección IP externa, haz lo siguiente:
kubectl get ingress
- Anota el valor de
EXTERNAL-IP. Utiliza esa dirección IP cuando envíes una solicitud a la API de ejemplo.
Enviar una solicitud mediante una dirección IP
Ahora que el servicio se está ejecutando en el clúster de contenedores y tienes la dirección IP externa, puedes enviar solicitudes a la API.
Crear una clave de API y definir una variable de entorno
El código de ejemplo requiere una clave de API. Para simplificar la solicitud, puedes definir una variable de entorno para la clave de API.
En el mismo Google Cloud proyecto que usaste para tu API, crea una clave de API en la página de credenciales de la API. Si quieres crear una clave de API en otro Google Cloud proyecto, consulta el artículo sobre cómo habilitar una API en tu Google Cloud proyecto.
- Haz clic en Crear credenciales y, a continuación, selecciona Clave de API.
- Copia la clave en el portapapeles.
- Haz clic en Cerrar.
- En tu ordenador local, pega la clave de API para asignarla a una variable de entorno:
- En Linux o macOS:
export ENDPOINTS_KEY=AIza... - En Windows PowerShell:
$Env:ENDPOINTS_KEY="AIza..."
- En Linux o macOS:
Enviar la solicitud
Linux o macOS
Usa curl para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_KEY que has definido anteriormente. Sustituye IP_ADDRESS por la dirección IP externa de tu instancia.
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://IP_ADDRESS:80/echo?key=${ENDPOINTS_KEY}"
En los curl anteriores:
- La opción
--dataespecifica los datos que se van a enviar a la API. - La opción
--headerespecifica que los datos están en formato JSON.
PowerShell
Usa Invoke-WebRequest para enviar una solicitud HTTP mediante la variable de entorno ENDPOINTS_KEY que has definido anteriormente. Sustituye IP_ADDRESS por la dirección IP externa de tu instancia.
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' ` -Headers @{"content-type"="application/json"} ` -URI "http://IP_ADDRESS:80/echo?key=$Env:ENDPOINTS_KEY").Content
En el ejemplo anterior, las dos primeras líneas terminan en una comilla inversa. Cuando pegues el ejemplo en PowerShell, asegúrate de que no haya ningún espacio después de las comillas inversas. Para obtener información sobre las opciones que se usan en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.
Aplicación de terceros
Puedes usar una aplicación de terceros, como la extensión Postman del navegador Chrome, para enviar la solicitud:
- Selecciona
POSTcomo verbo HTTP. - En el encabezado, selecciona la clave
content-typey el valorapplication/json. - En el cuerpo, introduce lo siguiente:
{"message":"hello world"} -
En la URL, usa la clave de API real en lugar de la variable de entorno.
Por ejemplo:
http://192.0.2.0:80/echo?key=AIza...
La API devuelve el mensaje que envías y responde con lo siguiente:
{
"message": "hello world"
}
Si no has recibido una respuesta correcta, consulta el artículo Solucionar problemas de errores de respuesta.
Acabas de desplegar y probar una API en Endpoints.
Monitorizar la actividad de la API
Para monitorizar la actividad de la API, siga estos pasos:
- 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.
Configurar DNS para Endpoints
Como el nombre del servicio Endpoints de la API está en el dominio .endpoints.YOUR_PROJECT_ID.cloud.goog, puedes usarlo como nombre de dominio completo (FQDN) haciendo un pequeño cambio de configuración en el archivo openapi.yaml. De esta forma, puedes enviar solicitudes a la API de ejemplo mediante echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog
en lugar de la dirección IP.
Para configurar el DNS de Endpoints, sigue estos pasos:
- Abre el archivo de configuración de OpenAPI,
openapi.yaml, y añade la propiedadx-google-endpointsen el nivel superior del archivo (sin sangría ni anidación), como se muestra en el siguiente fragmento:host: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog" target: "IP_ADDRESS" - En la propiedad
name, sustituye YOUR_PROJECT_ID por el ID de tu proyecto. - En la propiedad
target, sustituya IP_ADDRESS por la dirección IP que usó cuando envió una solicitud a la API de ejemplo. - Despliega el archivo de configuración de OpenAPI actualizado en Service Management:
gcloud endpoints services deploy openapi.yaml
Por ejemplo, supongamos que el archivo openapi.yaml tiene la siguiente configuración:
host: "echo-api.endpoints.example-project-12345.cloud.goog" x-google-endpoints: - name: "echo-api.endpoints.example-project-12345.cloud.goog" target: "192.0.2.1"
Cuando implementas el archivo openapi.yaml con el comando gcloud anterior, Service Management crea un registro A de DNS, echo-api.endpoints.my-project-id.cloud.goog, que se resuelve en la dirección IP de destino, 192.0.2.1. La nueva configuración de DNS puede tardar unos minutos en propagarse.
Configurar SSL
Para obtener más información sobre cómo configurar DNS y SSL, consulta Habilitar SSL para endpoints.
Enviar una solicitud mediante el FQDN
Ahora que has configurado el registro DNS de la API de ejemplo, envíale una solicitud mediante el FQDN (sustituye YOUR_PROJECT_ID por el ID de tu proyecto) y la variable de entorno ENDPOINTS_KEY que has definido anteriormente:- En Linux o macOS:
curl --request POST \ --header "content-type:application/json" \ --data '{"message":"hello world"}' \ "http://echo-api.endpoints.YOUR_PROJECT_ID.cloud.goog:80/echo?key=${ENDPOINTS_KEY}"
- En Windows PowerShell:
(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' -Headers @{"content-type"="application/json"} -URI "http://echo-api.endpoints.[YOUR_PROJECT_ID].cloud.goog:80/echo?key=$Env:ENDPOINTS_KEY").Content