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:
Defina o contexto atual de
kubectlpara o cluster que você quer registrar.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.pemEsses comandos exigem um shell Bash e os utilitários
jqeopenssl.
Registre o cluster
Para registrar o cluster, faça o seguinte:
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-issuerdo 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.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 comhttps://.
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.deleteenetworkservices.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-cloudou excluir o cluster do Kubernetes, exclua todos os recursos personalizadosGCPExtensionBindingeGCPAgentGatewaye 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:
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.
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"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-controllere o coletor de telemetria precisam ter conectividade HTTPS e gRPC de saída na porta TCP443para*.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:
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.
Instalar o gráfico Helm do plano de controle
Para instalar o plano de controle, faça o seguinte:
Instale o gráfico Helm
agent-governance-cross-cloudno namespacegeap-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_IDSubstitua:
PROJECT_ID: o ID do projeto Google Cloud .PROJECT_NUMBER: o número do projeto do Google Cloud .ORGANIZATION_ID: o ID da organização do Google Cloud . Se o projeto não estiver associado a uma organização, omita a flag--set-string gcp.orgId.LOCATION: a região em que você registrou o cluster, por exemplo,us-central1.CLUSTER_NAME: o nome do cluster registrado.POOL_ID: o ID do pool de Identidade da carga de trabalho.PROVIDER_ID: o ID do provedor do pool de Identidade da carga de trabalho.
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 comotolerations-values.yamle adicione--values tolerations-values.yamlao comando anterior:k8s: tolerations: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64" effect: "NoSchedule"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:
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"
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:
Se o namespace do gateway ainda não existir, crie-o:
kubectl create namespace GATEWAY_NAMESPACE
Substitua
GATEWAY_NAMESPACEpelo namespace dedicado ao gateway que você usou quando concedeu papéis ao gateway.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:
GATEWAY_NAME: um nome para o gateway.GATEWAY_NAMESPACE: o namespace dedicado para o gateway que você usou quando concedeu papéis ao gateway.PROJECT_ID: o ID do projeto Google Cloud .LOCATION: a região do modelo de conectividade do agente. Essa região precisa corresponder à região em que você registrou o cluster.ACT_NAME: o nome do modelo de conectividade do agente.
Aplique o manifesto:
kubectl apply -f agent-gateway.yaml
Aguarde até que o gateway seja implantado e esteja pronto:
kubectl wait --for=condition=Reconciled=True \ gcpagentgateway/GATEWAY_NAME \ -n GATEWAY_NAMESPACE \ --timeout=300sQuando o gateway estiver pronto, o comando vai retornar
gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.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:
Execute o comando
helm upgrade --installde Instalar o gráfico Helm do plano de controle com--values tolerations-values.yaml.Exclua a implantação do gateway atual:
kubectl delete deployment GATEWAY_NAME \ --namespace GATEWAY_NAMESPACERepita essa etapa para cada gateway no cluster.
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õesget,listewatchem recursosSecretnos namespacesgeap-systeme de gateway ao Gateway de Agente para contas de serviço entre nuvens e administradores de plataforma dedicados. As permissõeslistewatchtambém expõem o conteúdo deSecret. - Isole os namespaces do controlador e do gateway: os usuários que podem criar
pods em um namespace podem montar qualquer
Secretnesse namespace. Execute apenas o Gateway de Agente para componentes entre nuvens no namespacegeap-systeme 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 doSecretno 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 à CASecret.
A seguir
- Implantar e registrar agentes entre nuvens
- Aplicar políticas de governança entre nuvens
- Configurar a observabilidade do agente entre nuvens