Abilita Agent Sandbox su GKE

Questo documento spiega come attivare la funzionalità Agent Sandbox 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 agente isola il codice non attendibile generato con l'AI, consulta Informazioni su GKE Agent Sandbox.

Costi

Agent Sandbox è offerto 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 Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

    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 Google Cloud .

  3. Abilita le API Artifact Registry e Google Kubernetes Engine.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  4. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

  5. Assicurati che il cluster esegua GKE versione 1.35.2-gke.1269000 o successive.

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.35.2-gke.1269000"
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 Google Cloud 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 Google Cloud 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. La funzionalità Sandbox dell'agente richiede la versione 1.35.2-gke.1269000 o 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.

Attiva la sandbox dell'agente

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

Abilita Agent Sandbox 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.

Autopilot

Per creare un nuovo cluster GKE Autopilot con Agent Sandbox abilitato, includi il flag --enable-agent-sandbox:

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

Per un cluster Autopilot, assicurati che la variabile di ambiente LOCATION sia impostata su una regione (ad esempio, us-central1).

Standard

Per creare un nuovo cluster GKE Standard con Agent Sandbox abilitato, devi creare il cluster, aggiungere un pool di nodi con gVisor abilitato e poi abilitare la funzionalità Agent Sandbox. Per risparmiare sui costi, ti consigliamo di creare un cluster zonale con un solo nodo per pool:

  1. Crea il cluster:

    gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${LOCATION} \
    --num-nodes=1 \
    --cluster-version=${CLUSTER_VERSION}

    Per questo cluster Standard, assicurati che la variabile di ambiente LOCATION sia impostata su una zona (ad esempio, us-central1-a).

  2. Crea un pool di nodi separato con gVisor abilitato:

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

    LOCATION deve essere la stessa zona che hai utilizzato durante la creazione del cluster.

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

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

Abilita Agent Sandbox durante l'aggiornamento di un cluster GKE esistente

Per abilitare Agent Sandbox su un cluster esistente, il cluster deve eseguire la versione 1.35.2-gke.1269000 o successive.

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 tuo cluster Standard non ha un pool di nodil abilitato per gVisor, 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 è attivata 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 non consentita

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 warm 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.

SandboxTemplate funge da progetto riutilizzabile. SandboxWarmPool contribuisce a garantire che un numero specificato di pod pre-riscaldati 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/v1alpha1
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/v1alpha1
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 un SandboxClaim

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

Per richiedere un ambiente sandbox dal modello 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/v1alpha1
kind: SandboxClaim
metadata:
  name: sandbox-claim
  namespace: default
spec:
  sandboxTemplateRef:
    # This must match the name of the SandboxTemplate.
    name: python-runtime-template

  2. Applica il manifest SandboxClaim:

    kubectl apply -f sandbox-claim.yaml

  3. Verifica che la sandbox, la richiesta e il pool caldo 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/v1alpha1
kind: Sandbox
metadata:
  name: sandbox-example-2
spec:
  replicas: 1
  podTemplate:
    metadata:
      labels:
        sandbox: sandbox-example
    spec:
      runtimeClassName: gvisor
      restartPolicy: Always
      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

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 Google Cloud 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