Primeros pasos con API Gateway y Cloud Run

En esta página, se muestra cómo configurar API Gateway para administrar y proteger un servicio de backend de Cloud Run.

Lista de tareas

Usa la siguiente lista de tareas mientras trabajas en el instructivo. Todas las tareas son necesarias a fin de implementar una API Gateway para tu servicio de backend de Cloud Run.

1. Crea o selecciona un proyecto de Google Cloud .
2. Si no has implementado tu propio Cloud Run, implementa un servicio de muestra. Ve el paso 7 en Antes de comenzar.
3. Habilita los servicios de API Gateway necesarios.
4. Crea una descripción de OpenAPI que describa tu API y configura las rutas a tu servicio de backend de Cloud Run. Consulta Crea una configuración de API.
5. Implementa una API Gateway con tu configuración de API. Consulta Implementa una puerta de enlace de API.
6. Realiza un seguimiento de la actividad de tus servicios. Consulta Cómo realizar un seguimiento de la actividad de la API.
7. Evita que se apliquen cargos a tu cuenta de Google Cloud . Consulta Limpieza.

Antes de comenzar

1. En la consola de Google Cloud , ve a la página Panel y selecciona o crea un proyecto de Google Cloud .

   Ir al panel

   Nota: Si no planeas conservar los recursos creados durante este instructivo, crea un proyecto nuevo en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

2. Asegúrate de tener habilitada la facturación para tu proyecto.

   Habilitar la facturación

3. Anota el ID del proyecto que deseas usar para este instructivo. En el resto de esta página, este ID del proyecto se denomina PROJECT_ID.

4. Descarga e instala Google Cloud CLI.

   Descarga la CLI de gcloud

5. Actualiza los componentes de gcloud:

   gcloud components update

6. Configura el proyecto predeterminado. Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud

   gcloud config set project PROJECT_ID

7. Si no implementaste tu propio servicio de Cloud Run, sigue los pasos de la Guía de inicio rápido: Implementa un contenedor de muestra ya compilado para seleccionar o crear un proyecto de Google Cloud y, luego, implementar un backend de muestra. Toma nota de la URL de la app, así como de la región y el ID del proyecto donde se implementan tus apps.

Habilita los servicios obligatorios

API Gateway requiere que habilites los siguientes servicios de Google:

Nombre	Título
apigateway.googleapis.com	API de API Gateway
servicemanagement.googleapis.com	API de Administración de servicios
servicecontrol.googleapis.com	Service Control API

Usa los siguientes comandos para habilitar estos servicios:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Para obtener más información sobre los servicios de gcloud, consulta Servicios de gcloud.

Crea una configuración de API

Antes de que se pueda usar API Gateway para administrar el tráfico al backend de Cloud Run implementado, necesita una configuración de API.

Puedes crear una configuración de API con una descripción de OpenAPI que contenga anotaciones especializadas para definir el comportamiento elegido de API Gateway. Deberás agregar un campo específico de Google que contenga la URL de cada app de Cloud Run para que API Gateway tenga la información que necesita para invocar una app.

Para obtener más detalles sobre las extensiones de OpenAPI compatibles, consulta lo siguiente:

• Extensiones de OpenAPI 2.0 en API Gateway
• Extensiones de OpenAPI 3.x en API Gateway

Para crear tu configuración de API, sigue estos pasos:

1. Crea un archivo de texto denominado openapi-run.yaml. Para mayor comodidad, esta página hace referencia a la descripción de OpenAPI con ese nombre de archivo, pero puedes darle otro nombre si lo prefieres.
2. Copia el contenido del siguiente archivo en tu archivo openapi-run.yaml:

   OpenAPI 2.0

   # openapi-run.yaml
   swagger: '2.0'
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Cloud Run backend
     version: 1.0.0
   schemes:
   - https
   produces:
   - application/json
   x-google-backend:
     address: APP_URL
   paths:
     /assets/{asset}:
       get:
         parameters:
           - in: path
             name: asset
             type: string
             required: true
             description: Name of the asset.
         summary: Assets
         operationId: getAsset
         responses:
           '200':
             description: A successful response
             schema:
               type: string
     /hello:
       get:
         summary: Cloud Run hello world
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   • En el campo title, reemplaza API_ID por el nombre de tu API y optional-string por una breve descripción de tu elección. Si tu API aún no existe, el comando para crear la configuración de API también creará la API con el nombre que especifiques. El valor del campo title se usa cuando se generan claves de API que otorgan acceso a esta API. Consulta los requisitos de ID de API para conocer los lineamientos de nomenclatura de las APIs.
   • En el campo address de la sección x-google-backend, reemplaza APP_URL por la URL real de tu servicio de Cloud Run (la ruta de acceso completa de la API llamada). Por ejemplo: https://hello-abc1def2gh-uc.a.run.app.
     Nota: Si planeas usar etiquetas de revisión para controlar la versión del backend del servicio de Cloud Run, debes especificar el campo jwt_audience en address en la sección x-google-backend. El valor del campo jwt_audience debe ser la URL del servicio de Cloud Run. Por ejemplo:

     ...
       x-google-backend:
           address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
           jwt_audience: https://SERVICE_HOSTNAME
     ...

     Si el campo jwt_audience no está presente, la extensión x-google-backend se establece de forma predeterminada en el valor del campo address para el reclamo de público del JWT. Esto puede generar una reclamación de público de JWT inesperada para Cloud Run si la URL de la etiqueta de revisión se usa para address y no se especifica ningún jwt_audience.

   OpenAPI 3.x

   # openapi-run.yaml
   openapi: 3.0.4
   info:
     title: API_ID optional-string
     description: Sample API on API Gateway with a Cloud Run backend
     version: 1.0.0
   # Define reusable components in x-google-api-management
   x-google-api-management:
     backends:
       cloudrun_backend:
         address: APP_URL
         deadline: 30.0
         pathTranslation: APPEND_PATH_TO_ADDRESS
         protocol: "http/1.1"
   # Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
   x-google-backend: cloudrun_backend
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           "200":
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   • En el campo title, reemplaza API_ID por el nombre de tu API y optional-string por una breve descripción de tu elección. Si tu API aún no existe, el comando para crear la configuración de API también creará la API con el nombre que especifiques. El valor del campo title se usa cuando se generan claves de API que otorgan acceso a esta API. Consulta los requisitos de ID de API para conocer los lineamientos de nomenclatura de las APIs.
   • En el campo address, reemplaza APP_URL por la URL real de tu servicio de Cloud Run (la ruta de acceso completa de la API llamada). Por ejemplo: https://hello-687541448612.us-central1.run.app.
   Nota: Si planeas usar etiquetas de revisión para controlar la versión del backend del servicio de Cloud Run, debes especificar el campo jwtAudience en address en la sección x-google-api-management. El valor del campo jwtAudience debe ser la URL del servicio de Cloud Run. Por ejemplo:
   ...
     x-google-api-management:
       backends:
         cloudrun_backend:
           address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
           jwtAudience: https://SERVICE_HOSTNAME
   ...
   Si el campo jwtAudience no está presente, la extensión x-google-backend se establece de forma predeterminada en el valor del campo address para el reclamo de público del JWT. Esto puede generar una reclamación de público de JWT inesperada para Cloud Run si se usa la URL de la etiqueta de revisión para address y no se especifica ningún jwtAudience.
3. Ingresa el siguiente comando, donde:
   • CONFIG_ID especifica el nombre de tu configuración de API.
   • API_ID especifica el nombre de tu API. Si la API aún no existe, este comando la crea.
   • PROJECT_ID especifica el nombre de tu proyecto Google Cloud .
   • SERVICE_ACCOUNT_EMAIL especifica la cuenta de servicio que se usa para firmar tokens para backends con autenticación configurada. Para obtener más información, consulta Crea una cuenta de servicio.
     Nota: La cuenta de servicio que se usa para crear una configuración de API para un backend de Cloud Run debe tener asignado el rol de run.invoker.

   gcloud api-gateway api-configs create CONFIG_ID \
     --api=API_ID --openapi-spec=openapi2-run.yaml \
     --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

   Esta operación puede tardar varios minutos en completarse, ya que la configuración de la API se propaga a los sistemas posteriores. La creación de una configuración de API compleja puede tardar hasta diez minutos en completarse correctamente.

4. Después de crear la configuración de la API, puedes ver sus detalles. Para ello, ejecuta este comando:

   gcloud api-gateway api-configs describe CONFIG_ID \
     --api=API_ID

Implementa una puerta de enlace de API

Ahora puedes implementar tu API en API Gateway. La implementación de una API en API Gateway también define una URL externa que los clientes de API pueden usar para acceder a tu API.

Ejecuta el comando siguiente para implementar la configuración de la API que acabas de crear en API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID

Donde:

• GATEWAY_ID especifica el nombre de la puerta de enlace.
• API_ID especifica el nombre de la API de API Gateway asociada a esta puerta de enlace.
• CONFIG_ID especifica el nombre de la configuración de API implementada en la puerta de enlace.

• GCP_REGION es la Google Cloud región para la puerta de enlace implementada.

  Nota: Los valores permitidos son los siguientes:

  • asia-northeast1
  • australia-southeast1
  • europe-west1
  • europe-west2
  • us-east1
  • us-east4
  • us-central1
  • us-west2
  • us-west3
  • us-west4

• PROJECT_ID especifica el nombre de tu proyecto Google Cloud .

Cuando el proceso finalice con éxito, puedes usar el siguiente comando para ver los detalles de la puerta de enlace:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Ten en cuenta el valor de la propiedad defaultHostname en el resultado de este comando. Esta es la parte del nombre de host de la URL de la puerta de enlace que usarás para probar tu implementación en el siguiente paso.

Prueba tu implementación de la API

Ahora puedes enviar solicitudes a tu API mediante la URL generada después de la implementación de tu puerta de enlace.

Ingresa la siguiente URL en el navegador web, donde:

• DEFAULT_HOSTNAME especifica la parte del nombre de host de la URL de la puerta de enlace implementada.
• hello es la ruta de acceso que se especifica en la configuración de la API.

https://DEFAULT_HOSTNAME/hello

Por ejemplo:

https://my-gateway-687541448612.us-central1.run.app/hello

Deberías ver tu contenedor de Cloud Run ejecutando tu app en el navegador.

¡Listo! Tu puerta de enlace administra el acceso a tu servicio de backend de Cloud Run.

Realiza un seguimiento de la actividad de la API

1. Consulta los gráficos de actividad de tu API en la página API Gateway en laGoogle Cloud consola. Haz clic en tu API para ver los gráficos de actividad en la página Descripción general. Las solicitudes pueden tardar unos minutos en reflejarse en los gráficos.

2. Consulta los registros de solicitud de tu API en la página Visor de registros. Se puede encontrar un vínculo a la página Explorador de registros en la página API Gateway en la consola deGoogle Cloud .

   Una vez en la página API Gateway, haz lo siguiente:

   1. Selecciona la API que deseas ver.
   2. Haz clic en la pestaña Detalles.
   3. Haz clic en el vínculo en Registros.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta guía de inicio rápido, puedes hacer lo siguiente:

• Borra tus puertas de enlace
• Borra tu API

Como alternativa, también puedes borrar el proyecto Google Cloud que se usó para este instructivo.