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

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

Die Agent Sandbox verbessert die Sicherheit, da sie eine isolierte Umgebung für die Ausführung von nicht vertrauenswürdigem Code bietet, z. B. Code, der von Large Language Models (LLMs) generiert wird. Die direkte Ausführung 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 dass der Fortschritt verloren geht.
  • Zustandsorientierte Arbeitslasten: Der Kontext eines KI-Agents, z. B. der Konversationsverlauf oder Zwischenberechnungen, wird beibehalten, indem der Zustand 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

  1. Wählen Sie in der Google Cloud Console auf der Seite für die Projektauswahl ein Google Cloud -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 für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.

  3. Aktivieren Sie die Google Kubernetes Engine-, Cloud Storage- und Identity and Access Management (IAM)-APIs.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Weitere Informationen zum Zuweisen von Rollen

    APIs aktivieren

  4. Aktivieren Sie Cloud Shell in der Google Cloud Console.

    Cloud Shell aktivieren

Voraussetzungen

Für GKE-Pod-Snapshots ist GKE-Version 1.35.3-gke.1234000 oder höher erforderlich. Sowohl Autopilot- als auch Standardmodi werden unterstützt.

Da für Pod-Snapshots GKE Sandbox erforderlich ist, unterliegt Ihre Umgebung bestimmten Einschränkungen. Pod-Snapshots unterstützen beispielsweise keine E2-Maschinentypen. In diesem Tutorial wird daher ein Knotenpool mit N2-Maschinen erstellt.

Eine vollständige Liste der Einschränkungen, einschließlich Informationen zur Verwendung von GPU-basierten Maschinentypen, finden Sie unter 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 CLUSTER_VERSION="1.35.3-gke.1234000"
export AGENT_SANDBOX_VERSION="v0.4.6"
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.
  • CLUSTER_VERSION: die Version Ihres GKE-Cluster, die mindestens Version 1.35.3-gke.1234000 sein muss.
  • 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

  1. 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.
  2. Erfassung:GKE erfasst den Ausführungsstatus des Pods, z. B. den Status des Arbeitsspeichers und des Dateisystems des Pods.
  3. 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. ErstellenPodSnapshotStorageConfig
2. PodSnapshotPolicy erstellen
3. SandboxTemplate erstellen

Clustereinrichtung

Eine Sandbox-Anwendung wird in einem Pod auf einem GKE-Clusterknoten 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.

Neuen GKE-Cluster erstellen, der die Anforderungen erfüllt

Einen neuen GKE-Cluster mit aktivierten Pod-Snapshots erstellen Für die volle Kompatibilität mit allen Funktionen geben Sie eine Clusterversion ab 1.35.3-gke.1234000 an:

Autopilot

Erstellen Sie einen Autopilot-Cluster mit den erforderlichen Funktionen:

gcloud container clusters create-auto ${CLUSTER_NAME} \
   --cluster-version=${CLUSTER_VERSION} \
   --enable-pod-snapshots \
   --location=${GKE_LOCATION}

Standard

Erstellen Sie einen Standardcluster mit den erforderlichen Funktionen:

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

Erstellen Sie einen Knotenpool mit aktiviertem GKE Sandbox. GKE Sandbox ist eine Containersicherheitsfunktion, die auf dem Open-Source-Projekt gVisor basiert und eine zusätzliche Isolierungsebene zwischen laufenden Anwendungen und dem Hostbetriebssystem bietet:

gcloud container node-pools create ${NODE_POOL_NAME} \
   --cluster ${CLUSTER_NAME} \
   --num-nodes=1 \
   --location=${GKE_LOCATION} \
   --project=${PROJECT_ID} \
   --machine-type=${MACHINE_TYPE} \
   --sandbox type=gvisor

Anmeldedaten abrufen

Rufen Sie die Anmeldedaten des Clusters ab, damit die kubectl-Befehlszeile eine Verbindung zum Cluster herstellen kann:

gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${GKE_LOCATION}

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.

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

  2. Erstellen Sie den Namespace, in dem sich Ihre Sandbox und das zugehörige Dienstkonto befinden:

    kubectl create namespace "${SNAPSHOT_NAMESPACE}"

  3. 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}"

  4. 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"

  5. Weisen Sie dem Kubernetes-Dienstkonto für Ihre Sandbox die benutzerdefinierte Rolle podSnapshotGcsReadWriter zu. Durch diese Bindung kann nur dieses 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"

  6. 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 Ihrer 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 den Sandbox-Arbeitslast ausgelöst 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/v1
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/v1
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.

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

  2. 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 der Snapshot-Prozess 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.

Autopilot

Pod-Snapshots unterstützen keine E2-Maschinentypen. In Autopilot verwendet GKE möglicherweise standardmäßig E2-Knoten. Damit Ihre Arbeitslasten auf kompatibler Hardware ausgeführt werden, sollten Sie eine benutzerdefinierte ComputeClass verwenden, um kompatible Maschinenfamilien zu priorisieren.

  1. Speichern Sie das folgende Manifest als non-e2-class.yaml:

    apiVersion: cloud.google.com/v1
kind: ComputeClass
metadata:
  name: non-e2-class
spec:
  priorities:
  - machineFamily: n2
  - machineFamily: c3
  activeMigration:
    optimizeRulePriority: false
  whenUnsatisfiable: DoNotScaleUp

  2. Wenden Sie das Manifest an:

    kubectl apply -f non-e2-class.yaml

  3. Wenden Sie das folgende Manifest an, um die Ressourcen SandboxTemplate und SandboxClaim zu erstellen. Beachten Sie, dass sich SandboxTemplate auf die ComputeClass bezieht, die Sie gerade mit der Knotenauswahl cloud.google.com/compute-class: non-e2-class erstellt haben.

    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
      nodeSelector:
        cloud.google.com/compute-class: non-e2-class
      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

Standard

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.

  1. 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, können Sie eine Baseline für den Vergleich nach der Wiederherstellung erstellen.

    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.

  2. PodSnapshotManualTrigger-Ressource erstellen:Snapshot initiieren:

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

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

  4. Weitere Details zum erfassten Status ansehen:

    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.

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

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

Ressourcen bereinigen

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

  1. 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}"

  2. 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}"

  3. 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}"

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

  5. Wenn Sie eine ComputeClass für Autopilot erstellt haben, löschen Sie sie.

    kubectl delete computeclass non-e2-class

  6. Löschen Sie den Kubernetes-Namespace, um das Kubernetes-Dienstkonto und alle verbleibenden Metadaten mit Namespace automatisch zu entfernen.

    kubectl delete namespace "${SNAPSHOT_NAMESPACE}"

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

  8. Löschen Sie den Cloud Storage-Bucket (optional) mit dem rekursiven Befehl zum Entfernen, wenn Sie den Speicher vollständig zurücksetzen möchten. Beachten Sie, dass Sie diesen Schritt überspringen können, 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.}"

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