Configura Agent Gateway per il cross-cloud

Questa guida spiega come eseguire il deployment di Agent Gateway per il cross-cloud su cluster Kubernetes standard per estendere la governance di Gemini Enterprise Agent Platform al tuo ambiente. Per una panoramica dell'architettura a tre piani, consulta la panoramica di Agent Gateway per il cross-cloud.

Prima di iniziare

Prima di iniziare, assicurati di disporre di quanto segue:

  • Un cluster Kubernetes conforme alla Cloud Native Computing Foundation (CNCF).
  • Un mesh di servizi o uno stack di rete esistente configurato nel cluster.
  • Connettività di rete in uscita dal cluster alle API Google Cloud tramite HTTPS (porta TCP 443).
  • Google Cloud CLI versione 591.0.0 o successive installata. Per eseguire l'aggiornamento all'ultima versione, esegui gcloud components update.
  • I ruoli Identity and Access Management (IAM) nel tuo progetto Google Cloud necessari per abilitare le API, creare un pool di identità del workload e un provider e concedere i ruoli IAM.

Abilita le API e registra il cluster

Abilita le API Google Cloud richieste, quindi registra il tuo cluster esterno.

Abilita le API richieste

Per abilitare le API richieste da Agent Gateway per il cross-cloud, esegui questo 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

Sostituisci PROJECT_ID con l'ID del tuo progettoGoogle Cloud .

Estrai la chiave pubblica del server API Kubernetes

Per registrare il cluster, devi disporre della chiave pubblica utilizzata dal cluster per firmare i token dei account di servizio. Per estrarre la chiave pubblica:

  1. Imposta il contesto kubectl attuale sul cluster che vuoi registrare.

  2. Recupera il set di chiavi web JSON (JWKS) del tuo cluster, quindi converti la prima chiave RSA in un file di chiave pubblica denominato 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
    

    Questi comandi richiedono una shell Bash e le utilità jq e openssl.

Registra il cluster

Per registrare il cluster, segui questi passaggi:

  1. Recupera l'URL emittente OpenID Connect (OIDC) del tuo cluster:

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

    L'output è il valore del flag --service-account-issuer del server API Kubernetes del tuo cluster. Questo valore potrebbe essere diverso dall'URL esterno del server API Kubernetes. Copia l'output esattamente. Non aggiungere o rimuovere uno slash finale.

  2. Registra il 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)"
    

    Sostituisci quanto segue:

    • CLUSTER_NAME: un nome per il cluster registrato.
    • PROJECT_ID: l'ID del tuo progetto Google Cloud.
    • LOCATION: la regione Google Cloud per il cluster registrato, ad esempio us-central1.
    • OIDC_ISSUER_URL: l'URL esatto dell'emittente che hai recuperato nel passaggio precedente. L'URL deve iniziare con https://.

Impedisci l'eliminazione accidentale delle risorse

L'eliminazione del progetto Google Cloud o l'annullamento della registrazione di un cluster registrato mentre i workload cross-cloud sono attivi disconnette i controller nel cluster e interrompe l'applicazione delle policy. Per proteggere le risorse Google Cloud dall'eliminazione accidentale, applica le seguenti misure di salvaguardia:

  • Proteggi il progetto Google Cloud con i blocchi: applica un blocco del progetto al progettoGoogle Cloud che ospita il cluster registrato, Agent Registry e i pool di identità federate per bloccare l'eliminazione accidentale del progetto fino al ritiro di tutti i cluster cross-cloud.
  • Limita le autorizzazioni IAM distruttive: limita le autorizzazioni che possono eliminare i cluster registrati o le risorse del gateway (come networkservices.registeredClusters.delete e networkservices.agentGateways.delete) ai ruoli di amministratore della piattaforma dedicati.
  • Conserva i finalizzatori delle risorse Kubernetes: non rimuovere i finalizzatori dalle risorse personalizzate nel cluster gestite dal controller agent-governance-cross-cloud-controller. I finalizzatori assicurano che il deprovisioning delle registrazioni del control plane Google Cloud corrispondenti venga eseguito in modo pulito prima della rimozione delle risorse del cluster locale.
  • Elimina le risorse personalizzate prima di rimuovere il controller: prima di disinstallare il chart Helm agent-governance-cross-cloud o eliminare il cluster Kubernetes, elimina tutte le risorse personalizzate GCPExtensionBinding e GCPAgentGateway e attendi il completamento dell'eliminazione. Se rimuovi prima il controller, la risorsa Agent Gateway corrispondente rimane orfana in Network Services. Il gateway orfano blocca l'eliminazione del template di connettività dell'agente e del cluster registrato.

Configura la federazione delle identità per i workload

I componenti in-cluster di Agent Gateway per cross-cloud, ovvero il controller agent-governance-cross-cloud-controller, l'agente di raccolta di telemetria e il proxy, utilizzano la federazione delle identità per i workload per autenticarsi alle APIGoogle Cloud . Ogni componente scambia il proprio token del account di servizio Kubernetes (KSA) con un token di accesso federato. Concedi i ruoli IAM direttamente a queste identità federate, quindi non è necessario creare service accountGoogle Cloud o archiviare chiavi dei account di servizio nel tuo cluster.

Il sidecar Agent Identity Runtime (AIR) eseguito con ogni proxy utilizza il pool di identità del workload per fornire identità SPIFFE ai workload degli agenti. Queste identità sono le identità dell'agente dei tuoi agenti. Le policy di Model Armor e IAP identificano gli agenti in base alla loro identità, non alle identità federate dei componenti nel cluster. Per il formato dell'entità, consulta Identifica l'entità dell'agente.

Crea un provider e un pool di identità del workload

Per creare un pool di identità del workload e un provider OIDC per il tuo cluster, segui questi passaggi:

  1. Se l'URL dell'emittente OIDC del tuo cluster non è raggiungibile pubblicamente, salva il set di chiavi web JSON (JWKS) del tuo cluster in un file:

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

    Quando fornisci il JWKS al provider, Google Cloud può verificare i token KSA senza connettersi all'emittente OIDC del tuo cluster.

  2. Crea un pool di identità del workload:

    gcloud iam workload-identity-pools create POOL_ID \
        --project=PROJECT_ID \
        --location=global \
        --display-name="POOL_DISPLAY_NAME"
    
  3. Crea un provider OIDC nel 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']"
    

    Non specificare il flag --allowed-audiences. I componenti cross-cloud richiedono token per il pubblico predefinito, ovvero il nome completo della risorsa del provider: //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID.

Sostituisci quanto segue:

  • POOL_ID: un ID per il pool di identità del workload.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • POOL_DISPLAY_NAME: un nome visualizzato per il pool.
  • PROVIDER_ID: un ID per il provider OIDC.
  • OIDC_ISSUER_URL: l'URL esatto dell'emittente OIDC che hai recuperato quando hai registrato il cluster. Questo valore deve corrispondere al valore passato a --oidc-issuer-url, incluso l'eventuale slash finale.

Esegui il deployment del control plane

Utilizza il chart Helm fornito per eseguire il deployment del controller in-cluster, agent-governance-cross-cloud-controller e del raccoglitore di telemetria nello spazio dei nomi geap-system.

Assicurati che il controller sia connesso

Assicurati che il firewall, il proxy, le regole in uscita e le policy di rete del cluster consentano la seguente connettività:

  • APIGoogle Cloud : i pod del controller agent-governance-cross-cloud-controller e l'agente di raccolta della telemetria devono avere connettività HTTPS e gRPC in uscita sulla porta TCP 443 verso *.googleapis.com.
  • Server API Kubernetes: i pod del controller devono essere in grado di raggiungere il server API Kubernetes per monitorare i servizi, i workload e le risorse personalizzate di Kubernetes.
  • Workload degli agenti in tutti gli spazi dei nomi: i pod del controller devono essere in grado di chiamare i pod dell'agente e del server MCP in qualsiasi spazio dei nomi del cluster. Il controller recupera l'Agent Card da ogni workload dell'agente per registrarlo in Agent Registry.

Concedi i ruoli IAM al controller e al raccoglitore di telemetria

Concedi i ruoli IAM alle identità federate del controller agent-governance-cross-cloud-controller e del raccoglitore di telemetria, che vengono eseguite nello spazio dei nomi geap-system:

  • Operatore satellitare (roles/networkservices.satelliteOperator)
  • Cloud Telemetry Writer (roles/telemetry.writer)

Per concedere i ruoli, esegui questo 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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.

Installa il chart Helm del control plane

Per installare il control plane, segui questi passaggi:

  1. Installa il chart Helm agent-governance-cross-cloud nello spazio dei nomi 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
    

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto Google Cloud .
    • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
    • ORGANIZATION_ID: l'ID della tua organizzazioneGoogle Cloud . Se il tuo progetto non è associato a un'organizzazione, ometti il flag --set-string gcp.orgId.
    • LOCATION: la regione in cui hai registrato il cluster, ad esempio us-central1.
    • CLUSTER_NAME: il nome del cluster registrato.
    • POOL_ID: l'ID del pool di identità del workload.
    • PROVIDER_ID: l'ID del provider del pool di identità del workload.

    Se i nodi del cluster hanno taint, ad esempio i nodi arm64 sulla maggior parte dei provider cloud, tra cui Google Cloud, AWS e Azure, imposta le tolleranze dei pod nel valore Helm k8s.tolerations. Le tolleranze si applicano ai deployment del controller, del raccoglitore OpenTelemetry (OTel) e del gateway creati dal controller. Ad esempio, salva quanto segue come tolerations-values.yaml, quindi aggiungi --values tolerations-values.yaml al comando precedente:

    k8s:
      tolerations:
      - key: "kubernetes.io/arch"
        operator: "Equal"
        value: "arm64"
        effect: "NoSchedule"
    
  2. Attendi che il deployment del controller sia pronto:

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

Esegui il deployment del piano dati

Esegui il deployment dell'Agent Gateway per il proxy cross-cloud (proxy Envoy) creando una risorsa personalizzata GCPAgentGateway. Il proxy ispeziona il traffico e applica le policy per i workload degli agenti che gestisce. Ogni proxy viene eseguito con un sidecar Agent Identity Runtime (AIR) che gestisce le Workload Identity, i certificati Secret Discovery Service (SDS) e lo scambio di token locale per il proxy.

Devi eseguire il deployment di Agent Gateway per il cross-cloud in uno spazio dei nomi dedicato (ad esempio agent-gateway-system) che non contenga workload degli agenti, server MCP o altri pod di applicazioni. Un singolo gateway in questo spazio dei nomi dedicato può gestire il traffico in uscita dai workload degli agenti nel cluster.

Concedi ruoli IAM al gateway

Concedi i ruoli IAM alle identità federate dell'Agent Gateway per il proxy cross-cloud. L'associazione si applica a tutti i KSA nello spazio dei nomi del gateway, quindi concedi questi ruoli per ogni spazio dei nomi del gateway:

  • Client Traffic Director (roles/trafficdirector.client)
  • App Hub Endpoint Viewer (roles/apphubendpoint.viewer)
  • Agent Registry Viewer (roles/agentregistry.viewer)
  • Service Extensions Editor (roles/serviceextensions.editor), che consente al proxy di chiamare i callout delle policy di Service Extensions

Per concedere i ruoli, esegui questo 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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • GATEWAY_NAMESPACE: uno spazio dei nomi dedicato per il gateway. Questo spazio dei nomi non deve contenere workload degli agenti.

Crea un template di connettività dell'agente

Ogni gateway fa riferimento a un template di connettività dell'agente, ovvero una risorsaGoogle Cloud che fa riferimento al tuocluster registrato. Non è necessario creare un modello separato per ogni gateway: puoi mappare più gateway a un singolo modello. Puoi anche creare più template per lo stesso cluster.

Se hai già un template di connettività dell'agente per il tuo cluster che vuoi utilizzare, vai a Crea il gateway.

Per creare un template di connettività dell'agente, segui questi passaggi:

  1. Salva la seguente definizione del template come act.yaml:

    description: "Agent connectivity template for CLUSTER_NAME"
    agentCompute: K8S
    registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
    
  2. Importa il template:

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

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster registrato.
  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • LOCATION: la regione in cui hai registrato il cluster.
  • ACT_NAME: un nome per il template di connettività dell'agente.

Crea il gateway

Per creare il gateway:

  1. Se lo spazio dei nomi del gateway non esiste già, crealo:

    kubectl create namespace GATEWAY_NAMESPACE
    

    Sostituisci GATEWAY_NAMESPACE con lo spazio dei nomi dedicato per il gateway che hai utilizzato quando hai concesso i ruoli al gateway.

  2. Salva il seguente manifest come 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"
    

    Sostituisci quanto segue:

  3. Applica il manifest:

    kubectl apply -f agent-gateway.yaml
    
  4. Attendi che il gateway venga distribuito e sia pronto:

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

    Quando il gateway è pronto, il comando restituisce gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition met.

  5. Configura il mesh di servizi in modo che inoltri il traffico in uscita degli agenti, come le richieste di modelli linguistici di grandi dimensioni (LLM), Model Context Protocol (MCP) e da agente ad agente (A2A), tramite il gateway.

Aggiungi tolleranze ai gateway esistenti

Se aggiungi il valore Helm k8s.tolerations dopo aver creato una risorsa GCPAgentGateway, segui questi passaggi per fare in modo che il controller ricrei il deployment del gateway con le nuove tolleranze:

  1. Esegui il comando helm upgrade --install da Installa il chart Helm del control plane con --values tolerations-values.yaml.

  2. Elimina il deployment del gateway esistente:

    kubectl delete deployment GATEWAY_NAME \
        --namespace GATEWAY_NAMESPACE
    

    Ripeti questo passaggio per ogni gateway del cluster.

  3. Riavvia il controller in modo che ricrei il deployment del gateway:

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

Questa procedura non influisce sulla risorsa Google Cloud AgentGateway o su eventuali risorse GCPExtensionBinding collegate. Il traffico in uscita attraverso il gateway viene interrotto finché il controller non ricrea il deployment del gateway.

Consenti la connettività in uscita alle API di Google

Assicurati che l'Agent Gateway per i pod proxy cross-cloud disponga di connettività HTTPS e gRPC in uscita a *.googleapis.com sulla porta TCP 443.

Configura l'ispezione TLS

Configura l'ispezione TLS (Transport Layer Security) per assicurarti che Agent Gateway per cross-cloud possa ispezionare e gestire il traffico in uscita.

Proteggi il secret della CA di ispezione TLS

Agent Gateway per cross-cloud utilizza un'autorità di certificazione radice (CA) per emettere i certificati che presenta quando ispeziona il traffico TLS in uscita. Il controller crea questa CA all'avvio. La CA, inclusa la sua chiave privata, viene archiviata nelle risorse Kubernetes Secret in due spazi dei nomi: lo spazio dei nomi del controller (geap-system) e lo spazio dei nomi del gateway, in cui vengono eseguiti il deployment dell'Agent Gateway per il proxy cross-cloud e del sidecar AIR. Chiunque possa leggere queste risorse Secret può impersonare endpoint esterni per i workload degli agenti. Per proteggere la CA, applica le seguenti misure di salvaguardia:

  • Limita l'accesso RBAC a Secret: limita le autorizzazioni get, list e watch sulle risorse Secret negli spazi dei nomi geap-system e gateway all'Agent Gateway per i service account cross-cloud e gli amministratori della piattaforma dedicati. Le autorizzazioni list e watch espongono anche i contenuti di Secret.
  • Isola gli spazi dei nomi del controller e del gateway: gli utenti che possono creare pod in uno spazio dei nomi possono montare qualsiasi Secret in quello spazio dei nomi. Esegui solo Agent Gateway per i componenti cross-cloud nello spazio dei nomi geap-system e nello spazio dei nomi del gateway. Non eseguire il deployment dei workload degli agenti o di altri pod in questi spazi dei nomi. Limita le autorizzazioni per creare o modificare pod, deployment e altre risorse dei workload in questi spazi dei nomi agli amministratori attendibili.
  • Cripta i dati Secret at-rest: attiva la crittografia at-rest per le risorse Secret nel datastore etcd del tuo cluster. Se possibile, utilizza un provider KMS per gestire le chiavi di crittografia.
  • Controlla l'accesso a Secret: abilita l'audit logging di Kubernetes e monitora l'accesso in lettura alla CA Secret.

Passaggi successivi