Gerenciar o acesso às APIs do Google Cloud para agentes

Os desenvolvedores de aplicativos podem solicitar uma identidade de agente para agentes de IA executados no Google Kubernetes Engine (GKE). A identidade do agente é uma identidade por pod que pode ser vinculada criptograficamente a cada pod na carga de trabalho. Em seguida, os agentes podem fazer a autenticação nas APIs do Google Cloud usando a identidade do agente. É possível controlar quais recursos um agente pode acessar incluindo o agente como um principal nas políticas do Identity and Access Management (IAM). Este documento descreve como gerenciar o acesso a APIs e serviços do Google Cloud para agentes que usam uma identidade de agente.

Este documento é destinado a administradores de segurança e de plataforma que gerenciam a autorização de agentes implantados por desenvolvedores em clusters do GKE. Você precisa conhecer bem os seguintes tópicos:

Antes de começar

Antes de começar, verifique se você realizou as tarefas a seguir:

  • Ative a API Google Kubernetes Engine.
    • Ativar a API Google Kubernetes Engine
  • Se você quiser usar a Google Cloud CLI para essa tarefa, instale e inicialize a CLI gcloud. Se você instalou a CLI gcloud anteriormente, instale a versão mais recente executando o comando gcloud components update. Talvez as versões anteriores da CLI gcloud não sejam compatíveis com a execução dos comandos neste documento.

Funções exigidas

Para receber as permissões necessárias para gerenciar o acesso às APIs do Google Cloud para agentes, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto Google Cloud :

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Encontrar o identificador principal de um agente

Esta seção descreve como construir o identificador principal de um agente. É possível usar esse identificador em políticas do IAM para controlar quais recursos o agente pode acessar.

Qualquer carga de trabalho do agente que solicitar uma identidade de agente receberá uma string de identidade SPIFFE exclusiva para essa carga de trabalho. Quando o aplicativo chama as APIs do Google Cloud , as chamadas são autenticadas usando um token de acesso de identidade do agente que valida se a carga de trabalho tem uma identidade de agente. Esse token de acesso inclui um identificador principal do IAM para a carga de trabalho do agente, que pode ser incluído em políticas do IAM para controlar a quais recursos o agente tem acesso.

Ao criar suas políticas do IAM, você pode construir os identificadores principais dos agentes usando as seguintes informações:

  • A hierarquia de recursos do projeto.
  • O nome do cluster.
  • O namespace do Kubernetes e a conta de serviço do Kubernetes nesse namespace.

Quando os desenvolvedores implantam agentes que recebem uma identidade correspondente ao identificador principal, o agente herda o acesso especificado na política.

Para encontrar o identificador principal a ser usado nas suas políticas, siga estas etapas:

  1. Identifique o domínio de confiança da identidade. O domínio de confiança depende de se o projeto está em uma organização, da seguinte forma:

    • Projetos em uma organização:

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

      Substitua ORGANIZATION_ID pelo ID da organização.

    • Projetos que não estão em uma organização:

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

      Substitua PROJECT_NUMBER pelo número do projeto do cluster.

  2. Identifique as seguintes informações sobre o cluster:

    • O nome do cluster do GKE.
    • O local do plano de controle do cluster, como us-central1.
    • O namespace do Kubernetes em que os desenvolvedores implantam as cargas de trabalho.
    • O nome da conta de serviço do Kubernetes que os desenvolvedores precisam usar para a carga de trabalho do agente.

    Se você não souber, pergunte à equipe da plataforma. A equipe de plataforma precisa configurar os namespaces, as ServiceAccounts e as políticas de RBAC no cluster para que os agentes com diferentes requisitos de acesso recebam identidades diferentes.

  3. Construa o identificador principal:

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

    Substitua:

    • TRUST_DOMAIN: o domínio de confiança da identidade do agente.
    • PROJECT_NUMBER: o número do projeto do cluster.
    • CONTROL_PLANE_LOCATION: a região ou zona do plano de controle do cluster.
    • CLUSTER_NAME: o nome do cluster.
    • KUBERNETES_NAMESPACE: o nome do namespace do Kubernetes.
    • KUBERNETES_SERVICEACCOUNT: o nome da conta de serviço do Kubernetes.

Usar políticas para controlar o acesso

Esta seção descreve como usar o identificador principal de um agente para controlar quais APIs e serviços do Google Cloud ele pode acessar. Para controlar o acesso, inclua o identificador principal em qualquer uma das seguintes políticas do IAM:

Depois de criar ou atualizar uma política, qualquer agente que solicitar uma identidade de agente e for executado nesse namespace e usar essa ServiceAccount terá o acesso que você especificar nas políticas.

Autorizar agentes a acessar o gerenciador de autenticação

O gerenciador de autenticação de identidade do agente é um broker de autenticação e um cofre de credenciais que os agentes podem usar para receber credenciais e acessar ferramentas e serviços externos, como a própria identidade do agente ou em nome de um usuário final. O gerenciador de autenticação pode ter um ou mais provedores de autenticação, cada um deles processando um fluxo específico de autenticação e aquisição de credenciais para um serviço específico. Para dar aos agentes do GKE acesso a provedores de autenticação específicos, siga estas etapas:

  1. Encontre o identificador principal do agente.
  2. Receba o nome do provedor de autenticação que o agente precisa acessar.

  3. Conceda o papel de usuário da identidade do agente (roles/agentidentity.user) no provedor de autenticação ao principal do agente:

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

    Substitua:

    • AUTH_PROVIDER_NAME: o nome do provedor de autenticação.
    • AUTH_PROVIDER_LOCATION: a região do provedor de autenticação.
    • PRINCIPAL_IDENTIFIER: o identificador principal do agente.

    Outra opção é, para agentes registrados no Agent Registry, gerenciar o acesso aos provedores de autenticação criando uma vinculação de provedor de autenticação.

A seguir