Abilita Agent Sandbox su GKE

Questo documento spiega come abilitare la funzionalità Sandbox agente in un cluster Google Kubernetes Engine (GKE). Spiega anche come creare un ambiente in 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 dall'AI, consulta Informazioni su GKE Agent Sandbox.

Costi

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

    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 su cui ti è stato concesso un ruolo.
    • Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l' resourcemanager.projects.create autorizzazione. Scopri come concedere i ruoli.

    Vai al selettore di progetti

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

  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 servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  4. Nella Google Cloud console, attiva Cloud Shell.

    Attiva Cloud Shell

  5. Assicurati che sul cluster sia in esecuzione GKE versione 1.35.2-gke.1269000 o successive.

Definisci le variabili di ambiente

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

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"

Di seguito è riportata una spiegazione di queste variabili di ambiente:

  • PROJECT_ID: l'ID del tuo progetto corrente. Google Cloud 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 questa opzione 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 su cui verrà eseguito il cluster. La funzionalità Sandbox agente richiede la versione 1.35.2-gke.1269000 o successive.
  • NODE_POOL_NAME: il nome del pool di nodi che eseguirà i workload in sandbox, ad esempio agent-sandbox-pool. Questa variabile è obbligatoria solo se crei 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 crei un cluster GKE Standard.

Abilita Sandbox agente

Puoi abilitare la funzionalità Sandbox agente quando crei un nuovo cluster o quando aggiorni un cluster esistente.

Abilita Sandbox 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 Scegli una modalità operativa GKE.

Autopilot

Per creare un nuovo cluster GKE Autopilot con Sandbox agente 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 Sandbox agente abilitato, devi creare il cluster, aggiungere un pool di nodi con gVisor abilitato e poi abilitare la funzionalità Sandbox agente. Per ridurre i costi, ti consigliamo di creare un cluster di zona con un singolo 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

    La LOCATION deve essere la stessa zona utilizzata durante la creazione del cluster.

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

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

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

Per abilitare Sandbox agente su un cluster esistente, sul cluster deve essere in esecuzione 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, Sandbox agente 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 agente:

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

Verifica la configurazione

Puoi verificare se la funzionalità Sandbox 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à è stata abilitata correttamente, il comando restituisce True.

Requisiti di deployment di Sandbox 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 ammissione di convalida (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 essere destinato a 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.
  • Volumi HostPath.
  • Funzionalità aggiunte (capabilities.add).
  • Impostazioni hostPort.
  • Sysctl personalizzati.
  • Volumi proiettati per token o certificati del account di servizio.

Esegui il deployment di un ambiente in sandbox

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

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

SandboxTemplate funge da progetto riutilizzabile. SandboxWarmPool consente di garantire che un numero specificato di pod pre-riscaldati sia sempre in esecuzione e pronto per essere richiesto. L'utilizzo di questa risorsa cliente riduce al minimo la latenza di avvio.

Per eseguire il deployment di un ambiente in sandbox creando SandboxTemplate e SandboxWarmPool, segui questi 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 il seguente contenuto:

    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 una sandbox dal modello creando un SandboxClaim, segui questi passaggi:

  1. Crea un file denominato sandbox-claim.yaml con il seguente contenuto:

    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 una sandbox direttamente, segui questi passaggi:

  1. Crea un file denominato sandbox.yaml con il seguente contenuto:

    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

Disabilita Sandbox agente

Per disabilitare la funzionalità Sandbox 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 Google Cloud account 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