Agent-Sandbox-Umgebungen mit Pod-Snapshots speichern und wiederherstellen

Standard

Dieses Dokument gilt nur für Standardcluster.

In diesem Dokument erfahren Sie, wie Sie GKE-Pod-Snapshots verwenden, um den Status einer laufenden Agent Sandbox-Umgebung zu speichern.

Agent Sandbox bietet eine sichere und isolierte Umgebung für die Ausführung nicht vertrauenswürdigen Codes, z. B. von Large Language Models (LLMs) generierten Codes. Das direkte Ausführen dieser Art von Code in einem Cluster birgt Sicherheitsrisiken, da nicht vertrauenswürdiger Code möglicherweise auf andere Apps oder den zugrunde liegenden Clusterknoten selbst zugreifen oder diese beeinträchtigen kann.

Mit GKE-Pod-Snapshots können Sie den Status von Sandbox-Umgebungen speichern und wiederherstellen. Diese Funktion ist aus folgenden Gründen nützlich:

Schneller Start: Die Startzeit der Sandbox wird verkürzt, indem sie aus einem vorab aufgewärmten Snapshot wiederhergestellt wird.
Lang andauernde Agents: Sie können eine Sandbox, deren Ausführung lange dauert, pausieren und später fortsetzen oder sie auf einen anderen Knoten verschieben, ohne den Fortschritt zu verlieren.
Zustandsorientierte Arbeitslasten: Der Kontext eines KI-Agents, z. B. der Konversationsverlauf oder Zwischenberechnungen, wird beibehalten, indem der Status der Sandbox-Umgebung gespeichert und wiederhergestellt wird.
Reproduzierbarkeit: Erfassen Sie einen bestimmten Zustand und verwenden Sie ihn als Grundlage, um mehrere neue Sandboxes mit demselben initialisierten Zustand zu starten.

Ein Snapshot kann auf zwei Arten ausgelöst werden:

Manueller Trigger:Sie erstellen eine PodSnapshotManualTrigger-Ressource, um den Snapshot auszulösen.
Workload-Trigger:Die Sandboxed-Anwendung selbst signalisiert, wann sie gespeichert werden kann.

In diesem Dokument wird beschrieben, wie Sie einen Snapshot manuell auslösen.

Hinweis:GKE-Pod-Snapshots sind ein Vorschau-Feature.

Hinweise

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Verify that billing is enabled for your Google Cloud project.
Enable the Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM) APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Voraussetzungen

Wenn Sie GKE-Pod-Snapshots verwenden möchten, benötigen Sie einen Cluster im Standardmodus, auf dem die GKE-Version 1.34.1-gke.3084001 oder höher ausgeführt wird. Wir empfehlen, GKE-Version 1.35 oder höher zu verwenden. In GKE-Version 1.34 gibt es ein bekanntes Problem, bei dem das Erstellen von Checkpoints aufgrund von Ein-/Ausgabefehlern im Zusammenhang mit Cloud Storage-Berechtigungsfehlern fehlschlagen kann.

Pod-Snapshots unterstützen keine E2-Maschinentypen. In dieser Anleitung wird daher ein Knotenpool mit N2-Maschinen erstellt.

Wenn Sie GPU-basierte Maschinentypen für die Knoten in Ihrem Knotenpool verwenden möchten, lesen Sie die Einschränkungen und Anforderungen.

Umgebungsvariablen definieren

Um die Befehle, die Sie in diesem Dokument ausführen, zu vereinfachen, können Sie Umgebungsvariablen in Cloud Shell festlegen. In diesen Variablen werden Werte wie die ID Ihres Google Cloud -Projekts, der Name des Cloud Storage-Bucket, in dem Ihre Snapshots gespeichert werden, und der Speicherort Ihres GKE-Cluster gespeichert.

Nachdem Sie diese Variablen definiert haben, können Sie sie in mehreren Befehlen wiederverwenden, indem Sie auf den Variablennamen verweisen (z. B. $CLUSTER_NAME), anstatt Werte jedes Mal neu einzugeben oder zu ersetzen. Dieser Ansatz erleichtert die Nachvollziehbarkeit des Prozesses und verringert das Fehlerrisiko.

Führen Sie die folgenden Befehle aus, um die folgenden nützlichen Umgebungsvariablen in Cloud Shell zu definieren:

export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export GKE_VERSION="1.35.0-gke.1795000"
export AGENT_SANDBOX_VERSION="v0.1.0"
export NODE_POOL_NAME="agent-sandbox-node-pool"
export MACHINE_TYPE="n2-standard-2"
export SNAPSHOTS_BUCKET_NAME="agent-sandbox-snapshots-${PROJECT_ID}"
export SNAPSHOT_NAMESPACE="pod-snapshots-ns"
export SNAPSHOT_KSA_NAME="pod-snapshot-sa"
export SNAPSHOT_FOLDER="my-snapshots"
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

Hier finden Sie 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).
GKE_LOCATION: Die Google Cloud Region, in der Ihr GKE-Cluster erstellt wird, z. B. us-central1.
GKE_VERSION: Die GKE-Cluster- und Knotenversion, die für die Kompatibilität mit Pod-Snapshots erforderlich ist. Für GKE-Pod-Snapshots ist GKE-Version 1.34.1-gke.3084001 oder höher erforderlich.
AGENT_SANDBOX_VERSION: Die Version des Agent Sandbox-Controllers, der in Ihrem Cluster bereitgestellt werden soll.
NODE_POOL_NAME: der Name des Knotenpools, in dem Sandbox-Arbeitslasten ausgeführt werden (z. B. agent-sandbox-node-pool).
MACHINE_TYPE: Der Maschinentyp der Knoten in Ihrem Knotenpool, z. B. n2-standard-2. Pod-Snapshots unterstützen keine E2-Maschinentypen. Wenn Sie GPU-basierte Maschinentypen für die Knoten in Ihrem Knotenpool verwenden möchten, lesen Sie den Abschnitt Einschränkungen und Anforderungen. Weitere Informationen zu den verschiedenen Maschinenserien und zur Auswahl zwischen verschiedenen Optionen finden Sie im Leitfaden zu Ressourcen und Vergleichen für Maschinenfamilien.
SNAPSHOTS_BUCKET_NAME: der Name des Cloud Storage-Bucket, den Sie zum Speichern von Snapshots erstellen.
SNAPSHOT_NAMESPACE: Der Kubernetes-Namespace, in dem sich Ihre Snapshot-Arbeitslast und Ihr Dienstkonto befinden.
SNAPSHOT_KSA_NAME: Der Name des Kubernetes-Dienstkontos, das von Ihrem Arbeitslast zur Authentifizierung verwendet wird.
SNAPSHOT_FOLDER: Das Verzeichnis in Ihrem Cloud Storage-Bucket, in dem Snapshots organisiert werden.
PROJECT_NUMBER: die eindeutige numerische Kennung für Ihr Projekt, die für IAM-Berechtigungsbindungen verwendet wird.

Übersicht über die Konfigurationsschritte

Damit Pod-Snapshots von Agent Sandbox-Umgebungen aktiviert werden können, müssen Sie einige Konfigurationsschritte ausführen. Um diese Schritte nachzuvollziehen, ist es hilfreich, zuerst einige wichtige Konzepte und dann den Snapshot-Prozess zu verstehen:

Wichtige Konzepte

Umgebung:Eine Sandbox-Anwendung wird in einem Kubernetes-Pod auf einem GKE-Clusternknoten ausgeführt.
Identität:Der Pod ist mit einem Kubernetes-Dienstkonto verknüpft und wird in einem speziellen Namespace ausgeführt, den Sie erstellen. Das Kubernetes-Dienstkonto und der Namespace bilden zusammen eine eindeutige Identität, mit der dem Pod sicherer Zugriff auf Google Cloud Ressourcen gewährt wird.
Berechtigungen: Damit Snapshots in Cloud Storage gespeichert werden können, muss der Identität des Pods eine bestimmte IAM-Berechtigung gewährt werden, die es ihr ermöglicht, in einen Cloud Storage-Bucket zu schreiben.

Snapshot-Prozess

Trigger:Ein Snapshot wird entweder manuell (extern) oder von der Sandbox-Arbeitslast selbst initiiert. In diesem Dokument wird ein manueller Trigger veranschaulicht, den Sie durch Erstellen einer PodSnapshotManualTrigger-Ressource initiieren.
Erfassung:GKE erfasst den Ausführungsstatus des Pods, z. B. den Status des Arbeitsspeichers und des Dateisystems des Pods.
Hochladen:Mit den Berechtigungen, die dem Kubernetes-Dienstkonto des Pods gewährt wurden, lädt GKE den erfassten Status als Snapshot-Dateien in den angegebenen Cloud Storage-Bucket hoch.

Weitere Informationen dazu, wie GKE Kubernetes-Dienstkonten und IAM-Rollen für den Zugriff auf Google Cloud Ressourcen verwendet, finden Sie unter Authentifizierung bei Google Cloud APIs über GKE-Arbeitslasten.

Führen Sie die folgende Konfiguration aus, um Pod-Snapshots von Agent Sandbox-Umgebungen zu aktivieren. Zuerst bereiten Sie eine Clusterumgebung vor, indem Sie einen GKE-Cluster mit aktivierter Workload Identity-Föderation für GKE und aktivierten Pod-Snapshots erstellen. Als Nächstes konfigurieren Sie Cloud Storage- und IAM-Richtlinien, um dafür zu sorgen, dass Ihre Snapshots sicher gespeichert werden und Ihre Sandbox die erforderlichen Berechtigungen hat. Schließlich erstellen Sie die Snapshot-Ressourcen, in denen der Speicherort und die Richtlinien für Ihre Sandbox angegeben werden.

In der folgenden Tabelle sind die Konfigurationsschritte zusammengefasst, die Sie ausführen müssen. Jeder Schritt wird in den folgenden Abschnitten erläutert:

Thema	Aufgabe
Cluster einrichten	1. GKE-Cluster erstellen und die Funktionen „Pod-Snapshots“ und „Workload Identity Federation for GKE“ aktivieren 2. Agent-Sandbox bereitstellen:
Speicher und Berechtigungen konfigurieren	1. Cloud Storage-Bucket und verwalteten Ordner erstellen 2. Erstellen Sie die benutzerdefinierte IAM-Rolle. 3. Kubernetes-Namespace und Kubernetes-Dienstkonto (Kubernetes service account, KSA) erstellen 4. IAM-Rolle an das Kubernetes-Dienstkonto binden 5. Berechtigungen für den Snapshot-Controller erteilen
Snapshot-Ressourcen konfigurieren	1. Erstellen`PodSnapshotStorageConfig` 2. `PodSnapshotPolicy` erstellen 3. `SandboxTemplate` erstellen

Clustereinrichtung

Eine Sandbox-Anwendung wird in einem Pod auf einem GKE-Clusternknoten ausgeführt. Sie müssen also eine Clusterumgebung einrichten. In diesem Abschnitt wird beschrieben, wie Sie einen GKE-Cluster erstellen und den Agent Sandbox-Controller bereitstellen.

GKE-Cluster erstellen

Erstellen Sie einen GKE-Standardcluster. Dieser Cluster bietet die Kubernetes-Umgebung, in der Sie einen Snapshot einer Agent Sandbox-Umgebung erstellen. Mit dem folgenden Befehl wird der Cluster erstellt und die Identitätsföderation von Arbeitslasten für GKE sowie die Funktion für Pod-Snapshots werden aktiviert:

Führen Sie den folgenden Befehl aus, um einen Standardcluster mit der Google Cloud CLI zu erstellen:

gcloud beta container clusters create ${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --cluster-version=${GKE_VERSION} \
    --workload-pool=${PROJECT_ID}.svc.id.goog \
    --workload-metadata=GKE_METADATA \
    --num-nodes=1 \
    --enable-pod-snapshots

Mit diesem Befehl wird nicht nur der Cluster erstellt, sondern auch die Identitätsföderation von Arbeitslasten für GKE und die Funktion für Pod-Snapshots im Cluster aktiviert.

Rufen Sie die Anmeldedaten des Clusters ab, damit die kubectl-Befehlszeile eine Verbindung zum Cluster herstellen kann. Mit diesem Befehl wird Ihre Kubernetes-Konfigurationsdatei aktualisiert, die standardmäßig im Verzeichnis ~/.kube/config gespeichert ist. Diese Konfigurationsdatei enthält die Anmeldedaten, die kubectl für die Interaktion mit Ihrem GKE-Cluster benötigt:
```
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}
```
So erstellen Sie einen Knotenpool mit aktiviertem gVisor:
```
gcloud container node-pools create ${NODE_POOL_NAME} \
    --cluster=${CLUSTER_NAME} \
    --location=${GKE_LOCATION} \
    --machine-type=${MACHINE_TYPE} \
    --node-version=${GKE_VERSION} \
    --image-type=cos_containerd \
    --num-nodes=1 \
    --sandbox type=gvisor
```
Dieser Befehl verwendet die folgenden wichtigen Flags:
- --image-type=cos_containerd: Gibt an, dass die Knoten Container-Optimized OS mit containerd verwenden.
- --sandbox type=gvisor: Aktiviert die gVisor-Sandbox-Technologie auf den Knoten, die für die Agent-Sandbox erforderlich ist.

Agent Sandbox Controller in Ihrem Cluster bereitstellen

Sie können den Agent Sandbox-Controller und die erforderlichen Komponenten bereitstellen, indem Sie die offiziellen Release-Manifeste auf Ihren Cluster anwenden. Diese Manifeste sind Konfigurationsdateien, die Kubernetes anweisen, alle erforderlichen Komponenten herunterzuladen, die zum Bereitstellen und Ausführen des Agent Sandbox-Controllers in Ihrem Cluster erforderlich sind.

Führen Sie den folgenden Befehl aus, um die Agent Sandbox in Ihrem GKE-Cluster bereitzustellen:

# Apply the main manifest for the controller and its Custom Resource Definitions (CRDs)
kubectl apply \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/manifest.yaml \
-f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/extensions.yaml

Controller überprüfen

Prüfen Sie nach dem Anwenden der Manifeste, ob der Agent Sandbox-Controller-Pod im Namespace agent-sandbox-system korrekt ausgeführt wird. Durch die Manifeste wurde der Namespace agent-sandbox-system automatisch erstellt, als Sie sie im vorherigen Schritt angewendet haben.

kubectl get pods -n agent-sandbox-system

Warten Sie, bis in der Spalte STATUS für den Pod „Running“ und in der Spalte READY „1/1“ angezeigt wird. Wenn der Pod ordnungsgemäß ausgeführt wird, sieht die Ausgabe in etwa so aus:

NAME                         READY   STATUS    RESTARTS   AGE
agent-sandbox-controller-0      1/1     Running   0          44d

Nachdem der Agent Sandbox-Controller ausgeführt wird, kann er automatisch Sandbox-Umgebungen für alle Sandbox-Ressourcen erstellen und verwalten, die Sie in Ihrem Cluster erstellen.

Speicher und Berechtigungen konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie den für Pod-Snapshots erforderlichen Speicher und die erforderlichen Berechtigungen konfigurieren. Sie erstellen einen Cloud Storage-Bucket und einen verwalteten Ordner zum Speichern der Snapshot-Daten. Anschließend gewähren Sie Ihrer Sandbox und dem Snapshot-Controller die Berechtigungen, die sie für den Zugriff auf diesen Speicher benötigen.

Cloud Storage-Bucket erstellen

Erstellen Sie einen Bucket zum Speichern Ihrer Snapshots. Damit die Erstellung von Snapshots schnell und kostengünstig erfolgt, empfehlen wir, den Bucket mit den folgenden Einstellungen zu erstellen:

Hierarchische Namespaces aktivieren:Mit der Funktion für hierarchische Namespaces wird Ihr Bucket in einer Dateisystemhierarchie anstelle eines flachen Namespace organisiert. Diese Konfiguration ermöglicht einen höheren Lese- und Schreibdurchsatz und beschleunigt somit das Speichern und Wiederherstellen von Snapshots.
Vorläufiges Löschen deaktivieren:Mit der Funktion „Vorläufiges Löschen“ werden Daten geschützt, indem gelöschte Dateien für einen bestimmten Zeitraum aufbewahrt werden. Beim Erstellen von Snapshots werden jedoch während des Uploads viele temporäre Dateien erstellt und gelöscht. Wir empfehlen, das vorläufige Löschen zu deaktivieren, um unnötige Gebühren für die Speicherung dieser temporären Dateien zu vermeiden.

Führen Sie den folgenden Befehl aus, um den Bucket mit diesen Einstellungen zu erstellen:

gcloud storage buckets create "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --uniform-bucket-level-access \
    --enable-hierarchical-namespace \
    --soft-delete-duration=0d \
    --location="${GKE_LOCATION}"

Verwalteten Ordner erstellen

Erstellen Sie einen verwalteten Ordner, um Snapshots in Ihrem Bucket zu organisieren. Mit verwalteten Ordnern können Sie IAM-Berechtigungen auf einen bestimmten Ordner anwenden, anstatt auf den gesamten Bucket. Durch diesen Zugriff auf Ordnerebene kann die Sandbox nur auf ihre eigenen Snapshots zugreifen und diese Snapshots werden von anderen Daten im Bucket isoliert.

Führen Sie den folgenden Befehl aus, um einen verwalteten Ordner zu erstellen:

gcloud storage managed-folders create "gs://${SNAPSHOTS_BUCKET_NAME}/${SNAPSHOT_FOLDER}/"

Dienstkonto und IAM-Rollen konfigurieren

Damit GKE Snapshots sicher speichern kann, benötigt das Kubernetes-Dienstkonto, das von den Pods verwendet wird, in denen Ihre Sandbox-Arbeitslast ausgeführt wird, die Berechtigung, in Ihren Bucket zu schreiben. Sie erteilen diese Berechtigung, indem Sie Google CloudIAM-Rollen an das von den Pods verwendete Kubernetes-Dienstkonto binden. In diesem Abschnitt erfahren Sie, wie Sie eine benutzerdefinierte IAM-Rolle und das Kubernetes-Dienstkonto erstellen und die erforderlichen Berechtigungen konfigurieren.

Erstellen Sie eine benutzerdefinierte IAM-Rolle namens podSnapshotGcsReadWriter, die die Berechtigungen enthält, die zum Schreiben von Snapshot-Daten erforderlich sind:

gcloud iam roles create podSnapshotGcsReadWriter \
    --project="${PROJECT_ID}" \
    --permissions="storage.objects.get,storage.objects.create,storage.objects.delete,storage.folders.create"

Wenn die Rolle erfolgreich erstellt wurde, sieht die Ausgabe so aus:

Created role [podSnapshotGcsReadWriter].
etag: BwZJUfjNbew=
includedPermissions:
- storage.folders.create
- storage.objects.create
- storage.objects.delete
- storage.objects.get
name: projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter
stage: ALPHA
title: podSnapshotGcsReadWriter

Erstellen Sie den Namespace, in dem sich Ihre Sandbox und das zugehörige Dienstkonto befinden:
```
kubectl create namespace "${SNAPSHOT_NAMESPACE}"
```
Erstellen Sie das Kubernetes-Dienstkonto im Namespace, den Sie gerade erstellt haben. Das Kubernetes-Dienstkonto und der Namespace bilden zusammen eine eindeutige Identität, mit der Ihrer Sandbox sicherer Zugriff auf Google Cloud Ressourcen gewährt wird:
```
kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
    --namespace "${SNAPSHOT_NAMESPACE}"
```

Weisen Sie allen Dienstkonten im Namespace die Rolle roles/storage.bucketViewer zu. Mit dieser Rolle können die Konten die Metadaten des Buckets aufrufen, aber nicht die Daten selbst lesen oder schreiben:

gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/namespace/${SNAPSHOT_NAMESPACE}" \
    --role="roles/storage.bucketViewer"

Weisen Sie dem Kubernetes-Dienstkonto für Ihre Sandbox die benutzerdefinierte Rolle podSnapshotGcsReadWriter zu. Durch diese Bindung kann nur dieses bestimmte Konto Daten in den verwalteten Ordner schreiben:

gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \
    --role="projects/${PROJECT_ID}/roles/podSnapshotGcsReadWriter"

Weisen Sie dem Kubernetes-Dienstkonto die Rolle roles/storage.objectUser zu. Diese Rolle ist erforderlich, damit der Pod-Snapshot-Agent Vorgänge für verwaltete Ordner ausführen kann:

gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${PROJECT_ID}.svc.id.goog/subject/ns/${SNAPSHOT_NAMESPACE}/sa/${SNAPSHOT_KSA_NAME}" \
    --role="roles/storage.objectUser"

Berechtigungen für den Snapshot-Controller erteilen

Weisen Sie dem Snapshot-Controller des GKE-Systems die Rolle objectUser zu. Mit dieser Berechtigung kann der Controller den Snapshot-Lebenszyklus verwalten, z. B. Snapshot-Objekte löschen, wenn Sie eine PodSnapshot-Ressource löschen:

gcloud storage buckets add-iam-policy-binding "gs://${SNAPSHOTS_BUCKET_NAME}" \
    --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser"

Snapshot-Ressourcen konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie die Snapshot-Ressourcen für die Arbeitslast der Agent Sandbox konfigurieren.

Snapshot-Speicher und ‑Regeln definieren

Um anzugeben, wo GKE Ihre Snapshots speichert und welche Regeln für den Snapshot-Prozess gelten, erstellen Sie zwei benutzerdefinierte Ressourcen:

PodSnapshotStorageConfig: Mit dieser Ressource wird der Cloud Storage-Bucket und der Ordnerpfad angegeben, in dem GKE Ihre Snapshot-Dateien speichert.
PodSnapshotPolicy: Diese Ressource definiert anhand der Kubernetes-Labels, welche Pods für Snapshots infrage kommen. Außerdem werden die Triggerregeln angegeben, z. B. ob Snapshots manuell oder durch die Sandbox-Arbeitslast initiiert werden.

Führen Sie den folgenden Befehl in Cloud Shell aus, um beide Ressourcen in einem Schritt anzuwenden. Mit dieser Methode können Sie dafür sorgen, dass Ihre Umgebungsvariablen korrekt eingefügt werden:

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1alpha1
kind: PodSnapshotStorageConfig
metadata:
  name: cpu-pssc-gcs
spec:
  snapshotStorageConfig:
    gcs:
      bucket: "${SNAPSHOTS_BUCKET_NAME}"
      path: "${SNAPSHOT_FOLDER}"
EOF

sleep 5

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1alpha1
kind: PodSnapshotPolicy
metadata:
  name: cpu-psp
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  storageConfigName: cpu-pssc-gcs
  selector:
    matchLabels:
      app: agent-sandbox-workload
  triggerConfig:
    type: manual
    postCheckpoint: resume
EOF

Konfiguration prüfen

Nachdem Sie die Konfiguration und Richtlinie für die Snapshot-Speicherung angewendet haben, prüfen Sie, ob die Ressourcen einsatzbereit sind. In diesem Abschnitt erfahren Sie, wie Sie den Status dieser benutzerdefinierten Ressourcen prüfen.

Prüfen Sie den Status der PodSnapshotStorageConfig-Ressource:

kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs \
  --namespace "${SNAPSHOT_NAMESPACE}" -o yaml

Die Ausgabe sollte eine Bedingung mit type: Ready und status: "True" enthalten:

status:
  conditions:
  - lastTransitionTime: "2025-10-31T18:18:02Z"
    message: Valid PodSnapshotStorageConfig
    reason: StorageConfigValid
    status: "True"
    type: Ready

Prüfen Sie den Status der PodSnapshotPolicy-Ressource:

kubectl get podsnapshotpolicies.podsnapshot.gke.io cpu-psp \
  --namespace "${SNAPSHOT_NAMESPACE}" -o yaml

Die Ausgabe sollte eine Bedingung mit type: Ready und status: "True" enthalten. Außerdem sollte angegeben werden, dass die referenzierte PodSnapshotStorageConfig gefunden wurde:

status:
  conditions:
  - lastTransitionTime: "2025-10-31T18:19:47Z"
    message: The referenced PodSnapshotStorageConfig "cpu-pssc-gcs" was found
    reason: StorageConfigValid
    status: "True"
    type: Ready

Sandbox-Vorlage erstellen

Nachdem die Speicherrichtlinien und Berechtigungen eingerichtet sind, erstellen Sie die Ressourcen SandboxTemplate und SandboxClaim. Damit die Momentaufnahme funktioniert, muss die Sandbox mit dem Kubernetes-Dienstkonto ausgeführt werden, das Sie zuvor in diesem Dokument erstellt haben. Die Sandbox muss auch die Labels enthalten, die Sie zuvor in PodSnapshotPolicy angegeben haben.

In diesem Beispiel wird eine Python-App verwendet, die einen inkrementierenden Zähler in die Logs schreibt. Mit diesem Zähler können Sie prüfen, ob der Status erfolgreich gespeichert und später wiederhergestellt wurde.

Wenden Sie das folgende Manifest an, um die Ressourcen SandboxTemplate und SandboxClaim zu erstellen:

kubectl apply -f - <<EOF
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-runtime-template
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  podTemplate:
    metadata:
      labels:
        app: agent-sandbox-workload
    spec:
      serviceAccountName: ${SNAPSHOT_KSA_NAME}
      runtimeClassName: gvisor
      containers:
      - name: my-container
        image: python:3.10-slim
        command: ["python3", "-c"]
        args:
          - |
            import time
            i = 0
            while True:
              print(f"Count: {i}", flush=True)
              i += 1
              time.sleep(1)
---
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-example
  namespace: ${SNAPSHOT_NAMESPACE}
  labels:
    app: agent-sandbox-workload
spec:
  sandboxTemplateRef:
    name: python-runtime-template
EOF

Ihre Sandbox wird jetzt mit der richtigen Identität ausgeführt und kann als Snapshot gespeichert werden.

Snapshot erstellen

In diesem Abschnitt wird beschrieben, wie Sie manuell einen Snapshot Ihrer aktiven Sandbox auslösen. Sie erstellen eine Triggerressource, die auf Ihren Sandbox-Pod ausgerichtet ist, und prüfen dann, ob der Snapshot-Prozess erfolgreich abgeschlossen wurde.

Logs des ursprünglichen Zählers prüfen:Bevor Sie den Snapshot auslösen, sehen Sie sich die Logs der laufenden Sandbox an, um den aktuellen Zählerwert zu ermitteln. Wenn Sie sich die Logs ansehen, erhalten Sie eine Baseline, mit der Sie die Situation nach der Wiederherstellung vergleichen können.
```
kubectl logs python-sandbox-example --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
```
Die Ausgabe zeigt die letzten Zeilen des Zählers, z. B.:
```
Count: 15
Count: 16
Count: 17
```
Achten Sie auf die letzten ausgegebenen „Count“-Werte.

PodSnapshotManualTrigger-Ressource erstellen:Snapshot initiieren:

kubectl apply -f - <<EOF
apiVersion: podsnapshot.gke.io/v1alpha1
kind: PodSnapshotManualTrigger
metadata:
  name: cpu-snapshot-trigger
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  targetPod: python-sandbox-example
EOF

Prüfen Sie, ob der manuelle Trigger erfolgreich war:

kubectl get podsnapshotmanualtriggers.podsnapshot.gke.io \
  --namespace "${SNAPSHOT_NAMESPACE}"

Die Ausgabe sollte den Status Complete anzeigen. Das bedeutet, dass GKE den Snapshot des Ziel-Pods erfolgreich ausgelöst hat:

NAME                   TARGET POD               STATUS     AGE
cpu-snapshot-trigger   python-sandbox-example   Complete   XXs

Weitere Details zum erfassten Status ansehen: Beschreiben Sie den Trigger.

kubectl describe podsnapshotmanualtriggers.podsnapshot.gke.io cpu-snapshot-trigger \
  --namespace "${SNAPSHOT_NAMESPACE}"

Die Ausgabe enthält einen Snapshot Created-Abschnitt mit dem eindeutigen Namen der Snapshot-Dateien, die in Ihrem Bucket gespeichert sind:

Status:
  Conditions:
    Last Transition Time:  2026-01-30T19:11:04Z
    Message:               checkpoint completed successfully
    Reason:                Complete
    Status:                True
    Type:                  Triggered
  Observed Generation:     1
  Snapshot Created:
    Name:  <UNIQUE_SNAPSHOT_NAME>

Aus einem Snapshot wiederherstellen

Nachdem Sie einen Snapshot erstellt haben, können Sie die Sandbox-Umgebung wiederherstellen, um die Ausführung ab dem gespeicherten Status fortzusetzen. Wenn Sie die Sandbox wiederherstellen möchten, erstellen Sie eine neue SandboxClaim, die auf die ursprüngliche SandboxTemplate verweist. Der Pod-Snapshot-Controller identifiziert und stellt automatisch den letzten passenden Snapshot wieder her.

Erstellen Sie eine neue SandboxClaim, um die Sandbox wiederherzustellen:

kubectl apply -f - <<EOF
apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxClaim
metadata:
  name: python-sandbox-from-snapshot
  namespace: ${SNAPSHOT_NAMESPACE}
  labels:
    app: agent-sandbox-workload
spec:
  sandboxTemplateRef:
    name: python-runtime-template
EOF

Prüfen Sie anhand der Logs, ob die Wiederherstellung erfolgt ist. Der Zähler wird ab dem Zeitpunkt fortgesetzt, an dem der Snapshot aufgenommen wurde:
```
kubectl logs python-sandbox-from-snapshot --namespace "${SNAPSHOT_NAMESPACE}"
```
In der Ausgabe sollte zu sehen sein, dass der Zähler fortgesetzt wird, z. B.:
```
Count: 18
Count: 19
Count: 20
Count: 21
```

Bereinigen

Mit den folgenden Schritten vermeiden Sie, dass Ihrem Google Cloud Konto die in diesem Dokument verwendeten Ressourcen in Rechnung gestellt werden:

Löschen Sie die Sandbox-Ansprüche, um alle laufenden Pods zu beenden und dem Agent Sandbox-Controller zu ermöglichen, die Container ordnungsgemäß zu beenden.
```
kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
```

Löschen Sie die Sandbox-Vorlagen und manuellen Trigger, die zum Erstellen von Sandboxes und zum Initiieren von Snapshots verwendet wurden.

# Delete the blueprints
kubectl delete sandboxtemplates --all --namespace "${SNAPSHOT_NAMESPACE}"

# Delete the snapshot initiation objects
kubectl delete podsnapshotmanualtriggers --all --namespace "${SNAPSHOT_NAMESPACE}"

Löschen Sie die Snapshot-Richtlinien, in denen definiert ist, welche Pods in Ihrem Namespace für Snapshots infrage kommen.
```
kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
```
Löschen Sie die Snapshot-Speicherkonfiguration, die die globale Definition Ihres Snapshot-Speicher-Back-Ends ist. Da diese Ressource einen Clusterbereich hat, dürfen Sie kein Namespace-Flag verwenden.
```
kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
```
Löschen Sie den Kubernetes-Namespace, um das Kubernetes-Dienstkonto und alle verbleibenden Metadaten mit Namespace automatisch zu entfernen.
```
kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
```
Löschen Sie den GKE-Cluster, um die zugrunde liegende Infrastruktur und alle mit dem Tutorial verknüpften Knoten zu entfernen.
```
gcloud container clusters delete "${CLUSTER_NAME}" --location="${GKE_LOCATION}" --quiet
```
Löschen Sie den Cloud Storage-Bucket (optional) mit dem rekursiven Befehl zum Entfernen, wenn Sie den Speicher vollständig zurücksetzen möchten. Sie können diesen Schritt überspringen, wenn Sie Ihren korrekt konfigurierten Bucket für zukünftige Tests wiederverwenden möchten.
```
gcloud storage rm --recursive "gs://${SNAPSHOTS_BUCKET_NAME:?Error: SNAPSHOTS_BUCKET_NAME is not set. Please re-define the environment variables you defined earlier.}"
```
Löschen Sie die benutzerdefinierte IAM-Rolle (optional), wenn Sie das Projekt in einen vollständig bereinigten Zustand zurückversetzen möchten. Da IAM-Rollen auch nach dem Löschen des Clusters bestehen bleiben, müssen Sie sie separat löschen.
```
gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
```

Nächste Schritte

Weitere Informationen zu GKE-Pod-Snapshots
Weitere Informationen zum Open-Source-Projekt „Agent Sandbox“ finden Sie auf GitHub.
Informationen zum Isolieren der Ausführung von KI-Code mit Agent Sandbox