Configura OpenAPI de Cloud Endpoints para la publicación de Knative con ESPv2

En esta página, se muestra cómo configurar Cloud Endpoints para publicación de Knative. Endpoints usa el proxy de servicio extensible V2 (ESPv2) como una puerta de enlace de la API. Si deseas proporcionar administración de API para Knative serving, implementa el contenedor de ESPv2 previamente compilado en Knative serving que se ejecuta en un clúster de GKE.

Con esta configuración, el ESPv2 intercepta todas las solicitudes a tus servicios y realiza las verificaciones necesarias (como la autenticación) antes de invocar el servicio. Cuando el servicio responde, ESPv2 recopila y, luego, informa la telemetría.

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

Lista de tareas

Usa la siguiente lista de tareas mientras trabajas en el instructivo. Todas las tareas son obligatorias para completar el instructivo.

  1. Crea un proyecto de Google Cloud y, si no has implementado tu propio servicio de Knative, implementa un servicio de muestra. Consulta Antes de comenzar.

  2. Crea un clúster de GKE con la publicación de Knative habilitada.

  3. Implementa un servicio de entrega de Knative de muestra.

  4. Crea un documento de OpenAPI que describa tu API de Endpoints y configura las rutas a tu servicio de entrega de Knative. Consulta Cómo configurar Endpoints.

  5. Implementa el documento de OpenAPI para crear un servicio administrado. Consulta Cómo implementar la configuración de Endpoints.

  6. Compila una nueva imagen de Docker del ESPv2 con tu configuración de servicio de Endpoints. Consulta Compila una imagen de ESPv2 nueva.

  7. Implementa la nueva imagen de Knative serving de ESPv2. Consulta Implementa la imagen de ESPv2 de Cloud Run.

  8. Crea una asignación de dominio al servicio de Knative serving de ESPv2.

  9. Prueba la configuración mediante el envío de una solicitud a la API.

  10. Realiza un seguimiento de la actividad de tus servicios. Consulta Cómo realizar un seguimiento de la actividad de la API.

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

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

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

    Go to project selector

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

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

    Go to project selector

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

  6. Toma nota del ID del proyecto, ya que lo necesitarás más tarde. En el resto de esta página, este ID del proyecto se denomina ESP_PROJECT_ID.
  7. Descarga y, luego, instala el SDK de Google Cloud.
  8. Instala cURL si deseas enviar una solicitud al servicio de muestra implementado.

Configura la línea de comandos de gcloud

Para configurar gcloud CLI para la publicación de Knative en Anthos, haz lo siguiente:

  1. Asegúrate de que el SDK de Google Cloud tenga autorización para acceder a tus datos y servicios.

    1. Accede. 

      gcloud auth login

    2. En la nueva pestaña del navegador que se abre, elige una cuenta que tenga el rol de Editor o Propietario en el proyecto de Google Cloud que creaste para implementar ESPv2 en la entrega de Knative.

  2. Actualiza los componentes de gcloud instalados: 

    gcloud components update

  3. Configura la plataforma en gke y establece la configuración del proyecto predeterminado para gcloud al que acabas de crear:

    gcloud config set run/platform gke 
gcloud config set project ESP_PROJECT_ID

    Reemplaza ESP_PROJECT_ID por el ID del proyecto que creaste.

  4. Configura la zona deseada del clúster nuevo. Puedes usar cualquier zona que admita GKE, por ejemplo: 

    gcloud config set compute/zone ZONE

    Reemplaza ZONE por la zona. Por ejemplo, usa us-central1-a. Puedes usar cualquier zona que admita GKE

  5. Habilita las siguientes APIs para el proyecto, que son necesarias para crear un clúster, compilar y publicar un contenedor en Artifact Registry: 

    gcloud services enable container.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

Crea un clúster de GKE con el servicio de Knative habilitado

Para crear un clúster y habilitarlo en la entrega de Knative en Google Cloud, haz lo siguiente:

  1. Crea un clúster nuevo mediante el siguiente comando: 

    gcloud container clusters create CLUSTER_NAME \ 
  --addons=HttpLoadBalancing,CloudRun \ 
  --machine-type=n1-standard-4 \ 
  --num-nodes=3 \ 
  --enable-stackdriver-kubernetes

    Reemplaza CLUSTER_NAME por el nombre que deseas para el clúster.

    Aunque estas instrucciones no habilitan el ajuste de escala automático del clúster para cambiar el tamaño de los clústeres según la demanda, Knative serving en Google Cloud escala instancias automáticamente dentro del clúster.

  2. Espera a que termine de crearse el clúster. Durante el proceso de creación, deberías ver mensajes similares a los siguientes: 

    Creating cluster CLUSTER_NAME...done. 
Created [https://container.googleapis.com/v1/projects/ESP_PROJECT_ID/zones/ZONE/clusters/CLUSTER_NAME].

    En el resultado, también se muestra la versión del clúster en la columna NODE_VERSION del resultado. Por ejemplo, 1.15.11-gke.1 o 1.14.10-gke.27. Toma nota de la versión del clúster para usarla más adelante en este documento.

  3. Configura los valores predeterminados de gcloud para usar el clúster nuevo y la ubicación del clúster, a fin de evitar tener que especificarlos cuando uses gcloud CLI: 

    gcloud config set run/cluster CLUSTER_NAME
gcloud config set run/cluster_location ZONE

  4. Usa el siguiente comando para ver los detalles del clúster nuevo:

    gcloud container clusters describe CLUSTER_NAME

  5. Usa el siguiente comando a fin de recuperar credenciales para tu clúster:

    gcloud container clusters get-credentials CLUSTER_NAME

Implementa un contenedor de Knative serving de muestra

Para implementar el contenedor de muestra de Knative serving de “hello” en el clúster que acabas de crear, haz lo siguiente:

  1. Ir a Cloud Run

  2. Haz clic en Crear servicio.

  3. Selecciona Knative serving como tu plataforma de desarrollo.

  4. En el menú desplegable de clústeres disponibles, selecciona el clúster que acabas de crear.

  5. Usa hello como nombre del servicio. Puedes usar otro nombre, pero si lo haces, asegúrate de usarlo más adelante. En estas instrucciones, suponemos que usas hello.

  6. Selecciona Interna en Conectividad para que el servicio no sea accesible de manera externa.

  7. Haz clic en Next (Siguiente) para ir a la segunda página del formulario de creación de servicios:

  8. Especifica gcr.io/cloudrun/hello como la URL de la imagen del contenedor.

  9. Haz clic en Crear para implementar la imagen en Knative serving y espera a que termine la implementación.

    Cuando hayas terminado, aparecerá la pantalla Revisiones. Ten en cuenta que la URL del servicio implementado es la siguiente:

    http://hello.default.svc.cluster.local

    Cuando creas un servicio interno, GKE crea un nombre de DNS que solo se puede resolver en las solicitudes que se originan dentro del mismo clúster, no en las solicitudes externas. No puedes acceder a este vínculo de forma externa desde el clúster. Consulta los servicios de Cloud Run para obtener más información.

  10. Para verificar que tu servicio funcione correctamente mediante cURL, configura un túnel desde tu computadora de escritorio hacia el clúster. Para ver estas instrucciones, haz clic en el ícono a la derecha de la URL en la pantalla Revisiones:

    Pantalla de revisiones

  11. Se abrirá un panel en el que se muestran los dos comandos que usas para acceder al servicio interno. Debes ejecutar estos comandos en dos ventanas diferentes de la terminal, ya que el primer comando configura la redirección de puertos que usa el segundo comando.

    Cuando ejecutes el comando de cURL, deberías ver un resultado del servicio con el siguiente formato:

    <!doctype html>
<html lang=en> 
<head> 
<meta charset=utf-8> 
<meta name="viewport" content="width=device-width, initial-scale=1"> 
<title>Congratulations | Cloud Run</title> 
...

Configura Endpoints

Debes tener un documento de OpenAPI basado en la especificación de OpenAPI v2.0 que describa la superficie de tu servicio de backend y cualquier requisito de autenticación. También debes agregar un campo específico de Google que contenga la URL de cada servicio para que ESPv2 tenga la información que necesita para invocar un servicio. Si es la primera vez que usas OpenAPI, consulta Descripción general de OpenAPI para obtener más información.

Información sobre la configuración del campo de host de las especificaciones de OpenAPI

En el campo host de la especificación de OpenAPI, debes especificar el nombre del servicio de Endpoints que se usó para acceder al servicio de Knative serving. El nombre del servicio de Endpoints tiene la forma de un nombre de dominio: 

API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

Debido a que el nombre del servicio de Endpoints corresponde a un nombre de dominio, el nombre debe seguir estas reglas:

  • Debe contener solo letras en minúscula, números, puntos o guiones.
  • No debe comenzar con un guion.
  • No debe contener un guion bajo.

Por ejemplo:

hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

Crea la especificación de OpenAPI

  1. Crea un archivo de texto denominado openapi-run-anthos.yaml.

  2. Tu servicio de backend de Knative serving se define en la parte superior del archivo openapi-run-anthos.yaml, en una definición x-google-backend. Por ejemplo: 

    swagger: '2.0' 
info:
  title: Cloud Endpoints + Cloud Run
  description: Sample API on Cloud Endpoints with a Cloud Run backend
  version: 1.0.0 
host: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
x-google-endpoints:
- name: API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog
  target: "INGRESS-IP"
schemes:
  - https
produces:
  - application/json
x-google-backend:
  address: http://hello.default.svc.cluster.local
  disable_auth: true
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

    La sangría es importante para el formato yaml. Por ejemplo, el campo host debe estar en el mismo nivel que info.

  3. En el campo host, especifica el nombre de dominio de la API de Endpoints que se usa para acceder a tu servicio de entrega de Knative, de la siguiente manera: 

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    Por ejemplo: 

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

  4. En la extensión x-google-endpoints, se registra una entrada de DNS para tu servicio de Endpoints en el dominio cloud.goog, de la siguiente manera:

    x-google-endpoints: 
  - name: "API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

    IP_ADDRESS es la IP del servicio istio-ingress para tu clúster. Para determinar esta dirección IP, sigue estos pasos:

    1. Ve a la página de Google Kubernetes Engine en la consola de Google Cloud.

      Ir a Google Kubernetes Engine

    2. Haz clic en Ingress y servicios en el panel de navegación izquierdo para ver una lista de servicios.

    3. Si la versión del clúster es 1.15.3-gke.19, 1.14.3-gke.121.13.10-gke.8 o posteriores, desplázate hacia abajo hasta el servicio istio-ingress. Para ver las demás versiones del clúster, desplázate hacia abajo hasta el servicio istio-ingressgateway.

    4. Copia la dirección IP externa que se muestra junto al balanceador de cargas, sin la configuración de puerto, si la hay. Por ejemplo, si la IP es XX.XXX.XX.XXX:15020, omite el :15020. Ignora las otras direcciones IP enumeradas.

  5. En el campo address de la sección x-google-backend, especifica el nombre de DNS interno del servicio “hello” del backend de Knative serving y, luego, inhabilita la autenticación a este servicio. Esto es necesario porque la llamada de ESPv2 al servicio de entrega de Knative se realiza como una llamada interna desde el clúster y, por lo tanto, no es necesaria la autenticación.

  6. Ten en cuenta el valor de la propiedad title del archivo openapi-run-anthos.yaml: 

    title: Cloud Endpoints + Cloud Run

  7. El valor de la propiedad title se convierte en el nombre del servicio de Endpoints después de que implementas la configuración.

  8. Guarda tu documento de OpenAPI.

Para obtener información sobre los campos del documento de OpenAPI que requiere Endpoints, consulta Configura Endpoints.

Implemente la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa la Administración de servicios para crear un servicio administrado.

Para implementar la configuración de Endpoints:

  1. Asegúrate de estar en el directorio que contiene el documento de OpenAPI.

  2. Sube la configuración y crea un servicio administrado. 

    gcloud endpoints services deploy openapi-run-anthos.yaml \ 
  --project ESP_PROJECT_ID

    Con este proceso, se crea un servicio de Endpoints nuevo con el nombre que especificaste en el campo host del archivo openapi-run-anthos.yaml. El servicio de Endpoints se configura según tu documento de OpenAPI.

    Mientras se crea y configura el servicio de Endpoints, 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 [API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog]

    CONFIG_ID es el ID de configuración único del servicio de Endpoints que creó la implementación. Por ejemplo: 

    Service Configuration [2019-02-01r0] uploaded for service [hello-api.endpoints.ESP_PROJECT_ID.cloud.goog]

    El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si vuelves a implementar openapi-run-anthos.yaml el mismo día, se incrementa el número de revisión en el ID de configuración del servicio. Puedes ver la configuración del servicio y el historial de implementaciones en la página Endpoints > Servicios de la consola de Google Cloud.

    Si recibes un mensaje de error, consulta Cómo solucionar problemas en la implementación de la configuración de Endpoints.

Verifica los servicios requeridos

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:
Name Título
servicemanagement.googleapis.com API de Administración de servicios
servicecontrol.googleapis.com Service Control API

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

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

Compila una nueva imagen de entrega de Knative de ESPv2

Compila la configuración de servicio de Endpoints en una nueva imagen de Docker del ESPv2. Después de crear esta imagen, puedes implementarla en tu clúster.

Si quieres compilar la configuración de servicio en una imagen de Docker de ESPv2 nueva, sigue estos pasos:

  1. Descarga esta secuencia de comandos en tu máquina local donde está instalada gcloud CLI y ejecútala de la siguiente manera:

    chmod +x gcloud_build_image
./gcloud_build_image -s API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog \ 
-c CONFIG_ID -p ESP_PROJECT_ID

    La secuencia de comandos usa el comando de gcloud para descargar la configuración del servicio, compilarla en una imagen ESPv2 nueva y subir la imagen nueva al registro de contenedores del proyecto. La secuencia de comandos usa automáticamente la última versión del ESPv2, indicada por ESP_VERSION en el nombre de la imagen de salida. La imagen resultante se sube a la siguiente ubicación:

    gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID

Implementa la imagen de Knative serving de ESPv2

Implementa la imagen de servicio de entrega de Knative ESPv2 en tu clúster:

  1. Implementa el servicio de entrega de Knative de ESPv2 con la imagen nueva: 

    gcloud run deploy ESP_V2_SERVICE_NAME \ 
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
  --platform gke \ 
  --project=ESP_PROJECT_ID

    En ESP_PROJECT_ID, especifica el nombre que deseas usar para el servicio ESPv2. En este ejemplo, configura ESP_V2_SERVICE_NAME como espv2.

  2. Si quieres configurar Endpoints para usar opciones adicionales de inicio de ESPv2, como habilitar CORS, puedes pasar los argumentos en la variable de entorno ESPv2_ARGS:

    gcloud run deploy ESP_V2_SERVICE_NAME \
  --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog-CONFIG_ID" \ 
  --set-env-vars=ESPv2_ARGS=--cors_preset=basic \ 
  --platform gke \ 
  --project ESP_PROJECT_ID

    Para obtener más información y ejemplos sobre cómo configurar la variable de entorno ESPv2_ARGS, incluida la lista de opciones disponibles y la información sobre cómo especificar varias opciones, consulta Marcas del proxy de servicio extensible V2.

El servicio del ESPv2 se implementa como un servicio externo, lo que significa que puedes acceder a él mediante un comando cURL en la siguiente forma:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS

en el que IP_ADDRESS es la dirección IP del servicio istio-ingress de tu clúster.

Para ver este comando de cURL, haz clic en el ícono de IMAGE a la derecha de la URL de ESPv2 en la pantalla Revisiones del servicio de Knative Serving de ESPv2 implementado.

Ahora puedes realizar llamadas a la API en tu servicio de Endpoints mediante el servicio del ESPv2. Por ejemplo, para realizar una solicitud a un servicio de Endpoints con una ruta /hello, puedes crear una solicitud con el siguiente formato:

curl -H "Host: espv2.default.example.com" http://IP_ADDRESS/hello

Sin embargo, no es fácil especificar un encabezado host en cada solicitud a tu servicio de Endpoints. En la siguiente sección, configurarás una asignación de dominios para que sea más fácil realizar una llamada a tu servicio de Endpoint a través del ESPv2.

Cómo crear una asignación de dominio al servicio de Knative serving de ESPv2

Para poder omitir el encabezado host cuando realices una solicitud, agrega una asignación de dominio para el servicio del ESPv2:

  1. Ir a Cloud Run

  2. Selecciona Administrar dominios personalizados.

  3. Selecciona Agregar asignación.

  4. En el menú desplegable, seleccione Agregar asignación de dominio de servicio.

  5. En el campo Selecciona un servicio al que asignar en la ventana emergente Agregar asignación, selecciona el servicio del ESPv2.

  6. En el campo Ingresar nombre de dominio, especifica el nombre de dominio que deseas usar para acceder a tu servicio de entrega de Knative a través de Endpoints. Por ejemplo, especifica: 

    API_NAME.endpoints.ESP_PROJECT_ID.cloud.goog

    En el ejemplo anterior, API_NAME es el nombre de tu API de Endpoints. Para este ejemplo, puedes usar “hello-api”: 

    hello-api.endpoints.ESP_PROJECT_ID.cloud.goog

  7. Haga clic en Continuar. Aparecerá un resumen de la asignación.

  8. Selecciona Listo para guardar la asignación.

Envía solicitudes a la API

Usa cURL para enviar una solicitud HTTP a tu API:

curl -X GET "http://hello-api.endpoints.ESP_PROJECT_ID.cloud.goog/hello"

Si no obtuviste una respuesta correcta, consulta Cómo solucionar errores de respuesta.

Configura la API de Endpoints para usar HTTPS

La compatibilidad automática con TLS está inhabilitada de forma predeterminada para la publicación de Knative en Google Cloud. Por lo tanto, en este ejemplo, cuando accedes a la API de Endpoints a través del ESPv2, debes realizar la llamada mediante HTTP.

Puedes configurar el ESPv2 para admitir solicitudes mediante HTTPS. Ten en cuenta que debes configurar la compatibilidad con HTTPS en el ESPv2, el servicio externo, no en “hello”, el servicio de backend interno.

Para obtener la compatibilidad de HTTPS con el ESPv2, debes hacer lo siguiente:

  1. Tener un dominio. Si no tienes un dominio, puedes obtener uno de Cloud Domains o de otro proveedor de dominios.

  2. Crea una asignación de dominio para tu servicio ESPv2 y actualiza tu registro DNS de acuerdo con las instrucciones en la página de asignación de dominios.

    Si obtuviste el dominio de Cloud Domains, usa Cloud DNS o el servidor DNS que prefieras. La opción más fácil es usar un dominio de Cloud Domains.

  3. En la especificación de OpenAPI de Endpoints, haz lo siguiente:

    1. Configura el campo host para que haga referencia a tu dominio en lugar de a *.cloud.goog.

    2. Quita la etiqueta x-google-endpoints y sus dos propiedades secundarias.

Para obtener instrucciones y instructivos completos, consulta Cómo habilitar HTTPS y certificados TLS automáticos.

Realiza un seguimiento de la actividad de la API

  1. Consulta los gráficos de actividad de tu API en la página Endpoints > Service de la consola de Google Cloud.

    Ver los gráficos de actividad de Endpoints

    La solicitud puede tardar unos minutos en reflejarse en los gráficos.

  2. Consulta los registros de solicitud de tu API en la página Explorador de registros. Ver los registros de solicitud de Endpoints

Crea un portal de desarrolladores para la API

Puedes utilizar el Portal de Cloud Endpoints para crear un portal de desarrolladores, un sitio web en el que puedes interactuar con la API de muestra. Para obtener más información, consulta Descripción general del Portal de Cloud Endpoints.

Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página.

Consulta Borrar una API y las instancias de la API para obtener información acerca de cómo detener los servicios que se usan en este instructivo.

¿Qué sigue?