Abilita Agent Sandbox su GKE

Questo documento spiega come abilitare la funzionalità sandbox dell'agente in un cluster Google Kubernetes Engine (GKE). Spiega anche come creare un ambiente sandbox sul cluster per eseguire in sicurezza codice non attendibile.

Per una panoramica di come la funzionalità Sandbox dell'agente isola il codice non attendibile generato con l'AI, consulta Informazioni su GKE Agent Sandbox.

Costi

Sandbox dell'agente è offerta senza costi aggiuntivi in GKE. I prezzi di GKE si applicano alle risorse che crei.

Per evitare addebiti non necessari, assicurati di disabilitare GKE o eliminare il progetto dopo aver completato questo documento.

Prima di iniziare

1. Nella console Cloud de Confiance , nella pagina di selezione del progetto, seleziona o crea un progetto Cloud de Confiance .

   Ruoli richiesti per selezionare o creare un progetto

   • Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
   • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

   Vai al selettore di progetti

2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .

3. Abilita le API Artifact Registry e Google Kubernetes Engine, se non sono già abilitate.

   Ruoli richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

   Abilita le API

4. Nella console Cloud de Confiance , attiva Cloud Shell.

   Attiva Cloud Shell

5. Assicurati che il cluster esegua GKE versione 1.36.3-gke.1767000 o successive (supporta l'API v1beta1).

Definisci le variabili di ambiente

Per semplificare i comandi eseguiti in questo documento, puoi impostare le variabili di ambiente in Cloud Shell. In Cloud Shell, definisci le seguenti variabili di ambiente utili eseguendo questi comandi:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export LOCATION="us-central1"
export CLUSTER_VERSION="1.36.3-gke.1767000"
export NODE_POOL_NAME="agent-sandbox-pool"
export MACHINE_TYPE="e2-standard-2"

Ecco una spiegazione di queste variabili di ambiente:

• PROJECT_ID: l'ID del tuo progetto Cloud de Confiance by S3NS corrente. La definizione di questa variabile consente di garantire che tutte le risorse, come il cluster GKE, vengano create nel progetto corretto.
• CLUSTER_NAME: il nome del cluster GKE, ad esempio agent-sandbox-cluster.
• LOCATION: la Cloud de Confiance by S3NS regione o la zona in cui viene creato il cluster GKE. Imposta questo valore sulla regione (ad esempio, us-central1) se crei un cluster Autopilot o sulla zona (ad esempio, us-central1-a) se crei un cluster Standard.
• CLUSTER_VERSION: la versione di GKE in esecuzione sul cluster (1.36.3-gke.1767000 o versioni successive).
• NODE_POOL_NAME: il nome del pool di nodi che eseguirà i carichi di lavoro in sandbox, ad esempio agent-sandbox-pool. Questa variabile è obbligatoria solo se stai creando un cluster GKE Standard.
• MACHINE_TYPE: il tipo di macchina dei nodi nel pool di nodi, ad esempio e2-standard-2. Per informazioni dettagliate sulle diverse serie di macchine e sulla scelta tra le diverse opzioni, consulta la guida alle risorse e al confronto per le famiglie di macchine. Questa variabile è obbligatoria solo se stai creando un cluster GKE Standard.

Abilita sandbox dell'agente

Puoi attivare la funzionalità Agent Sandbox quando crei un nuovo cluster o quando aggiorni un cluster esistente.

Abilita la sandbox dell'agente durante la creazione di un nuovo cluster GKE

Ti consigliamo di utilizzare un cluster Autopilot per un'esperienza Kubernetes completamente gestita. Per scegliere la modalità operativa GKE più adatta ai tuoi workload, consulta Scegliere una modalità operativa GKE.

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --cluster-version=${CLUSTER_VERSION} \
    --enable-agent-sandbox

Abilita la sandbox dell'agente durante l'aggiornamento di un cluster GKE esistente

Per abilitare Agent Sandbox su un cluster esistente, il cluster deve eseguire la versione 1.36.3-gke.1767000 o successive, che supporta l'API v1beta1.

Assicurati che la variabile di ambiente LOCATION sia impostata sulla regione o sulla zona in cui si trova il cluster esistente.

1. Se utilizzi un cluster GKE Standard, Agent Sandbox si basa su gVisor. Se il cluster Standard non ha un pool di nodi con gVisor abilitato, devi prima crearne uno:

   gcloud container node-pools create ${NODE_POOL_NAME} \
       --cluster=${CLUSTER_NAME} \
       --machine-type=${MACHINE_TYPE} \
       --location=${LOCATION} \
       --image-type=cos_containerd \
       --sandbox=type=gvisor
   

2. Aggiorna il cluster per abilitare la funzionalità Sandbox dell'agente:

   gcloud beta container clusters update ${CLUSTER_NAME} \
       --location=${LOCATION} \
       --enable-agent-sandbox
   

Verificare la configurazione

Puoi verificare se la funzionalità Sandbox dell'agente è abilitata esaminando la descrizione del cluster.

gcloud beta container clusters describe ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --format="value(addonsConfig.agentSandboxConfig.enabled)"

Se hai creato un cluster Autopilot, la località è la regione (ad esempio us-central1). Se hai creato un cluster Standard, la località è la zona (ad esempio us-central1-a).

Se la funzionalità viene attivata correttamente, il comando restituisce True.

Requisiti di deployment della sandbox dell'agente

Per eseguire il deployment di un workload, ad esempio Sandbox o SandboxTemplate, il manifest YAML deve includere impostazioni di sicurezza e configurazione specifiche. GKE applica questi requisiti utilizzando un criterio di controllo dell'ammissione (VAP). Se questi requisiti non vengono soddisfatti, il controller di ammissione rifiuta il deployment.

Configurazione richiesta

Il manifest di deployment deve includere le seguenti impostazioni:

• runtimeClassName: gvisor: garantisce che il pod venga eseguito in una sandbox gVisor.
• automountServiceAccountToken: false: impedisce al pod di montare automaticamente il token del account di servizio predefinito.
• securityContext.runAsNonRoot: true: garantisce che il container non venga eseguito come utente root.
• securityContext.capabilities.drop: ["ALL"]: elimina tutte le funzionalità Linux dal container.
• resources.limits: devi specificare i limiti di CPU e memoria per evitare potenziali scenari di denial of service (DoS).
• nodeSelector: deve avere come target sandbox.gke.io/runtime: gvisor.
• tolerations: deve includere una tolleranza per il taint sandbox.gke.io/runtime=gvisor:NoSchedule.

Configurazione vietata

Il manifest di deployment non deve includere quanto segue:

• hostNetwork: true, hostPID: true o hostIPC: true.
• privileged: true nei contesti di sicurezza dei container.
• HostPath volumi.
• Funzionalità aggiunte (capabilities.add).
• Impostazioni di hostPort.
• sysctl personalizzati.
• Volumi previsti per i token o i certificati del account di servizio.

Esegui il deployment di un ambiente sandbox

Ti consigliamo di eseguire il deployment di un ambiente sandbox definendo un SandboxTemplate e mantenendo pronte le istanze pre-riscaldate utilizzando un SandboxWarmPool. Puoi quindi richiedere un'istanza da questo pool di nodi in attesa utilizzando un SandboxClaim. In alternativa, puoi creare una sandbox direttamente, ma questo approccio non supporta i pool caldi.

SandboxTemplate, SandboxWarmPool, SandboxClaim e Sandbox sono risorse personalizzate di Kubernetes.

Consigliato: crea un SandboxTemplate e un SandboxWarmPool

SandboxTemplate funge da progetto riutilizzabile. SandboxWarmPool contribuisce a garantire che un numero specificato di pod preinizializzati siano sempre in esecuzione e pronti per essere rivendicati. L'utilizzo di questa risorsa personalizzata riduce al minimo la latenza di avvio.

Per eseguire il deployment di un ambiente in sandbox creando SandboxTemplate e SandboxWarmPool, completa i seguenti passaggi:

1. In Cloud Shell, crea un file denominato sandbox-template.yaml con il seguente contenuto:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxTemplate
   metadata:
     name: python-runtime-template
     namespace: default
   spec:
     podTemplate:
       metadata:
         labels:
           sandbox-type: python-runtime
       spec:
         runtimeClassName: gvisor # Required
         automountServiceAccountToken: false # Required
         securityContext:
           runAsNonRoot: true # Required
         nodeSelector:
           sandbox.gke.io/runtime: gvisor # Required
         tolerations:
         - key: "sandbox.gke.io/runtime"
           value: "gvisor"
           effect: "NoSchedule" # Required
         containers:
         - name: runtime
           image: registry.k8s.io/agent-sandbox/python-runtime-sandbox:v0.1.0
           ports:
           - containerPort: 8888
           resources:
             requests:
               cpu: "250m"
               memory: "512Mi"
             limits:
               cpu: "500m"
               memory: "1Gi" # Required
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
         restartPolicy: OnFailure
   

2. Applica il manifest SandboxTemplate:

   kubectl apply -f sandbox-template.yaml
   

3. Crea un file denominato sandbox-warmpool.yaml con i seguenti contenuti:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxWarmPool
   metadata:
     name: python-runtime-warmpool
     namespace: default
     labels:
       app: python-runtime-warmpool
   spec:
     replicas: 2
     sandboxTemplateRef:
       # This must match the name of the SandboxTemplate.
       name: python-runtime-template
   

4. Applica il manifest SandboxWarmPool:

   kubectl apply -f sandbox-warmpool.yaml
   

Crea una SandboxClaim

SandboxClaim richiede una sandbox dal pool caldo. Poiché hai creato un pool caldo, la sandbox creata adotta un pod in esecuzione dal pool anziché avviare un nuovo pod.

Per richiedere una sandbox dal pool caldo creando un SandboxClaim, completa i seguenti passaggi:

1. Crea un file denominato sandbox-claim.yaml con i seguenti contenuti:

   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxClaim
   metadata:
     name: sandbox-claim
     namespace: default
   spec:
     warmPoolRef:
       # This must match the name of the SandboxWarmPool.
       name: python-runtime-warmpool
   

2. Applica il manifest SandboxClaim:

   kubectl apply -f sandbox-claim.yaml
   

3. Verifica che la sandbox, la richiesta e il warm pool siano pronti:

   kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
   

Alternativa: crea una sandbox direttamente

Se non hai bisogno dei tempi di avvio rapidi forniti dai pool caldi, puoi eseguire il deployment di una sandbox direttamente senza utilizzare i modelli.

Per eseguire il deployment di un ambiente in sandbox creando direttamente una sandbox, completa i seguenti passaggi:

1. Crea un file denominato sandbox.yaml con i seguenti contenuti:

   apiVersion: agents.x-k8s.io/v1beta1
   kind: Sandbox
   metadata:
     name: sandbox-example-2
   spec:
     replicas: 1
     podTemplate:
       metadata:
         labels:
           sandbox: sandbox-example
       spec:
         runtimeClassName: gvisor
         restartPolicy: OnFailure
         automountServiceAccountToken: false # Required
         securityContext:
           runAsNonRoot: true # Required
           runAsUser: 1000 # Required if image defaults to root (e.g. busybox)
         nodeSelector:
           sandbox.gke.io/runtime: gvisor
         tolerations:
         - key: "sandbox.gke.io/runtime"
           value: "gvisor"
           effect: "NoSchedule" # Required
         containers:
         - name: my-container
           image: busybox
           command: ["/bin/sh", "-c"]
           args: ["sleep 3600000; echo 'Container finished successfully'; exit 0"]
           securityContext:
             capabilities:
               drop: ["ALL"] # Required
             allowPrivilegeEscalation: false
           resources:
             limits:
               cpu: "100m"
               memory: "128Mi" # Required
   

2. Applica il manifest Sandbox:

   kubectl apply -f sandbox.yaml
   

3. Verifica che la sandbox sia in esecuzione:

   kubectl get sandbox
   

Migra la sandbox dell'agente da v1alpha1 a v1beta1

Se il cluster è stato deployment con una versione precedente di Agent Sandbox utilizzando le risorse personalizzate v1alpha1, puoi eseguire l'upgrade alla versione GKE 1.36.3-gke.1767000 o successive con tempo di inattività del workload quasi nullo.

Nota:questa procedura di migrazione si applica ai cluster che utilizzano la funzionalità gestita GKE Agent Sandbox (--enable-agent-sandbox). Se hai eseguito il deployment di Agent Sandbox utilizzando manifest open source, consulta la guida alla migrazione upstream.

Principali differenze tra le API v1alpha1 e v1beta1

Eseguire la migrazione utilizzando lo strumento di migrazione

Per creare automaticamente pool di pre-riscaldamento shadow e rendere persistente di nuovo lo spazio di archiviazione, utilizza lo script di migrazione canonico dal repository Agent Sandbox.

Scarica e prepara lo script:

curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh

Runbook di migrazione passo passo

Per eseguire la migrazione di un cluster esistente con tempi di inattività del carico di lavoro quasi nulli, completa le seguenti tre fasi in ordine:

Fase 1: fase di bootstrap pre-upgrade

1. Esegui il backup delle risorse esistenti: salva un backup YAML delle risorse dichiarative di Agent Sandbox (sandboxtemplates, sandboxwarmpools e sandboxclaims):

   kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims \
       --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yaml
   

2. Verifica la conformità alla sicurezza del modello: assicurati che le risorse SandboxTemplate esistenti soddisfino i requisiti di deployment della sandbox dell'agente. Durante la migrazione dell'archiviazione nella fase 3, il controller di ammissione rifiuta gli aggiornamenti a tutti i modelli che non rispettano queste norme di sicurezza.

3. Visualizza l'anteprima dei pool shadow da creare:

   ./migrate.sh --phase=bootstrap --dry-run
   

4. Esegui la fase di bootstrap:

   ./migrate.sh --phase=bootstrap
   

5. Verifica i pool shadow creati:

   kubectl get sandboxwarmpools --all-namespaces \
       -o custom-columns="NAMESPACE:.metadata.namespace,NAME:.metadata.name,REPLICAS:.spec.replicas,SHADOW:.metadata.annotations.agents\.x-k8s\.io/migration-shadow"
   

Fase 2: esegui l'upgrade del control plane GKE

Esegui l'upgrade del control plane GKE alla versione 1.36.3-gke.1767000 o successive:

gcloud container clusters upgrade ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --master \
    --cluster-version=1.36.3-gke.1767000

Durante l'implementazione del control plane, tieni presente quanto segue:

• I pod non subiscono riavvii o tempi di inattività.
• Il nuovo controller e l'endpoint webhook /convert vengono implementati sul control plane.

Fase 3: migrazione dell'archiviazione post-upgrade

Al termine dell'upgrade del control plane, aggiorna le credenziali e riscrivi gli oggetti etcd archiviati eseguendo la fase di migrazione dell'archiviazione:

./migrate.sh --phase=migrate

Elenco di controllo per la verifica post-migrazione

Se una CustomResourceDefinition continua a elencare ["v1alpha1", "v1beta1"] in .status.storedVersions dopo il completamento della fase di migrazione, si tratta del comportamento previsto di Kubernetes. Lo script di migrazione riscrive tutti i record esistenti in v1beta1 in etcd, ma Kubernetes non rimuove automaticamente le versioni obsolete dall'elenco status.storedVersions.

Dopo aver verificato che tutte le risorse siano state migrate, puoi facoltativamente eliminare v1alpha1 dalle versioni archiviate:

for crd in \
    sandboxes.agents.x-k8s.io \
    sandboxclaims.extensions.agents.x-k8s.io \
    sandboxtemplates.extensions.agents.x-k8s.io \
    sandboxwarmpools.extensions.agents.x-k8s.io; do
  kubectl patch crd "${crd}" --subresource=status --type=merge \
    -p '{"status":{"storedVersions":["v1beta1"]}}'
done

Risolvere i problemi di migrazione

Se riscontri problemi dopo l'upgrade del control plane o l'esecuzione della migrazione dell'archiviazione, risolvili in avanti anziché tentare di eseguire il downgrade del control plane:

• Richiesta bloccata in WarmPoolNotFound:

  • Se una rivendicazione di avvio a freddo v1alpha1 è stata eseguita l'upgrade senza eseguire ./migrate.sh --phase=bootstrap, crea manualmente il pool tiepido shadow mancante:

    apiVersion: extensions.agents.x-k8s.io/v1beta1
    kind: SandboxWarmPool
    metadata:
      name: shadow-pool-TEMPLATE_NAME
      namespace: NAMESPACE
      annotations:
        agents.x-k8s.io/migration-shadow: "true"
    spec:
      replicas: 0
      sandboxTemplateRef:
        name: TEMPLATE_NAME
    

  • Se una richiesta ha specificato un warm pool specifico che non esiste più, crea la risorsa SandboxWarmPool mancante con quel nome o aggiorna spec.warmPoolRef.name nella richiesta in modo che faccia riferimento a un warm pool esistente.

• Condizione rivendicazione Ready=False: esegui kubectl describe sandboxclaim per ispezionare gli eventi nella rivendicazione. Assicurati che il SandboxTemplate a cui viene fatto riferimento soddisfi tutti i requisiti di deployment di Agent Sandbox e riapplica il modello, se necessario.

• Errori di conversione o del controller: verifica che il lease di selezione del leader del control plane sia attivo eseguendo kubectl get leases -n gke-managed-agentsandbox. Se i problemi persistono, contatta l'assistenza clienti Google Cloud.

Disattiva la sandbox dell'agente

Per disattivare la funzionalità Sandbox dell'agente, utilizza il comando gcloud beta container clusters update con il flag --no-enable-agent-sandbox.

gcloud beta container clusters update ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --no-enable-agent-sandbox

Se hai creato un cluster Autopilot, la località è la regione (ad esempio us-central1). Se hai creato un cluster Standard, la località è la zona (ad esempio us-central1-a).

Libera spazio

Per evitare che al tuo account Cloud de Confiance by S3NS vengano addebitati costi, elimina il cluster GKE che hai creato.

gcloud container clusters delete $CLUSTER_NAME \
    --location=${LOCATION} \
    --quiet

Se hai creato un cluster Autopilot, la località è la regione (ad esempio us-central1). Se hai creato un cluster Standard, la località è la zona (ad esempio us-central1-a).

Passaggi successivi

• Scopri come salvare e ripristinare gli ambienti sandbox dell'agente con gli snapshot dei pod.
• Scopri di più sulla tecnologia sottostante utilizzata dalla sandbox dell'agente.
• Scopri di più sulla sicurezza di GKE.
• Esplora il progetto open source Agent Sandbox su GitHub.
• Scopri come utilizzare Kata Containers open source con Agent Sandbox. Kata Containers non è un prodotto Cloud de Confiance . Se installi e utilizzi questo software, sei responsabile della gestione e della risoluzione dei problemi. L'assistenza e gli SLA di Google non si applicano a Kata Containers.