Configura enlaces exprés

Los enlaces exprés en Ambient Networking te permiten conectar un servicio de Cloud Run de origen a un servicio de Cloud Run de destino en el mismo proyecto y región sin escribir código de autenticación en tu aplicación ni configurar una malla de servicios.

Cuando un servicio de Cloud Run llama a otro servicio de Cloud Run protegido por Identity and Access Management (IAM), la solicitud debe incluir un token de ID de OpenID Connect (OIDC) para que el destino pueda verificar la identidad y los permisos del emisor. Sin un enlace exprés, debes escribir código de autenticación de servicio a servicio en tu aplicación para recuperar y adjuntar tokens del servidor de metadatos, o configurar recursos de Cloud Service Mesh, como una red de nube privada virtual (VPC), servicios de backend y reglas de enrutamiento. Un enlace exprés descarga este trabajo de autenticación y enrutamiento en el contenedor sidecar de Ambient completamente administrado, lo que mantiene el código de la aplicación portátil y enfocado en la lógica empresarial.

Casos de uso

Puedes usar enlaces exprés en las siguientes situaciones:

  • Descarga la autenticación de servicio a servicio del código de la aplicación: conecta un servicio de Cloud Run que realiza llamadas a un servicio de Cloud Run de destino protegido por IAM a través de HTTP simple. El sidecar de Ambient recupera e inserta automáticamente el token de ID de OIDC del servicio de origen y encripta la solicitud a través de HTTPS.
  • Abstrae las URLs de destino con nombres de host personalizados: Configura un nombre de host personalizado en el enlace exprés con la marca --matches-hostname para que tu aplicación de origen envíe solicitudes a una dirección lógica, como http://my-backend, en lugar de codificar de forma fija la URL determinística del destino. Si el servicio de destino cambia, puedes volver a crear el enlace exprés para que apunte al nuevo destino sin modificar ni volver a implementar el código de la aplicación de origen.
  • Simplifica las llamadas de servicio de punto a punto sin una malla de servicios: Obtén inserción automática de credenciales entre los servicios de Cloud Run sin aprovisionar una red de VPC, grupos de extremos de red, servicios de backend o registros de Cloud DNS que requiere Cloud Service Mesh.

En la siguiente tabla, se comparan los pasos para configurar la comunicación autenticada entre servicios con y sin un enlace exprés:

Paso Sin un enlace exprés Con un enlace exprés
1. Implementa el servicio de destino Implementa el servicio de Cloud Run de destino con la autenticación de IAM requerida (--no-allow-unauthenticated). Igual.
2. Otorga permiso de invocador Otorga el rol de Invocador de Cloud Run (roles/run.invoker) en el servicio de destino a la cuenta de servicio del servicio de origen. Igual.
3. Configura la solicitud saliente Escribe código en tu aplicación de origen para recuperar un token de ID de OIDC para la URL de destino y adjuntarlo al encabezado Authorization: Bearer a través de HTTPS. Envía una solicitud http:// simple a la URL de destino o al nombre de host personalizado sin código de autenticación en tu aplicación de origen.
4. Implementa el servicio de origen Implementa el servicio de Cloud Run de origen. Implementa el servicio de Cloud Run de origen con Ambient Networking habilitado y, luego, crea un enlace exprés entre los servicios de origen y destino implementados.

Arquitectura

Cuando habilitas Ambient Networking en un servicio de Cloud Run de origen y creas un enlace exprés, Cloud Run configura el contenedor sidecar de Envoy completamente administrado que se ejecuta junto con el contenedor de tu aplicación en cada instancia de contenedor.

Cuando tu aplicación envía una solicitud HTTP simple a la URL determinística del servicio de destino o a un nombre de host personalizado que configuras en el enlace exprés, el contenedor sidecar de Ambient realiza automáticamente lo siguiente:

  1. Intercepta las solicitudes HTTP salientes destinadas al servicio de destino.
  2. Recupera un token de ID de OIDC para la cuenta de servicio del servicio de origen y lo inserta en el encabezado Authorization.
  3. Encripta y reenvía la solicitud a través de HTTPS (TLS unidireccional) al servicio de Cloud Run de destino, que verifica los permisos de IAM del emisor.
Un contenedor de aplicación dentro de un servicio de Cloud Run de origen que envía una solicitud HTTP simple al contenedor sidecar de Ambient, que intercepta la solicitud, inserta un token de ID de OIDC y reenvía el token de ID y la carga útil a través de HTTPS con un enlace exprés a un servicio de Cloud Run de destino.
Figure 1. El contenedor sidecar de Ambient intercepta las solicitudes salientes desde tu servicio de origen, inserta un token de ID de OIDC y reenvía la solicitud a través de HTTPS (TLS unidireccional) al servicio de destino.

Conectividad de red y plano de datos

Un enlace exprés configura la intercepción de solicitudes salientes y la inserción de credenciales en el sidecar de Ambient, pero no reemplaza la ruta de red subyacente entre tus servicios. Aún debes asegurarte de que tu servicio de origen pueda alcanzar la ruta de entrada del servicio de destino:

Antes de comenzar

  1. Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Habilita las APIs de Cloud Run, Network Services y Traffic Director, si aún no están habilitadas.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    Habilitar las API

  7. Asegúrate de tener un servicio de Cloud Run de origen existente y un servicio de Cloud Run de destino existente en el mismo proyecto y región.
  8. Asegúrate de que las redes de ambient estén habilitadas con el permiso global en tu servicio de Cloud Run de origen. Por ejemplo, ejecuta gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION, pero recuerda primero aumentar los límites de CPU y memoria de tu servicio.

  9. Lee la página de precios de Cloud Run para conocer el uso del sidecar de Ambient Networking. La facturación de las funciones de ambiente no se aplica de manera forzosa durante la versión preliminar.

Roles obligatorios

Para obtener los permisos que necesitas para configurar enlaces exprés, pídele a tu administrador que te otorgue los siguientes roles de IAM:

  • Configura el enlace exprés: Desarrollador de Cloud Run (roles/run.developer) y Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en el proyecto
  • Administra los recursos de enlace exprés: Administrador de servicios de red (roles/networkservices.admin) en el proyecto

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

La identidad del servicio del servicio de Cloud Run de origen también debe tener los siguientes roles en el proyecto:

  • Cliente de Traffic Director (roles/trafficdirector.client)
  • Agente de Cloud Trace (roles/cloudtrace.agent)

Para otorgar estos roles a la identidad de servicio, usa gcloud:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • RUN_CLIENT_SA: Es el nombre de la cuenta de servicio adjunta a tu servicio de Cloud Run de origen.

Si la identidad de servicio de Cloud Run no tiene estos roles, el servicio de Cloud Run se implementa de todos modos, pero las funciones que dependen de Ambient Networking no funcionan. Este comportamiento difiere de Cloud Service Mesh, en el que el servicio de Cloud Run no se implementa cuando faltan los roles requeridos.

Limitaciones

Se aplican las siguientes limitaciones a los vínculos exprés:

  • Solo se admiten los servicios de Cloud Run como recursos de origen y destino. No se admiten los trabajos, los grupos de trabajadores ni las instancias de Cloud Run.
  • No se admiten las configuraciones entre proyectos y entre regiones. El servicio de Cloud Run de origen y el servicio de Cloud Run de destino deben estar en el mismo proyecto y región.
  • Los enlaces exprés requieren Ambient Networking con el alcance global en el servicio de origen. Si el servicio de origen usa el permiso regional, la creación del enlace exprés se realiza correctamente, pero el tráfico no se enruta.
  • Debes crear los servicios de Cloud Run de origen y destino antes de crear el enlace exprés. No se admite la creación desordenada. Si borras un servicio de destino, el enlace exprés puede seguir mostrando y aplicando la configuración obsoleta hasta que borres o vuelvas a crear el enlace exprés.
  • No puedes actualizar el servicio de origen, el servicio de destino ni el nombre de host personalizado de un enlace exprés existente. El comando gcloud beta network-services express-links update solo actualiza la descripción del enlace exprés. Para cambiar la configuración de enrutamiento, borra y vuelve a crear el enlace exprés.
  • Los servicios de Cloud Run de destino deben tener habilitada la URL run.app predeterminada, incluso si usas URLs personalizadas, dominios personalizados o configuras un nombre de host personalizado con la marca --matches-hostname.
  • Las solicitudes enviadas a la URL no determinística del destino no se interceptan y fallan con un error 403 Forbidden. Si el servicio de destino no tiene una URL determinística porque el nombre del servicio y el número de proyecto combinados superan los 63 caracteres, debes especificar --matches-hostname o la creación del enlace exprés fallará con un error Cloud Run Service name is too long.
  • Cuando ves el estado completo de un enlace exprés, solo se devuelve la información del servicio de destino. Es posible que falten detalles sobre las revisiones de Cloud Run de origen y la autenticación negociada, o que se muestren datos obsoletos. Esto no afecta la forma en que el enlace exprés enruta o autentica el tráfico.
  • No se admiten los servicios de Cloud Run de origen configurados con la identidad del agente ni los tokens vinculados a mTLS.
  • No se admiten los servicios de Cloud Run de origen configurados para enrutar el tráfico saliente a través de Agent Gateway en Cloud Run y el proxy web seguro. Los enlaces exprés requieren el permiso de alcance global de Ambient Networking, mientras que Agent Gateway requiere el permiso de alcance regional.
  • Si una solicitud saliente del servicio de origen ya incluye un encabezado Authorization, el enlace exprés reenvía la solicitud con ese encabezado sin cambios y no inserta un token. No se admite la inserción automática de tokens en el encabezado X-Serverless-Authorization.
  • No se admite el tráfico generado desde los contenedores de zona de pruebas de Cloud Run.
  • No puedes usar enlaces exprés para reenviar tráfico a servicios de Cloud Run de destino que estén protegidos por Identity-Aware Proxy.
  • Cada enlace exprés admite un servicio de Cloud Run de destino, y puedes crear hasta 5,000 enlaces exprés por proyecto.

Para conectar tus servicios de Cloud Run, crea un enlace exprés especificando el servicio de origen y el de destino y, luego, otorga el rol de Invocador de Cloud Run en el servicio de destino.

Conéctate a otro servicio de Cloud Run

Para conectar un servicio de Cloud Run de origen a un servicio de Cloud Run de destino, crea un enlace exprés con gcloud o YAML.

gcloud

Usa el comando gcloud beta network-services express-links create para crear un enlace exprés:

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

Reemplaza lo siguiente:

  • EXPRESS_LINK_NAME: Es un nombre para tu enlace exprés.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: la región en la que se implementan tus servicios de Cloud Run.
  • SOURCE_SERVICE: Es el nombre del servicio de Cloud Run de origen.
  • DESTINATION_SERVICE: Es el nombre del servicio de Cloud Run de destino.

Después de que se complete el comando, la configuración de enrutamiento puede tardar hasta 2 minutos en propagarse a las instancias de servicio de origen en ejecución.

De forma predeterminada, el enlace exprés solo intercepta las solicitudes enviadas a la URL determinística del servicio de destino, no a su URL no determinística. Para usar un nombre de host personalizado, pasa el nombre de host sin un esquema en la marca --matches-hostname="HOSTNAME", como --matches-hostname="DESTINATION_SERVICE", y envía solicitudes desde tu aplicación de origen a http://HOSTNAME. Si especificas --matches-hostname, se reemplaza la URL determinística en lugar de agregarla.

YAML

  1. Crea un archivo de configuración, por ejemplo, express-link.yaml:

    name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
source:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
destination:
  services:
    - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud .
    • REGION: Es la región en la que se implementan tus servicios.
    • EXPRESS_LINK_NAME: Es un nombre para tu enlace exprés.
    • SOURCE_SERVICE: Es el nombre del servicio de Cloud Run de origen.
    • DESTINATION_SERVICE: Es el nombre del servicio de Cloud Run de destino.

  2. Importa el archivo YAML con el comando gcloud beta network-services express-links import:

    gcloud beta network-services express-links import EXPRESS_LINK_NAME \
    --location=global \
    --source=YAML_FILENAME.yaml

    Reemplaza lo siguiente:

    • EXPRESS_LINK_NAME: Es un nombre para tu enlace exprés.
    • YAML_FILENAME: Es el nombre de tu archivo YAML.

Otorga permisos de invocador en el servicio de destino

Para permitir que el servicio de origen invoque un servicio de destino protegido por IAM, otorga el rol de Invocador de Cloud Run (roles/run.invoker) a la cuenta de servicio del servicio de origen en el servicio de Cloud Run de destino. Esto es necesario para que la autenticación funcione en el plano de datos.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

Reemplaza lo siguiente:

  • DESTINATION_SERVICE: Es el nombre del servicio de Cloud Run de destino.
  • SOURCE_SA: Es el nombre de la cuenta de servicio adjunta a tu servicio de Cloud Run de origen.
  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • REGION: Es la región en la que se implementa tu servicio de destino.

Verifica el estado del enlace exprés

Para ver la configuración básica de tu enlace exprés, usa el comando gcloud beta network-services express-links describe:

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

Para ver el estado completo del enlace exprés, incluidos connectionStatus (tipo de ruta activa, nombres de host que coinciden y URI de revisión de origen) y cloudRunSourceInfo (métodos de autenticación configurados y red de VPC), incluye ?view=EXPRESS_LINK_VIEW_FULL# en el nombre del recurso:

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

Reemplaza EXPRESS_LINK_NAME por el nombre de tu enlace exprés. Conserva las comillas simples y el carácter # final cuando consultes la vista completa.

Para quitar un enlace exprés y detener la inserción automática de credenciales y la intercepción de tráfico desde el servicio de origen, usa el comando gcloud beta network-services express-links delete:

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

Reemplaza EXPRESS_LINK_NAME por el nombre de tu enlace exprés.

Para dirigir un enlace exprés existente a un servicio de destino diferente o cambiar el parámetro de configuración --matches-hostname, borra el enlace exprés con el comando anterior y, luego, crea un enlace exprés nuevo con la configuración actualizada.

¿Qué sigue?