Agent Sandbox in GKE aktivieren

In diesem Dokument wird beschrieben, wie Sie die Funktion „Agent Sandbox“ in einem Google Kubernetes Engine-Cluster (GKE) aktivieren. Außerdem wird erläutert, wie Sie eine Sandbox-Umgebung im Cluster erstellen, um nicht vertrauenswürdigen Code sicher auszuführen.

Eine Übersicht darüber, wie die Agent Sandbox-Funktion nicht vertrauenswürdigen, KI-generierten Code isoliert, finden Sie unter GKE Agent Sandbox.

Kosten

Agent Sandbox wird in GKE ohne zusätzliche Kosten angeboten. Die GKE-Preise gelten für die von Ihnen erstellten Ressourcen.

Um unnötige Gebühren zu vermeiden, deaktivieren Sie GKE oder löschen Sie das Projekt, nachdem Sie dieses Dokument durchgearbeitet haben.

Hinweis

1. Wählen Sie in der Cloud de Confiance Console auf der Seite für die Projektauswahl ein Cloud de Confiance -Projekt aus oder erstellen Sie eines.

   Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

   • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
   • Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

   Zur Projektauswahl

2. Prüfen Sie, ob die Abrechnung für Ihr Cloud de Confiance Projekt aktiviert ist.

3. Aktivieren Sie die Artifact Registry API und die Google Kubernetes Engine API, falls noch nicht geschehen.

   Rollen, die zum Aktivieren von APIs erforderlich sind

   Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

   APIs aktivieren

4. Aktivieren Sie Cloud Shell in der Cloud de Confiance Console.

   Cloud Shell aktivieren

5. Ihr Cluster muss die GKE-Version 1.36.3-gke.1767000 oder höher ausführen (unterstützt die v1beta1 API).

Umgebungsvariablen definieren

Um die Befehle, die Sie in diesem Dokument ausführen, zu vereinfachen, können Sie Umgebungsvariablen in Cloud Shell festlegen. Definieren Sie in Cloud Shell die folgenden nützlichen Umgebungsvariablen, indem Sie die folgenden Befehle ausführen:

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"

Hier eine Erklärung dieser Umgebungsvariablen:

• PROJECT_ID: die ID Ihres aktuellen Cloud de Confiance by S3NS -Projekts. Durch das Definieren dieser Variablen wird sichergestellt, dass alle Ressourcen, z. B. Ihr GKE-Cluster, im richtigen Projekt erstellt werden.
• CLUSTER_NAME: der Name Ihres GKE-Cluster, z. B. agent-sandbox-cluster.
• LOCATION: Die Cloud de Confiance by S3NS Region oder Zone, in der Ihr GKE-Cluster erstellt wird. Legen Sie dies auf die Region (z. B. us-central1) fest, wenn Sie einen Autopilot-Cluster erstellen, oder auf die Zone (z. B. us-central1-a), wenn Sie einen Standardcluster erstellen.
• CLUSTER_VERSION: die Version von GKE, die auf Ihrem Cluster ausgeführt wird (1.36.3-gke.1767000 oder höher).
• NODE_POOL_NAME: der Name des Knotenpools, in dem Sandbox-Arbeitslasten ausgeführt werden, z. B. agent-sandbox-pool. Diese Variable ist nur erforderlich, wenn Sie einen GKE Standard-Cluster erstellen.
• MACHINE_TYPE: der Maschinentyp der Knoten in Ihrem Knotenpool, z. B. e2-standard-2. Weitere Informationen zu den verschiedenen Maschinenserien und zur Auswahl zwischen verschiedenen Optionen finden Sie im Leitfaden zu Ressourcen und Vergleichen für Maschinenfamilien. Diese Variable ist nur erforderlich, wenn Sie einen GKE-Standardcluster erstellen.

Agent Sandbox aktivieren

Sie können die Agent Sandbox-Funktion aktivieren, wenn Sie einen neuen Cluster erstellen oder einen vorhandenen Cluster aktualisieren.

Agent-Sandbox beim Erstellen eines neuen GKE-Cluster aktivieren

Für eine vollständig verwaltete Kubernetes-Umgebung empfehlen wir die Verwendung eines Autopilot-Clusters. Informationen zum Auswählen des GKE-Betriebsmodus, der für Ihre Arbeitslasten am besten geeignet ist, finden Sie unter GKE-Betriebsmodus auswählen.

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

Agent-Sandbox beim Aktualisieren eines vorhandenen GKE-Cluster aktivieren

Wenn Sie die Agent Sandbox auf einem vorhandenen Cluster aktivieren möchten, muss auf dem Cluster Version 1.36.3-gke.1767000 oder höher ausgeführt werden, die die v1beta1 API unterstützt.

Achten Sie darauf, dass die Umgebungsvariable LOCATION auf die Region oder Zone festgelegt ist, in der sich Ihr vorhandener Cluster befindet.

1. Wenn Sie einen GKE Standard-Cluster verwenden, basiert Agent Sandbox auf gVisor. Wenn Ihr Standardcluster keinen Knotenpool mit aktiviertem gVisor hat, müssen Sie zuerst einen erstellen:

   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. Aktualisieren Sie den Cluster, um das Agent-Sandbox-Feature zu aktivieren:

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

Konfiguration prüfen

Sie können prüfen, ob die Agent Sandbox-Funktion aktiviert ist, indem Sie die Clusterbeschreibung ansehen.

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

Wenn Sie einen Autopilot-Cluster erstellt haben, ist der Standort die Region (z. B. us-central1). Wenn Sie einen Standardcluster erstellt haben, ist der Standort die Zone (z. B. us-central1-a).

Wenn die Funktion erfolgreich aktiviert wurde, gibt der Befehl True zurück.

Anforderungen für die Bereitstellung der Agent Sandbox

Damit Sie eine Arbeitslast wie Sandbox oder SandboxTemplate erfolgreich bereitstellen können, muss Ihr YAML-Manifest bestimmte Sicherheits- und Konfigurationseinstellungen enthalten. GKE erzwingt diese Anforderungen mithilfe einer Validating Admission Policy (VAP). Wenn diese Anforderungen nicht erfüllt sind, lehnt der Admission Controller die Bereitstellung ab.

Erforderliche Konfiguration

Ihr Bereitstellungsmanifest muss die folgenden Einstellungen enthalten:

• runtimeClassName: gvisor: sorgt dafür, dass der Pod in einer gVisor-Sandbox ausgeführt wird.
• automountServiceAccountToken: false: verhindert, dass das Standarddienstkonto-Token automatisch im Pod bereitgestellt wird.
• securityContext.runAsNonRoot: true: sorgt dafür, dass der Container nicht als Root-Nutzer ausgeführt wird.
• securityContext.capabilities.drop: ["ALL"]: Alle Linux-Funktionen werden aus dem Container entfernt.
• resources.limits: Sie müssen CPU- und Arbeitsspeicherlimits angeben, um potenzielle DoS-Szenarien (Denial of Service) zu verhindern.
• nodeSelector: Muss auf sandbox.gke.io/runtime: gvisor ausgerichtet sein.
• tolerations: muss eine Toleranz für die Markierung sandbox.gke.io/runtime=gvisor:NoSchedule enthalten.

Unzulässige Konfiguration

Ihr Bereitstellungsmanifest darf Folgendes nicht enthalten:

• hostNetwork: true, hostPID: true oder hostIPC: true.
• privileged: true in Bezug auf die Containersicherheit.
• HostPath Bände.
• Es wurden Funktionen hinzugefügt (capabilities.add).
• hostPort-Einstellungen.
• Benutzerdefinierte Sysctls.
• Voraussichtliche Mengen für Dienstkonto-Tokens oder ‑Zertifikate.

Sandbox-Umgebung bereitstellen

Wir empfehlen, eine Sandbox-Umgebung bereitzustellen, indem Sie ein SandboxTemplate definieren und vorgewärmte Instanzen mit einem SandboxWarmPool bereithalten. Anschließend können Sie mit einem SandboxClaim eine Instanz aus diesem Warm-Knotenpool anfordern. Alternativ können Sie eine Sandbox direkt erstellen. Bei diesem Ansatz werden jedoch keine Warmpools unterstützt.

SandboxTemplate, SandboxWarmPool, SandboxClaim und Sandbox sind benutzerdefinierte Kubernetes-Ressourcen.

Empfohlen: SandboxTemplate und SandboxWarmPool erstellen

Das SandboxTemplate dient als wiederverwendbarer Entwurf. Der SandboxWarmPool sorgt dafür, dass immer eine bestimmte Anzahl von vorgewärmten Pods ausgeführt wird und bereit ist, in Anspruch genommen zu werden. Durch die Verwendung dieser benutzerdefinierten Ressource wird die Startlatenz minimiert.

Führen Sie die folgenden Schritte aus, um eine Sandbox-Umgebung bereitzustellen, indem Sie das SandboxTemplate und den SandboxWarmPool erstellen:

1. Erstellen Sie in Cloud Shell eine Datei namens sandbox-template.yaml mit folgendem Inhalt:

   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. Wenden Sie das SandboxTemplate-Manifest an:

   kubectl apply -f sandbox-template.yaml
   

3. Erstellen Sie eine Datei mit dem Namen sandbox-warmpool.yaml und dem folgendem Inhalt:

   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. Wenden Sie das SandboxWarmPool-Manifest an:

   kubectl apply -f sandbox-warmpool.yaml
   

Sandbox-Anspruch erstellen

Mit SandboxClaim wird eine Sandbox aus dem Warm-Pool angefordert. Da Sie einen Warmpool erstellt haben, wird für die erstellte Sandbox ein laufender Pod aus dem Pool übernommen, anstatt einen neuen Pod zu starten.

So fordern Sie eine Sandbox aus dem Warm Pool an, indem Sie eine SandboxClaim erstellen:

1. Erstellen Sie eine Datei mit dem Namen sandbox-claim.yaml und dem folgendem Inhalt:

   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. Wenden Sie das SandboxClaim-Manifest an:

   kubectl apply -f sandbox-claim.yaml
   

3. Prüfen Sie, ob die Sandbox, die Anspruchsart und der Warm-Pool bereit sind:

   kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
   

Alternative: Sandbox direkt erstellen

Wenn Sie die schnellen Startzeiten von Warm Pools nicht benötigen, können Sie eine Sandbox direkt ohne Vorlagen bereitstellen.

So stellen Sie eine Sandbox-Umgebung bereit, indem Sie direkt eine Sandbox erstellen:

1. Erstellen Sie eine Datei mit dem Namen sandbox.yaml und dem folgendem Inhalt:

   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. Wenden Sie das Sandbox-Manifest an:

   kubectl apply -f sandbox.yaml
   

3. Prüfen Sie, ob die Sandbox ausgeführt wird:

   kubectl get sandbox
   

Agent-Sandbox von v1alpha1 zu v1beta1 migrieren

Wenn Ihr Cluster mit einer früheren Version von Agent Sandbox mit v1alpha1-benutzerdefinierten Ressourcen bereitgestellt wurde, können Sie ein Upgrade auf GKE-Version 1.36.3-gke.1767000 oder höher mit nahezu null Ausfallzeiten der Arbeitslast durchführen.

Hinweis:Dieses Migrationsverfahren gilt für Cluster, die die verwaltete GKE Agent Sandbox-Funktion (--enable-agent-sandbox) verwenden. Wenn Sie Agent Sandbox mit Open-Source-Manifesten bereitgestellt haben, lesen Sie die Upstream-Migrationsanleitung.

Wichtige API-Unterschiede zwischen v1alpha1 und v1beta1

Mit dem Migrationstool migrieren

Wenn Sie automatisch Shadow-Warmpools erstellen und den Speicher neu speichern möchten, verwenden Sie das kanonische Migrationsskript aus dem Agent Sandbox-Repository.

Laden Sie das Skript herunter und bereiten Sie es vor:

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

Detaillierte Migrationsanleitung

Wenn Sie einen vorhandenen Cluster mit nahezu null Ausfallzeiten für Arbeitslasten migrieren möchten, führen Sie die folgenden drei Phasen in der angegebenen Reihenfolge aus:

Phase 1: Bootstrap-Phase vor dem Upgrade

1. Vorhandene Ressourcen sichern:Speichern Sie eine YAML-Sicherung Ihrer deklarativen Agent Sandbox-Ressourcen (sandboxtemplates, sandboxwarmpools und sandboxclaims):

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

2. Sicherheitskonformität der Vorlage prüfen: Achten Sie darauf, dass vorhandene SandboxTemplate-Ressourcen die Bereitstellungsanforderungen für die Agent Sandbox erfüllen. Während der Speichermigration in Phase 3 lehnt der Zulassungscontroller Aktualisierungen von Vorlagen ab, die nicht diesen Sicherheitsrichtlinien entsprechen.

3. Sehen Sie sich eine Vorschau der Schattenpools an, die erstellt werden sollen:

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

4. Führen Sie die Bootstrap-Phase aus:

   ./migrate.sh --phase=bootstrap
   

5. Prüfen Sie die erstellten Schattenpools:

   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"
   

Phase 2: GKE-Steuerungsebene aktualisieren

Aktualisieren Sie die GKE-Steuerungsebene auf Version 1.36.3-gke.1767000 oder höher:

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

Beachten Sie während der Einführung der Steuerungsebene Folgendes:

• Bei Pods kommt es nicht zu Neustarts oder Ausfallzeiten.
• Der neue Controller und der /convert-Webhook-Endpunkt werden auf der Steuerungsebene bereitgestellt.

Phase 3: Speichermigration nach dem Upgrade

Nach Abschluss des Upgrades der Steuerungsebene aktualisieren Sie Ihre Anmeldedaten und überschreiben Sie die gespeicherten etcd-Objekte, indem Sie die Speichermigrationsphase ausführen:

./migrate.sh --phase=migrate

Checkliste für die Überprüfung nach der Migration

Wenn in einer CustomResourceDefinition nach Abschluss der Migrationsphase weiterhin ["v1alpha1", "v1beta1"] in .status.storedVersions aufgeführt ist, ist dies das erwartete Kubernetes-Verhalten. Das Migrationsskript schreibt alle vorhandenen Datensätze in v1beta1 in etcd um, aber Kubernetes entfernt veraltete Versionen nicht automatisch aus der Liste status.storedVersions.

Nachdem Sie bestätigt haben, dass alle Ressourcen migriert wurden, können Sie v1alpha1 optional aus den gespeicherten Versionen entfernen:

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

Probleme bei der Migration beheben

Wenn nach dem Upgrade der Steuerungsebene oder der Speichermigration Probleme auftreten, beheben Sie diese, anstatt zu versuchen, ein Downgrade der Steuerungsebene durchzuführen:

• Anspruch hängt in WarmPoolNotFound fest:

  • Wenn ein v1alpha1-Anspruch für einen Kaltstart ohne Ausführung von ./migrate.sh --phase=bootstrap aktualisiert wurde, erstellen Sie den fehlenden Shadow-Warmpool manuell:

    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
    

  • Wenn in einem Anspruch ein bestimmter Warmpool angegeben ist, der nicht mehr vorhanden ist, erstellen Sie die fehlende SandboxWarmPool-Ressource mit diesem Namen oder aktualisieren Sie spec.warmPoolRef.name im Anspruch, damit auf einen vorhandenen Warmpool verwiesen wird.

• Anspruchsbedingung Ready=False:Führen Sie kubectl describe sandboxclaim aus, um die Ereignisse im Anspruch zu prüfen. Prüfen Sie, ob die referenzierte SandboxTemplate alle Anforderungen für die Bereitstellung der Agent Sandbox erfüllt, und wenden Sie die Vorlage bei Bedarf noch einmal an.

• Konvertierungs- oder Controllerfehler:Prüfen Sie, ob der Lease für die Wahl des Leaders der Steuerungsebene aktiv ist. Führen Sie dazu kubectl get leases -n gke-managed-agentsandbox aus. Wenn die Probleme weiterhin bestehen, wenden Sie sich an Cloud Customer Care.

Agent Sandbox deaktivieren

Verwenden Sie zum Deaktivieren der Funktion „Agent Sandbox“ den Befehl gcloud beta container clusters update mit dem Flag --no-enable-agent-sandbox.

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

Wenn Sie einen Autopilot-Cluster erstellt haben, ist der Standort die Region (z. B. us-central1). Wenn Sie einen Standardcluster erstellt haben, ist der Standort die Zone (z. B. us-central1-a).

Ressourcen bereinigen

Löschen Sie den erstellten GKE-Cluster, um Gebühren für Ihr Cloud de Confiance by S3NS -Konto zu vermeiden.

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

Wenn Sie einen Autopilot-Cluster erstellt haben, ist der Standort die Region (z. B. us-central1). Wenn Sie einen Standardcluster erstellt haben, ist der Standort die Zone (z. B. us-central1-a).

Nächste Schritte

• Informationen zum Speichern und Wiederherstellen von Agent Sandbox-Umgebungen mit Pod-Snapshots
• Weitere Informationen zur zugrunde liegenden Technologie der Agent Sandbox
• Weitere Informationen zur GKE-Sicherheit
• Open-Source-Projekt „Agent Sandbox“ auf GitHub
• Open-Source-Kata-Container mit Agent Sandbox verwenden Kata Containers ist kein Cloud de Confiance -Produkt. Wenn Sie diese Software installieren und verwenden, sind Sie für die Verwaltung und Fehlerbehebung verantwortlich. Der Support und die SLAs von Google gelten nicht für Kata Containers.