Configurar o Gateway de Agente entre nuvens

Este guia explica como implantar o Gateway de Agente para ambientes de várias nuvens em clusters padrão do Kubernetes para estender a governança da Gemini Enterprise Agent Platform ao seu ambiente. Para uma visão geral da arquitetura de três planos, consulte a Visão geral do Gateway de Agente entre nuvens.

Antes de começar

Antes de começar, verifique se você tem:

  • Um cluster do Kubernetes em conformidade com a Cloud Native Computing Foundation (CNCF).
  • Uma malha de serviço ou pilha de rede configurada no cluster.
  • Conectividade de rede de saída do cluster com as APIs do Google Cloud por HTTPS (porta TCP 443).
  • A CLI do Google Cloud versão 591.0.0 ou mais recente instalada. Para atualizar para a versão mais recente, execute gcloud components update.
  • Os papéis do Identity and Access Management (IAM) no projeto do Google Cloud necessários para ativar APIs, criar um pool de Identidade da carga de trabalho e um provedor e conceder papéis do IAM.

Ativar APIs e registrar o cluster

Ative as APIs do Google Cloud necessárias e registre o cluster externo.

Ative as APIs necessárias

Para ativar as APIs necessárias para o Gateway de Agente entre nuvens, execute o seguinte comando:

gcloud services enable \
    agentregistry.googleapis.com \
    apphubendpoint.googleapis.com \
    cloudresourcemanager.googleapis.com \
    cloudtrace.googleapis.com \
    iam.googleapis.com \
    iamcredentials.googleapis.com \
    iap.googleapis.com \
    logging.googleapis.com \
    modelarmor.googleapis.com \
    monitoring.googleapis.com \
    networkservices.googleapis.com \
    serviceextensions.googleapis.com \
    sts.googleapis.com \
    telemetry.googleapis.com \
    trafficdirector.googleapis.com \
    --project=PROJECT_ID

Substitua PROJECT_ID pelo ID do seu projeto doGoogle Cloud .

Extrair a chave pública do servidor de API Kubernetes

Para registrar o cluster, você precisa da chave pública que ele usa para assinar tokens de conta de serviço. Para extrair a chave pública, faça o seguinte:

  1. Defina o contexto atual de kubectl para o cluster que você quer registrar.

  2. Recupere o conjunto de chaves da Web JSON (JWKS, na sigla em inglês) do cluster e converta a primeira chave RSA em um arquivo de chave pública chamado pubkey.pem:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    
    N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n')
    
    openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \
      | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pem
    

    Esses comandos exigem um shell Bash e os utilitários jq e openssl.

Registre o cluster

Para registrar o cluster, faça o seguinte:

  1. Recupere o URL do emissor do OpenID Connect (OIDC) do cluster:

    kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
    

    A saída é o valor da flag --service-account-issuer do servidor de API Kubernetes do cluster. Esse valor pode ser diferente do URL externo do servidor de API Kubernetes. Copie a saída exatamente como ela aparece. Não adicione nem remova uma barra final.

  2. Registre o cluster:

    gcloud alpha network-services registered-clusters create CLUSTER_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --oidc-issuer-url=OIDC_ISSUER_URL \
        --api-server-public-key="$(cat pubkey.pem)"
    

    Substitua:

    • CLUSTER_NAME: um nome para o cluster registrado.
    • PROJECT_ID: ID do seu projeto do Google Cloud.
    • LOCATION: a região do Google Cloud para o cluster registrado, por exemplo, us-central1.
    • OIDC_ISSUER_URL: o URL exato do emissor que você recuperou na etapa anterior. O URL precisa começar com https://.

Evitar a exclusão acidental de recursos

Excluir o projeto do Google Cloud ou cancelar o registro de um cluster registrado enquanto as cargas de trabalho entre nuvens estão ativas desconecta os controladores no cluster e interrompe a aplicação da política. Para proteger os recursos do Google Cloud contra exclusão acidental, aplique as seguintes proteções:

  • Proteja o projeto do Google Cloud com garantias: aplique uma garantia de projeto ao projeto doGoogle Cloud que hospeda o cluster registrado, o Agent Registry e os pools de identidade federada para bloquear a exclusão acidental do projeto até que todos os clusters entre nuvens sejam desativados.
  • Restringir permissões destrutivas do IAM: limite as permissões que podem excluir clusters registrados ou recursos de gateway (como networkservices.registeredClusters.delete e networkservices.agentGateways.delete) a papéis dedicados de administrador de plataforma.
  • Manter finalizadores de recursos do Kubernetes: não remova os finalizadores de recursos personalizados no cluster gerenciados pelo controlador agent-governance-cross-cloud-controller. Os finalizadores garantem que os registros correspondentes do plano de controle do Google Cloud sejam desprovisionados de maneira limpa antes que os recursos do cluster local sejam removidos.
  • Exclua recursos personalizados antes de remover o controlador: antes de desinstalar o gráfico Helm agent-governance-cross-cloud ou excluir o cluster do Kubernetes, exclua todos os recursos personalizados GCPExtensionBinding e GCPAgentGateway e aguarde a conclusão da exclusão. Se você remover o controlador primeiro, o recurso correspondente do Gateway de Agente vai permanecer órfão no Network Services. O gateway órfão bloqueia a exclusão do modelo de conectividade do agente e do cluster registrado.

Configurar a federação de identidade da carga de trabalho

Os componentes no cluster do Gateway de Agente entre nuvens (o controlador agent-governance-cross-cloud-controller, o coletor de telemetria e o proxy) usam a federação de identidade da carga de trabalho para autenticação nas APIs doGoogle Cloud . Cada componente troca o token da conta de serviço do Kubernetes (KSA) por um token de acesso federado. Você concede papéis do IAM diretamente a essas identidades federadas, então não precisa criar contas de serviço doGoogle Cloud nem armazenar chaves de conta de serviço no cluster.

O arquivo secundário do ambiente de execução de identidade do agente (AIR, na sigla em inglês) que é executado com cada proxy usa o pool de Identidade da carga de trabalho para fornecer identidades SPIFFE às cargas de trabalho do agente. Essas identidades são as identidades de agente dos seus agentes. As políticas do Model Armor e do IAP identificam os agentes pela identidade do agente, não pelas identidades federadas dos componentes no cluster. Para o formato do principal, consulte Identificar o principal do agente.

Criar um pool de Identidade da carga de trabalho e um provedor

Para criar um pool de Identidade da carga de trabalho e um provedor OIDC para o cluster, faça o seguinte:

  1. Se o URL do emissor do OIDC do cluster não estiver acessível publicamente, salve o conjunto de chaves da Web JSON (JWKS, na sigla em inglês) do cluster em um arquivo:

    kubectl get --raw /openid/v1/jwks > cluster-jwks.json
    

    Quando você fornece o JWKS ao provedor, o Google Cloud pode verificar os tokens de KSA sem se conectar ao emissor do OIDC do cluster.

  2. Crie um pool de identidade da carga de trabalho:

    gcloud iam workload-identity-pools create POOL_ID \
        --project=PROJECT_ID \
        --location=global \
        --display-name="POOL_DISPLAY_NAME"
    
  3. Crie um provedor do OIDC no pool:

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --project=PROJECT_ID \
        --location=global \
        --workload-identity-pool=POOL_ID \
        --issuer-uri=OIDC_ISSUER_URL \
        --jwk-json-path=cluster-jwks.json \
        --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"
    

    Não especifique a flag --allowed-audiences. Os componentes entre nuvens solicitam tokens para o público-alvo padrão, que é o nome completo do recurso do provedor: //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

Substitua:

  • POOL_ID: um ID para o pool de Identidade da carga de trabalho.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • POOL_DISPLAY_NAME: um nome de exibição para o pool.
  • PROVIDER_ID: um ID para o provedor do OIDC.
  • OIDC_ISSUER_URL: o URL exato do emissor do OIDC que você recuperou ao registrar o cluster. Esse valor precisa corresponder ao valor transmitido para --oidc-issuer-url, incluindo se ele termina com uma barra final.

Implantar o plano de controle

Use o gráfico Helm fornecido para implantar o controlador no cluster, agent-governance-cross-cloud-controller e o coletor de telemetria no namespace geap-system.

Garantir a conectividade do controlador

Verifique se o firewall, o proxy, as regras de saída e as políticas de rede do cluster permitem a seguinte conectividade:

  • APIs doGoogle Cloud : os pods do controlador do agent-governance-cross-cloud-controller e o coletor de telemetria precisam ter conectividade HTTPS e gRPC de saída na porta TCP 443 para *.googleapis.com.
  • Servidor de API Kubernetes: os pods do controlador precisam conseguir acessar o servidor de API Kubernetes para monitorar os serviços, as cargas de trabalho e os recursos personalizados do Kubernetes.
  • Cargas de trabalho do agente em todos os namespaces: os pods do controlador precisam ser capazes de chamar pods do agente e do servidor MCP em qualquer namespace no cluster. O controlador busca o cartão de agente de cada carga de trabalho para registrar o agente no Agent Registry.

Conceder papéis do IAM ao controlador e ao coletor de telemetria

Conceda papéis do IAM às identidades federadas do controlador do agent-governance-cross-cloud-controller e do coletor de telemetria, que são executados no namespace geap-system:

  • Operadora de satélite (roles/networkservices.satelliteOperator)
  • Gravador de telemetria do Cloud (roles/telemetry.writer)

Para conceder os papéis, execute o seguinte comando:

for ROLE in \
    roles/networkservices.satelliteOperator \
    roles/telemetry.writer; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done

Substitua:

Instalar o gráfico Helm do plano de controle

Para instalar o plano de controle, faça o seguinte:

  1. Instale o gráfico Helm agent-governance-cross-cloud no namespace geap-system:

    helm upgrade --install agent-governance-cross-cloud \
        oci://gcr.io/gke-release/agent-governance-cross-cloud \
        --version 0.1.1-preview \
        --namespace geap-system \
        --create-namespace \
        --set gcp.projectId=PROJECT_ID \
        --set-string gcp.projectNumber=PROJECT_NUMBER \
        --set-string gcp.orgId=ORGANIZATION_ID \
        --set gcp.location=LOCATION \
        --set gcp.registeredCluster=CLUSTER_NAME \
        --set gcp.workloadIdentityPool=POOL_ID \
        --set gcp.identityProvider=PROVIDER_ID
    

    Substitua:

    Se os nós do cluster tiverem taints, por exemplo, nós arm64 na maioria dos provedores de nuvem, incluindo Google Cloud, AWS e Azure, defina tolerâncias de pod no valor do Helm k8s.tolerations. As tolerâncias se aplicam ao controlador, ao coletor do OpenTelemetry (OTel) e às implantações de gateway criadas pelo controlador. Por exemplo, salve o seguinte como tolerations-values.yaml e adicione --values tolerations-values.yaml ao comando anterior:

    k8s:
      tolerations:
      - key: "kubernetes.io/arch"
        operator: "Equal"
        value: "arm64"
        effect: "NoSchedule"
    
  2. Aguarde até que a implantação do controlador esteja pronta:

    kubectl rollout status deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system --timeout=180s
    

Implantar o plano de dados

Implante o Gateway de Agente para proxy entre nuvens (proxy Envoy) criando um recurso personalizado GCPAgentGateway. O proxy inspeciona o tráfego e aplica políticas às cargas de trabalho do agente que ele controla. Cada proxy é executado com um arquivo secundário do ambiente de execução de identidade do agente (AIR, na sigla em inglês) que intermedia identidades de carga de trabalho, certificados do Secret Discovery Service (SDS) e troca de tokens locais para o proxy.

É necessário implantar o Gateway de Agente para várias nuvens em um namespace dedicado (por exemplo, agent-gateway-system) que não contenha cargas de trabalho de agentes, servidores MCP ou outros pods de aplicativos. Um único gateway nesse namespace dedicado pode controlar o tráfego de saída das cargas de trabalho do agente em todo o cluster.

Conceder papéis do IAM ao gateway

Conceda papéis do IAM às identidades federadas do Gateway de Agente para proxy entre nuvens. A vinculação se aplica a todas as KSAs no namespace do gateway. Portanto, conceda esses papéis para cada namespace do gateway:

  • Cliente do Traffic Director (roles/trafficdirector.client)
  • Leitor de endpoint do App Hub (roles/apphubendpoint.viewer)
  • Leitor do Agent Registry (roles/agentregistry.viewer)
  • Editor de Service Extensions (roles/serviceextensions.editor), que permite que o proxy chame as chamadas de política de Service Extensions.

Para conceder os papéis, execute o seguinte comando:

for ROLE in \
    roles/trafficdirector.client \
    roles/apphubendpoint.viewer \
    roles/agentregistry.viewer \
    roles/serviceextensions.editor; do
  gcloud projects add-iam-policy-binding PROJECT_ID \
      --role="${ROLE}" \
      --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • POOL_ID: o ID do pool de Identidade da carga de trabalho.
  • GATEWAY_NAMESPACE: um namespace dedicado para o gateway. Esse namespace não pode conter cargas de trabalho do agente.

Criar um modelo de conectividade de agente

Cada gateway faz referência a um modelo de conectividade de agente, que é um recurso doGoogle Cloud que faz referência ao seu cluster registrado. Não é necessário criar um modelo separado para cada gateway: é possível mapear vários gateways para um único modelo. Também é possível criar vários modelos para o mesmo cluster.

Se você já tiver um modelo de conectividade de agente para o cluster que quer usar, pule para Criar o gateway.

Para criar um modelo de conectividade de agente, faça o seguinte:

  1. Salve a seguinte definição de modelo como act.yaml:

    description: "Agent connectivity template for CLUSTER_NAME"
    agentCompute: K8S
    registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
    
  2. Importe o modelo:

    gcloud alpha network-services agent-connectivity-templates import ACT_NAME \
        --project=PROJECT_ID \
        --location=LOCATION \
        --source=act.yaml
    

Substitua:

  • CLUSTER_NAME: o nome do cluster registrado.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: a região em que você registrou o cluster.
  • ACT_NAME: um nome para o modelo de conectividade do agente.

Criar o gateway

Para criar o gateway, faça o seguinte:

  1. Se o namespace do gateway ainda não existir, crie-o:

    kubectl create namespace GATEWAY_NAMESPACE
    

    Substitua GATEWAY_NAMESPACE pelo namespace dedicado ao gateway que você usou quando concedeu papéis ao gateway.

  2. Salve o seguinte manifesto como agent-gateway.yaml:

    apiVersion: networkservices.googleapis.com/v1alpha1
    kind: GCPAgentGateway
    metadata:
      name: GATEWAY_NAME
      namespace: GATEWAY_NAMESPACE
    spec:
      agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
    

    Substitua:

  3. Aplique o manifesto:

    kubectl apply -f agent-gateway.yaml
    
  4. Aguarde até que o gateway seja implantado e esteja pronto:

    kubectl wait --for=condition=Reconciled=True \
        gcpagentgateway/GATEWAY_NAME \
        -n GATEWAY_NAMESPACE \
        --timeout=300s
    

    Quando o gateway estiver pronto, o comando vai retornar gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.

  5. Configure sua malha de serviço para encaminhar o tráfego de saída do agente, como solicitações de modelo de linguagem grande (LLM), Protocolo de Contexto de Modelo (MCP) e agente para agente (A2A), pelo gateway.

Adicionar tolerâncias aos gateways atuais

Se você adicionar o valor do Helm k8s.tolerations depois de criar um recurso GCPAgentGateway, faça o seguinte para que o controlador recrie a implantação do gateway com as novas tolerâncias:

  1. Execute o comando helm upgrade --install de Instalar o gráfico Helm do plano de controle com --values tolerations-values.yaml.

  2. Exclua a implantação do gateway atual:

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    Repita essa etapa para cada gateway no cluster.

  3. Reinicie o controlador para que ele recrie a implantação do gateway:

    kubectl rollout restart deployment/agent-governance-cross-cloud-controller \
        --namespace geap-system
    

Esse procedimento não afeta o recurso Google Cloud AgentGateway nem os recursos GCPExtensionBinding anexados. O tráfego de saída pelo gateway é interrompido até que o controlador recrie a implantação do gateway.

Permitir conectividade de saída com as APIs do Google

Verifique se o Gateway de Agente para pods de proxy entre nuvens tem conectividade HTTPS e gRPC de saída com *.googleapis.com na porta TCP 443.

Configurar inspeção de TLS

Configure a inspeção de Transport Layer Security (TLS) para garantir que o Gateway de Agente para cross-cloud possa inspecionar e controlar o tráfego de saída.

Proteger o secret da CA de inspeção de TLS

O Gateway de Agente para entre nuvens usa uma autoridade certificadora raiz (CA) para emitir os certificados que apresenta ao inspecionar o tráfego TLS de saída. O controlador cria essa CA quando é iniciado. A CA, incluindo a chave privada, é armazenada em recursos Secret do Kubernetes em dois namespaces: o namespace do controlador (geap-system) e o namespace do gateway, em que o Gateway de Agente para proxy entre nuvens e o sidecar do AIR são implantados. Qualquer pessoa que possa ler esses recursos Secret pode personificar endpoints externos para as cargas de trabalho do agente. Para proteger a CA, aplique as seguintes proteções:

  • Restringir o acesso do RBAC ao Secret: limite as permissões get, list e watch em recursos Secret nos namespaces geap-system e de gateway ao Gateway de Agente para contas de serviço entre nuvens e administradores de plataforma dedicados. As permissões list e watch também expõem o conteúdo de Secret.
  • Isole os namespaces do controlador e do gateway: os usuários que podem criar pods em um namespace podem montar qualquer Secret nesse namespace. Execute apenas o Gateway de Agente para componentes entre nuvens no namespace geap-system e no namespace do gateway. Não implante cargas de trabalho de agentes ou outros pods nesses namespaces. Limite as permissões para criar ou modificar pods, implantações e outros recursos de carga de trabalho nesses namespaces para administradores confiáveis.
  • Criptografar dados em repouso do Secret: ative a criptografia em repouso para recursos do Secret no repositório de dados etcd do cluster. Sempre que possível, use um provedor do KMS para gerenciar as chaves de criptografia.
  • Auditar o acesso ao Secret: ative a geração de registros de auditoria do Kubernetes e monitore o acesso de leitura à CA Secret.

A seguir