Administra el acceso a las APIs de Google Cloud para los agentes

Los desarrolladores de aplicaciones pueden solicitar una identidad de agente para los agentes de IA que se ejecutan en Google Kubernetes Engine (GKE). La identidad del agente es una identidad por Pod que se puede vincular de forma criptográfica a cada Pod de la carga de trabajo. Luego, los agentes pueden autenticarse en las Google Cloud APIs con la identidad del agente. Puedes controlar a qué recursos puede acceder un agente si lo incluyes como principal en las políticas de Identity and Access Management (IAM). En este documento, se describe cómo administrar el acceso a las Google Cloud APIs y los servicios para los agentes que usan una identidad de agente.

Este documento está dirigido a los administradores de seguridad y de plataformas que administran la autorización de los agentes que los desarrolladores implementan en los clústeres de GKE. Debes tener conocimientos generales sobre los siguientes temas:

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

  • Habilita la API de Google Kubernetes Engine.
    • Habilitar la API de Google Kubernetes Engine
  • Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste la gcloud CLI, ejecuta el comando gcloud components update para obtener la versión más reciente. Es posible que las versiones anteriores de gcloud CLI no admitan la ejecución de los comandos que se indican en este documento.
  • Verifica que tengas un clúster de Autopilot existente o un clúster de Standard que tenga habilitada la Workload Identity Federation for GKE y que ejecute la versión 1.37.0-gke.3503000 o posterior de GKE.

Roles obligatorios

Para obtener los permisos que necesitas para administrar el acceso a las APIs de Google Cloud agentes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto Google Cloud :

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.

Cómo encontrar el identificador principal de un agente

En esta sección, se describe cómo construir el identificador principal de un agente. Puedes usar este identificador en las políticas de IAM para controlar a qué recursos puede acceder el agente.

Cualquier carga de trabajo del agente que solicite una identidad del agente obtiene una cadena de identidad de SPIFFE que es única para esa carga de trabajo. Cuando la aplicación llama a las APIs de Google Cloud , las llamadas se autentican con un token de acceso de identidad del agente que valida que la carga de trabajo tenga una identidad del agente. Este token de acceso incluye un identificador de principal de IAM para la carga de trabajo del agente, que puedes incluir en las políticas de IAM para controlar a qué recursos tiene acceso el agente.

Cuando diseñes tus políticas de IAM, puedes construir los identificadores principales para los agentes con la siguiente información:

  • Es la jerarquía de recursos del proyecto.
  • Es el nombre del clúster.
  • El espacio de nombres de Kubernetes y la ServiceAccount de Kubernetes en ese espacio de nombres.

Cuando los desarrolladores implementan agentes que obtienen una identidad de agente que coincide con el identificador principal, el agente hereda el acceso que especificaste en tu política.

Para encontrar el identificador principal que se usará en tus políticas, sigue estos pasos:

  1. Identifica el dominio de confianza de la identidad. El dominio de confianza depende de si el proyecto pertenece a una organización, de la siguiente manera:

    • Proyectos que pertenecen a una organización:

      agents.global.org-ORGANIZATION_ID.system.id.goog

      Reemplaza ORGANIZATION_ID por el ID de organización.

    • Proyectos que no pertenecen a una organización:

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      Reemplaza PROJECT_NUMBER por el número del proyecto del clúster.

  2. Identifica la siguiente información sobre el clúster:

    • El nombre del clúster de GKE.
    • Ubicación del plano de control del clúster, como us-central1.
    • Es el espacio de nombres de Kubernetes en el que los desarrolladores implementan las cargas de trabajo.
    • Es el nombre de la cuenta de servicio de Kubernetes que los desarrolladores deben usar para la carga de trabajo del agente.

    Si no conoces esta información, consulta a tu equipo de la plataforma. El equipo de la plataforma debe configurar los espacios de nombres, las ServiceAccounts y las políticas de RBAC en el clúster para que los agentes que tienen diferentes requisitos de acceso obtengan diferentes identidades.

  3. Construye el identificador principal:

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

    Reemplaza lo siguiente:

    • TRUST_DOMAIN: Es el dominio de confianza para la identidad del agente.
    • PROJECT_NUMBER: Es el número del proyecto del clúster.
    • CONTROL_PLANE_LOCATION: Es la región o zona del plano de control del clúster.
    • CLUSTER_NAME: el nombre del clúster
    • KUBERNETES_NAMESPACE: Es el nombre del espacio de nombres de Kubernetes.
    • KUBERNETES_SERVICEACCOUNT: Es el nombre de la cuenta de servicio de Kubernetes.

Usa políticas para controlar el acceso

En esta sección, se describe cómo usar el identificador principal de un agente para controlar a qué Google Cloud APIs y servicios puede acceder el agente. Para controlar el acceso, incluye el identificador principal en cualquiera de las siguientes políticas de IAM:

Después de crear o actualizar una política, cualquier agente que solicite una identidad de agente y se ejecute en ese espacio de nombres y use esa ServiceAccount tendrá el acceso que especifiques en tus políticas.

Autoriza a los agentes para que accedan al administrador de autenticación

El administrador de autenticación de identidad del agente es un agente de autenticación y una bóveda de credenciales que los agentes pueden usar para obtener credenciales y acceder a herramientas y servicios externos, ya sea como la propia identidad del agente o en nombre de un usuario final. El administrador de autenticación puede tener uno o más proveedores de autenticación, cada uno de los cuales controla un flujo específico de autenticación y adquisición de credenciales para un servicio específico. Para otorgarles a los agentes de GKE acceso a proveedores de autenticación específicos, sigue estos pasos:

  1. Busca el identificador de principal del agente.
  2. Obtén el nombre del proveedor de autenticación al que necesita acceder el agente.

  3. Otorga el rol de Usuario de identidad del agente (roles/agentidentity.user) en el proveedor de autenticación a la entidad principal del agente:

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

    Reemplaza lo siguiente:

    • AUTH_PROVIDER_NAME: Es el nombre del proveedor de autenticación.
    • AUTH_PROVIDER_LOCATION: Es la región del proveedor de autenticación.
    • PRINCIPAL_IDENTIFIER: Es el identificador principal del agente.

    Como alternativa, para los agentes registrados en Agent Registry, puedes crear una vinculación del proveedor de autenticación para administrar el acceso a los proveedores de autenticación.

¿Qué sigue?