In diesem Dokument wird beschrieben, wie Sie das Feature „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 das Feature „Agent Sandbox“ nicht vertrauenswürdigen von KI generierten Code isoliert, finden Sie unter Informationen zu GKE Agent Sandbox.
Kosten
Agent Sandbox wird in GKE ohne zusätzliche Kosten angeboten. Für die von Ihnen erstellten Ressourcen gelten die GKE-Preise.
Deaktivieren Sie GKE oder löschen Sie das Projekt, nachdem Sie dieses Dokument durchgearbeitet haben, um unnötige Kosten zu vermeiden.
Hinweis
-
Wählen Sie in der Google Cloud Console auf der Seite für die Projektauswahl ein Projekt von aus oder erstellen Sie eines Google Cloud .
Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts
- Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges 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 dieresourcemanager.projects.createBerechtigung enthält. Informationen zum Zuweisen von Rollen.
-
Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.
Aktivieren Sie die Artifact Registry API und die Google Kubernetes Engine API.
Erforderliche Rollen zum Aktivieren von APIs
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.-
Aktivieren Sie Cloud Shell in der Google Cloud Console.
- Prüfen Sie, ob auf Ihrem Cluster die GKE-Version 1.36.3-gke.1767000 oder höher ausgeführt wird (unterstützt die
v1beta1-API).
Umgebungsvariablen definieren
Um die Befehle zu vereinfachen, die Sie in diesem Dokument ausführen, 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 Erläuterung dieser Umgebungsvariablen:
PROJECT_ID: die ID Ihres aktuellen Google Cloud 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 Google Cloud Region oder Zone, in der Ihr GKE Cluster erstellt wird. Legen Sie diese auf die Region fest (z. B.us-central1), wenn Sie einen Autopilot-Cluster erstellen, oder auf die Zone (z. B.us-central1-a), wenn Sie einen Standard-Cluster erstellen.CLUSTER_VERSION: die Version von GKE, die auf Ihrem Cluster ausgeführt wird (1.36.3-gke.1767000oder 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 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 Standard-Cluster erstellen.
Agent Sandbox aktivieren
Sie können das Feature „Agent Sandbox“ 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.
Autopilot
Wenn Sie einen neuen GKE Autopilot-Cluster mit aktivierter Agent Sandbox erstellen möchten, fügen Sie das Flag --enable-agent-sandbox ein:
gcloud beta container clusters create-auto ${CLUSTER_NAME} \
--location=${LOCATION} \
--cluster-version=${CLUSTER_VERSION} \
--enable-agent-sandbox
Achten Sie bei einem Autopilot-Cluster darauf, dass die Umgebungsvariable LOCATION auf eine Region festgelegt ist (z. B. us-central1).
Standard
Wenn Sie einen neuen GKE Standard-Cluster mit aktivierter Agent Sandbox erstellen möchten, müssen Sie den Cluster erstellen, einen Knotenpool mit aktiviertem gVisor hinzufügen und dann das Feature „Agent Sandbox“ aktivieren. Um Kosten zu sparen, empfehlen wir, einen zonalen Cluster mit einem einzelnen Knoten pro Pool zu erstellen:
Erstellen Sie den Cluster:
gcloud beta container clusters create ${CLUSTER_NAME} \ --location=${LOCATION} \ --num-nodes=1 \ --cluster-version=${CLUSTER_VERSION}Achten Sie bei diesem Standard-Cluster darauf, dass die Umgebungsvariable
LOCATIONauf eine Zone festgelegt ist (z. B.us-central1-a).Erstellen Sie einen separaten Knotenpool mit aktiviertem gVisor:
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=gvisorDie
LOCATIONmuss dieselbe Zone sein, die Sie beim Erstellen des Clusters verwendet haben.Aktualisieren Sie den Cluster, um das Feature „Agent Sandbox“ zu aktivieren:
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
Agent Sandbox beim Aktualisieren eines vorhandenen GKE-Cluster aktivieren
Wenn Sie Agent Sandbox in einem vorhandenen Cluster aktivieren möchten, muss auf dem Cluster die 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.
Wenn Sie einen GKE Standard-Cluster verwenden, basiert Agent Sandbox auf gVisor. Wenn Ihr Standard-Cluster 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=gvisorAktualisieren Sie den Cluster, um das Feature „Agent Sandbox“ zu aktivieren:
gcloud beta container clusters update ${CLUSTER_NAME} \ --location=${LOCATION} \ --enable-agent-sandbox
Konfiguration prüfen
Sie können prüfen, ob das Feature „Agent Sandbox“ aktiviert ist, indem Sie die Clusterbeschreibung untersuchen.
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 Standard-Cluster erstellt haben, ist der Standort die Zone (z. B. us-central1-a).
Wenn das Feature erfolgreich aktiviert wurde, gibt der Befehl True zurück.
Anforderungen für die Bereitstellung von Agent Sandbox
Damit Sie eine Arbeitslast wie Sandbox oder SandboxTemplate,
Ihr YAML-Manifest muss bestimmte Sicherheits- und Konfigurationseinstellungen enthalten.
GKE erzwingt diese Anforderungen mithilfe einer Validating Admission Policy (VAP). Wenn diese Anforderungen nicht erfüllt sind, lehnt der Zulassungscontroller 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 in den Pod eingebunden wird.securityContext.runAsNonRoot: true: sorgt dafür, dass der Container nicht als Root-Nutzer ausgeführt wird.securityContext.capabilities.drop: ["ALL"]: entfernt alle Linux-Funktionen aus dem Container.resources.limits: Sie müssen CPU- und Arbeitsspeicherlimits angeben, um potenzielle Denial-of-Service-Szenarien (DoS) zu verhindern.nodeSelector: muss aufsandbox.gke.io/runtime: gvisorausgerichtet sein.tolerations: muss eine Toleranz für die Markierungsandbox.gke.io/runtime=gvisor:NoScheduleenthalten.
Verbotene Konfiguration
Ihr Bereitstellungsmanifest darf Folgendes nicht enthalten:
hostNetwork: true,hostPID: trueoderhostIPC: true.privileged: truein Container-Sicherheitskontexten.HostPath-Volumes.- Hinzugefügte Funktionen (
capabilities.add). hostPort-Einstellungen.- Benutzerdefinierte Sysctls.
- Projizierte Volumes für Dienstkonto-Tokens oder -Zertifikate.
Sandbox-Umgebung bereitstellen
Wir empfehlen, eine Sandbox-Umgebung bereitzustellen, indem Sie eine SandboxTemplate definieren und vorgewärmte Instanzen mit einem SandboxWarmPool bereithalten. Anschließend können Sie mit einem SandboxClaim eine Instanz aus diesem vorgewärmten Knotenpool anfordern. Alternativ können Sie direkt eine Sandbox erstellen. Dieser Ansatz unterstützt jedoch keine vorgewärmten Pools.
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 vorgewärmter Pods ausgeführt wird und angefordert werden kann. Durch die Verwendung dieser benutzerdefinierten Ressource wird die Startlatenz minimiert.
So stellen Sie eine Sandbox-Umgebung bereit, indem Sie das SandboxTemplate und den SandboxWarmPool erstellen:
Erstellen Sie in Cloud Shell eine Datei mit dem Namen
sandbox-template.yamlund dem folgenden 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: OnFailureWenden Sie das
SandboxTemplate-Manifest an:kubectl apply -f sandbox-template.yamlErstellen Sie eine Datei mit dem Namen
sandbox-warmpool.yamlund dem folgenden 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-templateWenden Sie das
SandboxWarmPool-Manifest an:kubectl apply -f sandbox-warmpool.yaml
SandboxClaim erstellen
Mit dem SandboxClaim wird eine Sandbox aus dem vorgewärmten Pool angefordert. Da Sie einen vorgewärmten Pool erstellt haben, übernimmt die erstellte Sandbox einen ausgeführten Pod aus dem Pool, anstatt einen neuen Pod zu starten.
So fordern Sie eine Sandbox aus dem vorgewärmten Pool an, indem Sie einen SandboxClaim erstellen:
Erstellen Sie eine Datei mit dem Namen
sandbox-claim.yamlund dem folgenden 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-warmpoolWenden Sie das
SandboxClaim-Manifest an:kubectl apply -f sandbox-claim.yamlPrüfen Sie, ob die Sandbox, der Anspruch und der vorgewärmte Pool bereit sind:
kubectl get sandboxwarmpool,sandboxclaim,sandbox,pod
Alternative: Sandbox direkt erstellen
Wenn Sie die schnellen Startzeiten, die durch vorgewärmte Pools bereitgestellt werden, nicht benötigen, können Sie eine Sandbox direkt bereitstellen, ohne Vorlagen zu verwenden.
So stellen Sie eine Sandbox-Umgebung bereit, indem Sie direkt eine Sandbox erstellen:
Erstellen Sie eine Datei mit dem Namen
sandbox.yamlund dem folgenden 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" # RequiredWenden Sie das
Sandbox-Manifest an:kubectl apply -f sandbox.yamlPrü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 bereitgestellt wurde, indem Sie benutzerdefinierte v1alpha1-Ressourcen verwendet haben, können Sie ein Upgrade auf die GKE-Version 1.36.3-gke.1767000 oder höher mit nahezu keiner Ausfallzeit der Arbeitslast durchführen.
Hinweis: Dieses Migrationsverfahren gilt für Cluster, die das verwaltete GKE Agent Sandbox-Feature verwenden (
--enable-agent-sandbox). Wenn Sie Agent Sandbox mit Open-Source-Manifesten bereitgestellt haben, lesen Sie die Migrationsanleitung für Upstream.
Wichtigste API-Unterschiede zwischen v1alpha1 und v1beta1
| Konzept | v1alpha1-Verhalten |
v1beta1-Verhalten |
Auswirkungen der Migration |
|---|---|---|---|
| SandboxClaim-Ziele | Direkte Referenz auf SandboxTemplate ohne vorgewärmten Pool zulässig (Kaltstart). |
Eine Referenz auf einen SandboxWarmPool (spec.warmPoolRef.name) ist erforderlich. |
Kaltstart-Ansprüche müssen einem Schatten-Warmpool zugeordnet werden (replicas: 0). |
| Sandbox-Betriebsmodus | Wird aus Replikaten oder Statusfeldern abgeleitet. | Expliziter Wert für das Feld spec.operatingMode (z. B. Running oder Paused). |
Der Conversion-Webhook ordnet dieses Feld automatisch zu und legt es fest. |
| CRD-Speicherversion | v1alpha1 in etcd gespeichert (storage: true). |
v1beta1 in etcd gespeichert (storage: true). |
Webhook konvertiert dynamisch. Im Schritt nach dem Upgrade werden etcd-Objekte noch einmal gespeichert. |
| Conversion-Webhook | Keine. | Aktiv auf /convert (Port 9447). |
Bidirektionale Konvertierung zwischen v1alpha1 und v1beta1. |
Mit dem Migrationstool migrieren
Verwenden Sie das kanonische Migrationsskript aus dem Agent Sandbox-Repository, um automatisch Schatten-Warmpools zu erstellen und den Speicher noch einmal zu speichern.
Skript herunterladen und vorbereiten:
curl -LO https://raw.githubusercontent.com/kubernetes-sigs/agent-sandbox/v0.5.6/helm/files/migrate.sh
chmod +x migrate.sh
Detaillierte Anleitung für die Migration
Wenn Sie einen vorhandenen Cluster mit nahezu keiner Ausfallzeit der Arbeitslast migrieren möchten, führen Sie die folgenden drei Phasen in der angegebenen Reihenfolge aus:
Phase 1: Bootstrap-Phase vor dem Upgrade
Vorhandene Ressourcen sichern:Speichern Sie eine YAML-Sicherung aller benutzerdefinierten Agent Sandbox-Ressourcen in Ihrem Cluster:
kubectl get sandboxtemplates,sandboxwarmpools,sandboxclaims,sandboxes \ --all-namespaces -o yaml > agent-sandbox-v1alpha1-backup.yamlPrüfen Sie die Vorlagensicherheit: Achten Sie darauf, dass die vorhandenen
SandboxTemplateRessourcen die Anforderungen für die Bereitstellung von Agent Sandbox erfüllen. Während der Speichermigration in Phase 3 lehnt der Zulassungscontroller Aktualisierungen für alle Vorlagen ab, die nicht diesen Sicherheitsrichtlinien entsprechen.Sehen Sie sich eine Vorschau der zu erstellenden Schattenpools an:
./migrate.sh --phase=bootstrap --dry-runFühren Sie die Bootstrap-Phase aus:
./migrate.sh --phase=bootstrapPrü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 treten keine Neustarts oder Ausfallzeiten auf.
- Der neue Controller und der
/convert-Webhook-Endpunkt werden auf der Steuerungsebene bereitgestellt.
Phase 3: Speichermigration nach dem Upgrade
Nachdem das Upgrade der Steuerungsebene abgeschlossen ist, aktualisieren Sie Ihre Anmeldedaten und schreiben Sie die gespeicherten etcd-Objekte neu, indem Sie die Speichermigration ausführen:
./migrate.sh --phase=migrate
Checkliste für die Überprüfung nach der Migration
| Artikel auswählen | Befehl | Erwartetes Ergebnis |
|---|---|---|
| CRD-Speicherversionen | kubectl get crd sandboxes.agents.x-k8s.io sandboxclaims.extensions.agents.x-k8s.io sandboxtemplates.extensions.agents.x-k8s.io sandboxwarmpools.extensions.agents.x-k8s.io -o jsonpath='{range .items[*]}{.metadata.name}{": storedVersions="}{.status.storedVersions}{"\n"}{end}' |
Alle vier CRDs zeigen Folgendes an:storedVersions=["v1beta1"] |
| Pod-Kontinuität | kubectl get pods -n default -o wide |
Status: 1/1 RunningRestarts: 0(gilt für Cluster mit aktiven Sandboxen) |
| Anspruchsbindung | kubectl get sandboxclaims -n default -o yaml |
spec.warmPoolRef.name: shadow-pool-...status.conditions: Ready=True (erfordert, dass die Vorlage den Zulassungsanforderungen entspricht) |
| `v1alpha1`-Kompatibilität | kubectl get sandboxes.v1alpha1.agents.x-k8s.io |
Zeigt eine Warnung zu veralteten Funktionen an und gibt die Ressource zurück |
| Native CRUD-Vorgänge für `v1beta1` | kubectl apply -f sandbox-claim.yaml |
Wird ohne Warnungen angewendet |
Agent Sandbox deaktivieren
Verwenden Sie den Befehl gcloud beta container clusters update mit dem Flag --no-enable-agent-sandbox, um das Feature „Agent Sandbox“ zu deaktivieren.
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 Standard-Cluster erstellt haben, ist der Standort die Zone (z. B. us-central1-a).
Ressourcen bereinigen
Löschen Sie den erstellten GKE-Cluster, damit Ihrem Google Cloud Konto keine Gebühren in Rechnung gestellt werden.
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 Standard-Cluster 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.
- Informationen zur zugrunde liegenden Technologie, die von Agent Sandbox verwendet wird.
- Weitere Informationen zur GKE-Sicherheit.
- Informationen zum Open-Source-Projekt Agent Sandbox auf GitHub.
- Informationen zur Verwendung von Open-Source- Kata Containers mit Agent Sandbox. Kata Containers ist kein Google Cloud 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.