Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Agent Sandbox-Snapshots aus einem Cluster heraus auslösen

Autopilot Standard

In dieser Anleitung wird beschrieben, wie Sie die Snapshot-Funktion von Agent Sandbox in einem Google Kubernetes Engine-Cluster (GKE) bereitstellen und testen. Sie erfahren, wie Sie eine Clientanwendung im Cluster ausführen, um Sandbox-Umgebungen programmatisch zu erstellen, anzuhalten und fortzusetzen.

Weitere Informationen zum Erstellen von Snapshots von Pods finden Sie unter Aus einem Pod-Snapshot wiederherstellen.

Kosten

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

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 die resourcemanager.projects.create Berechtigung enthält. Informationen zum Zuweisen von Rollen.
Hinweis: Wenn Sie die Ressourcen, die Sie in diesem Verfahren erstellen, nicht behalten möchten, erstellen Sie ein Projekt, anstatt ein vorhandenes Projekt auszuwählen. Wenn Sie fertig sind, können Sie das Projekt löschen und dadurch alle mit ihm verknüpften Ressourcen entfernen.

Zur Projektauswahl
Prüfen Sie, ob für Ihr Google Cloud Projekt die Abrechnung aktiviert ist.
Aktivieren Sie die Artifact Registry API und die Kubernetes Engine API.
Erforderliche Rollen zum Aktivieren von APIs
Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) mit der Berechtigung serviceusage.services.enable. Informationen zum Zuweisen von Rollen.
APIs aktivieren

Aktivieren Sie Cloud Shell in der Google Cloud Console.

Cloud Shell aktivieren
Prüfen Sie, ob Sie die Berechtigungen haben, die für diese Anleitung erforderlich sind.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle „Kubernetes Engine-Administrator “ (roles/container.admin) für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Sandboxes benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Beschränkungen

In einem regionalen Cluster können Knoten in verschiedenen Zonen unterschiedliche CPU-Mikroarchitekturen haben. Da in Snapshots der CPU-Status erfasst wird, schlägt die Wiederherstellung eines Snapshots auf einem Knoten mit fehlenden CPU-Funktionen fehl (z. B. mit dem Fehler OCI runtime restore failed: incompatible FeatureSet).

Verwenden Sie die entsprechende Konfiguration für Ihre Umgebung, um dieses Problem zu vermeiden:

Produktion: Damit die Hochverfügbarkeit im gesamten Cluster erhalten bleibt, sollten Sie Arbeitslasten nicht an eine bestimmte Zone anpinnen. Geben Sie stattdessen eine Mindest-CPU-Plattform an, um die Konsistenz der CPU-Funktionen in allen Zonen zu gewährleisten. Weitere Informationen finden Sie unter Mindest-CPU-Plattform auswählen.
Testen: Um die Einrichtung zu vereinfachen und anfängliche Fehler aufgrund von CPU-Inkompatibilitäten zu vermeiden, können Sie im Manifest SandboxTemplate ein Feld nodeSelector verwenden, um den Pod an eine bestimmte Zone anzupinnen, z. B. us-central1-a. Im Beispiel in dieser Anleitung wird diese Testkonfiguration verwendet.

Umgebungsvariablen definieren

Um die Befehle zu vereinfachen, die Sie in dieser Anleitung 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 PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export CLUSTER_NAME="test-snapshot"
export LOCATION="us-central1"
export BUCKET_LOCATION="us"
export MACHINE_TYPE="n2-standard-2"
export REPOSITORY_NAME="agent-sandbox"
export BUCKET_NAME="${PROJECT_ID}_snapshots"
export CLOUDBUILD_BUCKET_NAME="${PROJECT_ID}_cloudbuild"

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 im richtigen Projekt erstellt werden.
PROJECT_NUMBER: die Projektnummer Ihres aktuellen Google Cloud Projekts.
CLUSTER_NAME: der Name Ihres GKE-Cluster, z. B. test-snapshot.
LOCATION: die Google Cloud Region, in der sich Ihr GKE-Cluster und das Artifact Registry-Repository befinden, z. B. us-central1.
BUCKET_LOCATION: der Speicherort Ihrer Cloud Storage-Buckets, z. B. us.
BUCKET_NAME: der Name des Cloud Storage-Bucket, der für Snapshots verwendet wird.
CLOUDBUILD_BUCKET_NAME: der Name des Cloud Storage-Bucket, der für Cloud Build-Logs verwendet wird.
MACHINE_TYPE: der Maschinentyp, der für die Clusterknoten verwendet werden soll, z. B. e2-standard-8.
REPOSITORY_NAME: der Name des Artifact Registry-Repositorys, z. B. agent-sandbox.

Übersicht über die Konfigurationsschritte

Um Pod-Snapshots von Agent Sandbox-Umgebungen in Ihrem Cluster zu aktivieren und zu testen, müssen Sie mehrere Konfigurationsschritte ausführen. Um diese Schritte zu verstehen, ist es hilfreich, zuerst die Komponenten zu kennen, die am gesamten Workflow beteiligt sind.

Schlüsselkomponenten

In dieser Anleitung werden die folgenden beiden Python-Anwendungen verwendet, um den Snapshot-Prozess zu testen:

Clientanwendung: Ein Python-Skript, das in einem Standard-Pod in Ihrem Cluster ausgeführt wird. Diese Anwendung verwaltet den Lebenszyklus der Sandbox: Sie erstellt die Sandbox programmatisch, hält sie an, um einen Snapshot auszulösen, setzt die Sandbox fort und prüft, ob der Status beibehalten wurde. In diesem Tutorial erstellen Sie ein Kubernetes-Dienstkonto mit dem Namen agent-sandbox-client-sa und gewähren ihm RBAC-Berechtigungen, damit der Pod der Clientanwendung Sandbox-benutzerdefinierte Ressourcen und Snapshot-Triggerobjekte mit der Kubernetes API verwalten kann.
Sandbox-Anwendung: Ein Python-Skript, das jede Sekunde einen Zähler erhöht und ausgibt. Diese Anwendung wird sicher in der isolierten Sandbox-Umgebung ausgeführt, um einen sich ändernden Status zu generieren, den die Clientanwendung prüfen kann. In dieser Anleitung erstellen Sie ein dediziertes Kubernetes-Dienstkonto mit dem Namen snapshot-sa und konfigurieren Workload Identity, um den Sandbox-Pod zu autorisieren, Snapshot-Objekte in Cloud Storage sicher zu lesen und zu schreiben.

Konfigurations- und Testprozess

In der folgenden Liste sind die Schritte zusammengefasst, die Sie ausführen müssen, um Ihre Umgebung einzurichten und den Test auszuführen:

Cluster erstellen: Erstellen Sie einen Autopilot- oder Standardcluster mit aktivierten Pod-Snapshots und der Funktion „Agent Sandbox“.
Artifact Registry-Repository erstellen: Erstellen Sie ein Docker-Repository, um das Container-Image für Ihre Clientanwendung zu speichern.
Agent Sandbox installieren: Installieren Sie die Kernkomponenten und Erweiterungen von Agent Sandbox in Ihrem Cluster.
Speicher und Berechtigungen konfigurieren: Erstellen Sie einen Cloud Storage-Bucket und konfigurieren Sie Workload Identity Berechtigungen, damit Snapshots sicher gespeichert werden können.
Pod-Snapshots konfigurieren: Erstellen und anwenden der Snapshot-Speicherkonfiguration, der Snapshot-Richtlinie und der Sandbox Vorlage.
Clientanwendung erstellen: Erstellen Sie das Container-Image für die Clientanwendung und übertragen Sie es per Push an Ihr Artifact Registry Repository.
Testen: Stellen Sie den Pod der Clientanwendung bereit. Dadurch wird die Sandbox erstellt, angehalten, um einen Snapshot zu erstellen, fortgesetzt und geprüft, ob der Status des Zählers erfolgreich wiederhergestellt wurde.

Cluster erstellen

Erstellen Sie einen neuen GKE-Cluster mit aktivierten Pod-Snapshots. Geben Sie den Rapid Release Channel an, um die volle Feature-Kompatibilität zu gewährleisten.

Autopilot

Erstellen Sie einen Autopilot-Cluster mit den erforderlichen Funktionen:

gcloud beta container clusters create-auto ${CLUSTER_NAME} \
   --enable-pod-snapshots \
   --release-channel=rapid \
   --location=${LOCATION}

Standard

Erstellen Sie einen Standardcluster mit den erforderlichen Funktionen:

gcloud beta container clusters create ${CLUSTER_NAME} \
   --enable-pod-snapshots \
   --release-channel=rapid \
   --machine-type=${MACHINE_TYPE} \
   --workload-pool=${PROJECT_ID}.svc.id.goog \
   --workload-metadata=GKE_METADATA \
   --num-nodes=1 \
   --location=${LOCATION}

Erstellen Sie einen Knotenpool mit aktiviertem gVisor:

gcloud container node-pools create gvisor-pool \
   --cluster ${CLUSTER_NAME} \
   --num-nodes=1 \
   --location=${LOCATION} \
   --project=${PROJECT_ID} \
   --sandbox type=gvisor

Artifact Registry-Repository erstellen

Erstellen Sie in Artifact Registry ein Docker-Repository, um das Container-Image für Ihre Clientanwendung zu speichern (die Anwendung, die die Sandbox erstellt und verwaltet):

gcloud artifacts repositories create ${REPOSITORY_NAME} \
   --repository-format=docker \
   --location=${LOCATION} \
   --description="Docker repository for Agent Sandbox"

Agent Sandbox installieren

Installieren Sie die Kernkomponenten und Erweiterungen von Agent Sandbox in Ihrem Cluster (Beispiel mit Version 0.4.6):

# Install the core agent-sandbox components
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.4.6/manifest.yaml

# Install the extensions (e.g., Warm Pools, Claims)
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v0.4.6/extensions.yaml

Speicher und Berechtigungen konfigurieren

Konfigurieren Sie einen Cloud Storage-Bucket zum Speichern von Pod-Snapshots und gewähren Sie die erforderlichen Workload Identity-Berechtigungen für das Dienstkonto snapshot-sa und den GKE-Dienst-Agenten. So können Ihre Sandbox-Arbeitslasten Snapshot-Objekte sicher speichern und abrufen:

Erstellen Sie einen neuen Cloud Storage-Bucket:

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

Erstellen Sie ein Kubernetes-Dienstkonto im Namespace default. Ihre Sandbox-Anwendung (das Python-Zählerskript) verwendet diese Identität, um sich bei externen APIs zu authentifizieren und sicher auf Snapshot-Objekte zuzugreifen, die in Cloud Storage gespeichert sind:
```
kubectl create serviceaccount "snapshot-sa" \
    --namespace "default"
```

Binden Sie die Rolle storage.bucketViewer mit Workload Identity an Ihr Dienstkonto. Mit dieser Rolle kann die Sandbox-Arbeitslast den Bucket-Inhalt auflisten und bestimmte Snapshots finden:

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

Binden Sie die Rolle storage.objectUser mit Workload Identity an Ihr Dienstkonto. Diese Rolle gewährt die Berechtigung, binäre Snapshot-Objekte im Bucket zu lesen, zu speichern und zu löschen:

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

Gewähren Sie dem GKE-Dienst-Agenten Berechtigungen zum Verwalten (Erstellen, Auflisten, Lesen und Löschen) von Snapshot-Objekten im Bucket:

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser" \
    --condition="expression=resource.name.startsWith(\"projects/_/buckets/${BUCKET_NAME}\"),title=restrict_to_bucket,description=Restricts access to one bucket only"

Pod-Snapshots konfigurieren

Erstellen und wenden Sie die Konfigurationsdateien an, um die erforderlichen benutzerdefinierten Kubernetes-Ressourcen zu installieren. Diese Ressourcen definieren, wie der Cluster Pod-Snapshots speichert und verwaltet:

PodSnapshotStorageConfig: gibt den Cloud Storage-Bucket an, der zum Speichern binärer Snapshot-Objekte vorgesehen ist.
PodSnapshotPolicy: definiert, wie Snapshots manuell ausgelöst werden, wie oft sie gruppiert werden und ihre Aufbewahrungsrichtlinien.
SandboxTemplate: definiert den zugrunde liegenden Container, die Knotenauswahl und die Dienstkonten für die Ausführung der isolierten Sandbox-Arbeitslast.

Erstellen Sie eine Datei mit dem Namen test_client/snapshot_storage_config.yaml. Diese Konfiguration gibt den Ziel-Cloud Storage-Bucket an, in dem der Cluster den binären Pod-Snapshot-Status speichert:

apiVersion: podsnapshot.gke.io/v1
kind: PodSnapshotStorageConfig
metadata:
  name: example-pod-snapshot-storage-config
spec:
  snapshotStorageConfig:
    gcs:
      bucket: "$BUCKET_NAME"

Ersetzen Sie den Platzhalter für die Umgebungsvariable in der Konfigurationsdatei:

sed -i "s/\$BUCKET_NAME/$BUCKET_NAME/g" test_client/snapshot_storage_config.yaml

Wenden Sie das Manifest der Speicherkonfiguration an:

kubectl apply -f test_client/snapshot_storage_config.yaml

Warten Sie, bis die Speicherkonfiguration bereit ist:

kubectl wait --for=condition=Ready podsnapshotstorageconfig/example-pod-snapshot-storage-config --timeout=60s

Erstellen Sie eine Datei mit dem Namen test_client/snapshot_policy.yaml. Diese Konfiguration legt eine Aufbewahrungsregel fest, mit der maximal zwei Snapshots für Ihre Sandbox-Arbeitslast aufbewahrt werden. Der Triggertyp ist auf manual festgelegt. So kann die Clientanwendung Snapshots bei Bedarf steuern:

apiVersion: podsnapshot.gke.io/v1
kind: PodSnapshotPolicy
metadata:
  name: example-pod-snapshot-policy
  namespace: default
spec:
  storageConfigName: example-pod-snapshot-storage-config
  selector:
    matchLabels:
      app: agent-sandbox-workload
  triggerConfig:
    type: manual
    postCheckpoint: resume
  snapshotGroupingRules:
    groupByLabelValue:
      labels: ["agents.x-k8s.io/sandbox-name-hash", "tenant-id", "user-id"]
      groupRetentionPolicy:
        maxSnapshotCountPerGroup: 2

Wenden Sie das Manifest der Snapshot-Richtlinie an:

kubectl apply -f test_client/snapshot_policy.yaml

Erstellen Sie eine Datei mit dem Namen test_client/python-counter-template.yaml. Diese Konfiguration definiert den Sandbox-Pod und weist ihm die Dienstkontoidentität snapshot-sa zu. Diese Zuweisung trägt dazu bei, dass die Sandbox sicher ausgeführt wird. In diesem Pod gibt die Sandbox-Anwendung (ein Python-Skript) kontinuierlich einen inkrementierenden Zähler in die Containerlogs aus:

apiVersion: extensions.agents.x-k8s.io/v1alpha1
kind: SandboxTemplate
metadata:
  name: python-counter-template
  namespace: default
spec:
  podTemplate:
    metadata:
      labels:
        app: agent-sandbox-workload
    spec:
      serviceAccountName: snapshot-sa
      runtimeClassName: gvisor
      nodeSelector:
        topology.kubernetes.io/zone: us-central1-a # Pin to a zone to avoid CPU mismatch during restore
      containers:
      - name: python-counter
        image: python:3.13-slim
        command: ["python3", "-c"]
        args:
          - |
            import time
            i = 0
            while True:
              print(f"Count: {i}", flush=True)
              i += 1
              time.sleep(1)

Wenden Sie das Manifest der Sandbox-Vorlage an:

kubectl apply -f test_client/python-counter-template.yaml

Clientanwendung erstellen

Erstellen Sie das Container-Image für die Clientanwendung und laden Sie es in Artifact Registry hoch.

Erstellen Sie eine Datei mit dem Namen test_client/Dockerfile.client. Diese Datei definiert die Python-Laufzeitumgebung und die Abhängigkeiten für die Clientanwendung:

FROM python:3.13-slim

WORKDIR /app

RUN pip install "k8s-agent-sandbox[tracing]==0.4.6"

# Copy test script
COPY client_test.py /app/client_test.py

CMD ["python", "/app/client_test.py"]

Erstellen Sie eine Datei mit dem Namen test_client/client_test.py. Dieses Skript verwaltet den Lebenszyklus der Sandbox und prüft, ob der Status nach dem Erstellen eines Snapshots erfolgreich fortgesetzt wird:

import time
import logging
import re
from kubernetes import config, client
from k8s_agent_sandbox.gke_extensions.snapshots import PodSnapshotSandboxClient

logging.basicConfig(level=logging.INFO)

def get_last_count(pod_name, namespace):
    v1 = client.CoreV1Api()
    try:
        logs = v1.read_namespaced_pod_log(name=pod_name, namespace=namespace)
        counts = re.findall(r"Count: (\d+)", logs)
        if counts:
            return int(counts[-1])
        return None
    except Exception as e:
        logging.error(f"Failed to read logs for pod {pod_name}: {e}")
        return None

def get_current_pod_name(sandbox_id, namespace):
    custom_api = client.CustomObjectsApi()
    try:
        sandbox_cr = custom_api.get_namespaced_custom_object(
            group="agents.x-k8s.io",
            version="v1alpha1",
            namespace=namespace,
            plural="sandboxes",
            name=sandbox_id
        )
        metadata = sandbox_cr.get("metadata", {})
        annotations = metadata.get("annotations", {})
        return annotations.get("agents.x-k8s.io/pod-name")
    except Exception as e:
        logging.error(f"Failed to get sandbox CR: {e}")
        return None

def get_current_count(sandbox_id, namespace="default"):
    pod_name = get_current_pod_name(sandbox_id, namespace)
    if not pod_name:
        logging.error(f"Could not determine pod name for sandbox {sandbox_id}")
        return None
    return get_last_count(pod_name, namespace)

def suspend_sandbox(sandbox):
    logging.info("Pausing sandbox (using snapshots)...")
    try:
        suspend_resp = sandbox.suspend(snapshot_before_suspend=True)
        if suspend_resp.success:
            logging.info("Sandbox paused successfully.")
            if suspend_resp.snapshot_response:
                logging.info(f"Snapshot created: {suspend_resp.snapshot_response.snapshot_uid}")
            return suspend_resp
        else:
            logging.error(f"Failed to pause: {suspend_resp.error_reason}")
            exit(1)
    except Exception as e:
        logging.error(f"Failed to pause sandbox: {e}")
        exit(1)

def resume_sandbox(sandbox):
    logging.info("Resuming sandbox (using snapshots)...")
    try:
        resume_resp = sandbox.resume()
        if resume_resp.success:
            logging.info("Sandbox resumed successfully.")
            if resume_resp.restored_from_snapshot:
                logging.info(f"Restored from snapshot: {resume_resp.snapshot_uid}")
            return resume_resp
        else:
            logging.error(f"Failed to resume: {resume_resp.error_reason}")
            exit(1)
    except Exception as e:
        logging.error(f"Failed to resume sandbox: {e}")
        exit(1)

def verify_continuity(count_before, count_after):
    if count_before is not None and count_after is not None:
        logging.info(f"Verification: Count before={count_before}, Count after={count_after}")
        if count_after >= count_before:
            logging.info("SUCCESS: Sandbox resumed from where it left off (or later).")
        else:
            logging.error("FAIL: Sandbox counter reset or went backwards!")
    else:
        logging.warning("Could not verify counter continuity.")

def main():
    try:
        config.load_incluster_config()
    except config.ConfigException:
        config.load_kube_config()

    client_reg = PodSnapshotSandboxClient()

    logging.info("Creating sandbox...")
    sandbox = client_reg.create_sandbox(template="python-counter-template", namespace="default")
    logging.info(f"Sandbox created with ID: {sandbox.sandbox_id}")

    logging.info("Waiting for sandbox to run...")
    time.sleep(10)

    count_before = get_current_count(sandbox.sandbox_id)
    logging.info(f"Count before suspend: {count_before}")

    suspend_sandbox(sandbox)

    logging.info("Waiting 10 seconds...")
    time.sleep(10)

    resume_sandbox(sandbox)

    logging.info("Waiting for sandbox to be ready again...")
    time.sleep(10)

    count_after = get_current_count(sandbox.sandbox_id)
    logging.info(f"Count after resume: {count_after}")

    verify_continuity(count_before, count_after)

    logging.info("Snapshot test completed successfully.")

if __name__ == "__main__":
    main()

Erstellen Sie das Container-Image des Clients und laden Sie es in Artifact Registry hoch. Wenn in Ihrer Umgebung (z. B. Cloud Shell) Docker installiert ist, können Sie das Image lokal mit Docker erstellen. Wenn Sie in einer Umgebung ohne Docker arbeiten, können Sie Cloud Build verwenden, um das Image remote zu erstellen und per Push zu übertragen:

Docker

Konfigurieren Sie die Docker-Authentifizierung für Artifact Registry:
```
gcloud auth configure-docker "${LOCATION}-docker.pkg.dev"
```

Erstellen Sie das Container-Image des Clients lokal und übertragen Sie es per Push:

docker build -t "${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-client:latest" -f test_client/Dockerfile.client test_client
docker push "${LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY_NAME}/sandbox-client:latest"

Cloud Build

Erstellen Sie eine Datei mit dem Namen test_client/cloudbuild.yaml:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '$LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest', '-f', 'test_client/Dockerfile.client', 'test_client']
images:
- '$LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest'

Ersetzen Sie die Platzhalter für die Umgebungsvariablen in der Konfigurationsdatei:

sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" test_client/cloudbuild.yaml
sed -i "s/\$LOCATION/$LOCATION/g" test_client/cloudbuild.yaml
sed -i "s/\$PROJECT_ID/$PROJECT_ID/g" test_client/cloudbuild.yaml

Gewähren Sie dem Cloud Build-Dienstkonto die erforderlichen Berechtigungen:

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role="roles/artifactregistry.writer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
   --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role="roles/logging.logWriter"

gcloud storage buckets add-iam-policy-binding "gs://$CLOUDBUILD_BUCKET_NAME" \
   --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
   --role="roles/storage.objectAdmin"

Führen Sie den Build mit Cloud Build aus:

gcloud builds submit --config test_client/cloudbuild.yaml

Testen

Stellen Sie die Clientanwendung bereit, um die Sandbox zu erstellen, einen Snapshot auszulösen und zu prüfen, ob der interne Zähler erfolgreich aus dem gespeicherten Status fortgesetzt wird.

Erstellen Sie eine Datei mit dem Namen test_client/client_sa.yaml. Dieses Manifest definiert das Dienstkonto agent-sandbox-client-sa und die erforderlichen RBAC-Berechtigungen zum Verwalten benutzerdefinierter Sandbox-Ressourcen:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: agent-sandbox-client-sa
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: agent-sandbox-client-role
  namespace: default
rules:
- apiGroups: ["agents.x-k8s.io"]
  resources: ["sandboxes"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["extensions.agents.x-k8s.io"]
  resources: ["sandboxclaims"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["podsnapshot.gke.io"]
  resources: ["podsnapshotmanualtriggers", "podsnapshots"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: agent-sandbox-client-rolebinding
  namespace: default
subjects:
- kind: ServiceAccount
  name: agent-sandbox-client-sa
  namespace: default
roleRef:
  kind: Role
  name: agent-sandbox-client-role
  apiGroup: rbac.authorization.k8s.io

Wenden Sie das Manifest für das Client-Dienstkonto und RBAC an:
```
kubectl apply -f test_client/client_sa.yaml
```

Erstellen Sie eine Datei mit dem Namen test_client/client_pod.yaml. Dieses Manifest erstellt den Pod der Clientanwendung mit dem vorgefertigten Container-Image:

apiVersion: v1
kind: Pod
metadata:
  name: agent-sandbox-client-pod
  namespace: default
spec:
  serviceAccountName: agent-sandbox-client-sa
  containers:
  - name: client
    image: $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY_NAME/sandbox-client:latest
    imagePullPolicy: Always
  restartPolicy: Never

Ersetzen Sie die Platzhalter für die Umgebungsvariablen im Manifest:

sed -i "s/\$REPOSITORY_NAME/$REPOSITORY_NAME/g" test_client/client_pod.yaml
sed -i "s/\$LOCATION/$LOCATION/g" test_client/client_pod.yaml
sed -i "s/\$PROJECT_ID/$PROJECT_ID/g" test_client/client_pod.yaml

Wenden Sie das Pod-Manifest der Clientanwendung an:
```
kubectl apply -f test_client/client_pod.yaml
```
Streamen Sie die Pod-Logs, um den Ausführungsablauf zu prüfen:
```
kubectl logs -f agent-sandbox-client-pod
```

Wenn der Test ordnungsgemäß ausgeführt wird, sieht die Ausgabe so aus (hier zur besseren Lesbarkeit gekürzt):

2026-04-21 23:02:39,030 - INFO - Creating sandbox...
...
2026-04-21 23:02:51,755 - INFO - Count before suspend: 23
2026-04-21 23:02:51,755 - INFO - Pausing sandbox (using snapshots)...
...
2026-04-21 23:03:07,115 - INFO - Resuming sandbox (using snapshots)...
...
2026-04-21 23:03:21,329 - INFO - Count after resume: 38
2026-04-21 23:03:21,329 - INFO - Verification: Count before=23, Count after=38
2026-04-21 23:03:21,329 - INFO - SUCCESS: Sandbox resumed from where it left off (or later).

Die Ausgabe zeigt, dass der Status der Sandbox beim Anhalten und Fortsetzen beibehalten wird. Der Zähler wird angehalten, während die Sandbox angehalten ist (pausiert und auf null skaliert), und wird fortgesetzt, wenn die Sandbox wiederhergestellt wird. Ohne Anhalten wäre der Zähler während des Anhaltezeitraums weitergelaufen und die Anzahl wäre deutlich höher.

Ressourcen bereinigen

Löschen Sie die erstellten Ressourcen, damit Ihrem Google Cloud Konto keine Gebühren in Rechnung gestellt werden:

Löschen Sie den GKE-Cluster. Dadurch werden auch der Knotenpool und alle Kubernetes-Dienstkonten darin gelöscht:
```
gcloud beta container clusters delete test-snapshot --location="${LOCATION}" --quiet
```
Löschen Sie das Artifact Registry-Repository, um das Docker-Repository zu entfernen, das Sie für das Test-Image erstellt haben:
```
gcloud artifacts repositories delete ${REPOSITORY_NAME} --location="${LOCATION}" --quiet
```
Löschen Sie den Cloud Storage-Bucket und alle darin enthaltenen Snapshots. Dadurch werden automatisch die IAM-Bindungen für Workload Identity auf Bucket-Ebene entfernt, die darauf angewendet wurden:
```
gcloud storage rm --recursive "gs://${BUCKET_NAME}"
```

Entfernen Sie die IAM-Bindung auf Projektebene für den GKE-Dienstagenten:

gcloud projects remove-iam-policy-binding "${PROJECT_ID}" \
    --member="serviceAccount:service-${PROJECT_NUMBER}@container-engine-robot.iam.gserviceaccount.com" \
    --role="roles/storage.objectUser" \
    --condition="expression=resource.name.startsWith(\"projects/_/buckets/${BUCKET_NAME}\"),title=restrict_to_bucket,description=Restricts access to one bucket only"

Wenn Sie Cloud Build anstelle von Docker verwendet haben, um das Container-Image zu erstellen und per Push zu übertragen, löschen Sie den Logs-Bucket und entfernen Sie die Berechtigungen für das Dienstkonto:

gcloud storage rm --recursive "gs://${CLOUDBUILD_BUCKET_NAME}"

gcloud projects remove-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/artifactregistry.writer"

gcloud projects remove-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/logging.logWriter"

Nächste Schritte

Informationen zum Isolieren der KI-Codeausführung: externer Trigger
Informationen zum Speichern und Wiederherstellen von Agent Sandbox-Umgebungen
Informationen zu den Isolationsebenen, die Ihre nicht vertrauenswürdigen Arbeitslasten schützen, finden Sie unter GKE Sandbox.
Informationen zum Open-Source Projekt Agent Sandbox auf GitHub