This document shows you how to use [GKE Pod
snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots) to save the state of
a running Agent Sandbox on GKE environment.

Agent Sandbox on GKE improves your security by providing
an isolated environment for executing untrusted code, such as code generated by
large language models (LLMs). Running this type of code directly in a cluster
poses security risks, because untrusted code could potentially access or
interfere with other apps or the underlying cluster node itself.

GKE Pod snapshots let you save and restore the state of sandboxed
environments. This functionality is useful for the following reasons:

- **Fast startup**: reduce sandbox startup time by restoring from a pre-warmed snapshot.
- **Long-running agents**: pause a sandbox that takes a long time to run and resume it later, or move it to a different node, without losing progress.
- **Stateful workloads**: persist the context of an agent, such as conversation history or intermediate calculations, by saving and restoring the state of its sandboxed environment.
- **Reproducibility**: capture a specific state and use it as a base to start multiple new sandboxes with the same initialized state.

A snapshot can be triggered in two ways:

- **Manual trigger:** you create a `PodSnapshotManualTrigger` resource to trigger the snapshot.
- **Workload trigger:** the sandboxed application itself signals when it's ready to be saved.

This document shows you how to manually trigger a snapshot.

## Before you begin

1. 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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).

   > [!NOTE]
   > **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](https://console.cloud.google.com/projectselector2/home/dashboard)
2.
   [Verify that billing is enabled for your Google Cloud project](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

3.


   Enable the Google Kubernetes Engine, Cloud Storage, Identity and Access Management (IAM) APIs, if any are not already enabled.


   **Roles required to enable APIs**


   To enable APIs, you need the `serviceusage.services.enable` permission. If you
   created the project, then you likely already have this permission through the
   Owner role (`roles/owner`). Otherwise, you can get this permission through the
   Service Usage Admin role (`roles/serviceusage.serviceUsageAdmin`).
   [Learn how to grant roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

   [Enable the APIs](https://console.cloud.google.com/apis/enableflow?apiid=container.googleapis.com,storage.googleapis.com,iam.googleapis.com)
4. In the Google Cloud console, activate Cloud Shell.

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)

## Requirements

GKE Pod snapshots requires GKE version
1.35.3-gke.1234000 or later. Both Autopilot and Standard modes
are supported.

Pod snapshots require gVisor and don't work with [microVM
sandboxes](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods#sandbox-technologies).

Because Pod snapshots require
[GKE Sandbox](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods.md.txt), your
environment is subject to certain limitations. For example, Pod snapshots don't
support E2 machine types. Consequently, this tutorial creates a node pool
consisting of N2 machines.

For a full list of restrictions, including information on using GPU-based
machine types, see [Limitations and
requirements](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots#limitations).

## Define environment variables

To simplify the commands that you run in this document, you can set environment
variables in [Cloud Shell](https://docs.cloud.google.com/shell/docs/using-cloud-shell.md.txt). These variables
store values such as the ID of your Google Cloud project, the name of the
Cloud Storage bucket that will store your snapshots, and the location of your
GKE cluster.

After you define these variables, you can reuse them in multiple commands by
referencing the variable name (for example, `$CLUSTER_NAME`) instead of retyping
or replacing values each time. This approach makes the process easier to follow
and reduces the risk of errors.

To define the following useful environment variables in Cloud Shell, run
the following commands:

```bash
export PROJECT_ID=$(gcloud config get project)
export CLUSTER_NAME="agent-sandbox-cluster"
export GKE_LOCATION="us-central1"
export ZONE="us-central1-a"
export AGENT_SANDBOX_VERSION="v1.0.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)")
```

Here's an explanation of these environment variables:

- `PROJECT_ID`: the ID of your current Google Cloud project. Commands in this document use this ID to name resources and to grant IAM permissions.
- `CLUSTER_NAME`: the name of your GKE cluster (for example, `agent-sandbox-cluster`).
- `GKE_LOCATION`: the Google Cloud region for your Cloud Storage bucket (for example, `us-central1`). If you create an Autopilot cluster, the cluster also uses this region.
- `ZONE`: the zone for your GKE cluster. If you create a Standard cluster, set this to a zone in the `GKE_LOCATION` region (for example, `us-central1-a`). To reduce costs, this document creates a zonal Standard cluster.
- `AGENT_SANDBOX_VERSION`: the version of the open source Agent Sandbox controller to install. This document uses version 1.0.6.
- `NODE_POOL_NAME`: the name of the node pool that will run sandboxed workloads (for example, `agent-sandbox-node-pool`).
- `MACHINE_TYPE`: the machine type of the nodes in your node pool (for example, `n2-standard-2`). Pod snapshots don't support E2 machine types. If you want to use GPU-based machine types for the nodes in your node pool, see [Limitations and
  requirements](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots#limitations). For details about different machine series and choosing between different options, see the [Machine families resource and comparison
  guide](https://docs.cloud.google.com/compute/docs/machine-resource).
- `SNAPSHOTS_BUCKET_NAME`: the name of the Cloud Storage bucket you will create to store snapshots.
- `SNAPSHOT_NAMESPACE`: the Kubernetes namespace where your snapshot workload and service account will reside.
- `SNAPSHOT_KSA_NAME`: the name of the Kubernetes service account your workload will use to authenticate.
- `SNAPSHOT_FOLDER`: the directory inside your Cloud Storage bucket where snapshots will be organized.
- `PROJECT_NUMBER`: the unique numerical identifier for your project, used for IAM permission bindings.

## Overview of configuration steps

To enable Pod snapshots of Agent Sandbox on GKE
environments, you need to perform some configuration steps. To understand these
steps, it's helpful to first understand a few key concepts and then the snapshot
process:

### Key concepts

- **Environment:** a sandboxed application runs inside a Kubernetes Pod on a GKE cluster node.
- **Identity:** the Pod is associated with a [Kubernetes service
  account](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/workload-identity#terminology) and runs in a special namespace that you create. Together, the Kubernetes service account and the namespace form a unique identity that is used to grant the Pod secure access to Google Cloud resources.
- **Permissions** : to allow snapshots to be saved to Cloud Storage, the Pod's identity must be granted specific IAM permissions that allow it to write to a [Cloud Storage bucket](https://docs.cloud.google.com/storage/docs/buckets.md.txt).

### Snapshot process

1. **Trigger:** a snapshot is initiated, either manually (externally) or by the sandboxed workload itself. This document demonstrates a manual trigger which you initiate by creating a `PodSnapshotManualTrigger` resource.
2. **Capture:** GKE captures the running state of the Pod, such as the state of the Pod's memory and its file system.
3. **Upload:** using the permissions granted to the Pod's Kubernetes service account, GKE uploads the captured state as snapshot files to the designated Cloud Storage bucket.

To learn more about how GKE uses Kubernetes service accounts and
IAM roles to access Google Cloud resources, see [Authenticate to
Google Cloud APIs from GKE
workloads](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).

To enable Pod snapshots of Agent Sandbox on GKE
environments, perform the following configuration. First, you prepare a cluster
environment by creating a GKE cluster with Workload Identity Federation for GKE
and the Pod snapshots features enabled. Next, you configure Cloud Storage and
IAM policies to help ensure that your snapshots are stored
securely and that your sandbox has the necessary permissions. Finally, you
create the snapshot resources that specify the storage location and policies for
your sandbox.

The following table summarizes the configuration steps you need to perform, and
each step is explained in the sections that follow:

| Topic | Task |
|---|---|
| [**Cluster setup**](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#cluster-setup) | 1. [Create a GKE cluster and enable the Pod snapshots and Workload Identity Federation for GKE features.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#create-gke-cluster) 2. [Deploy Agent Sandbox.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#deploy-controller) |
| [**Configure storage and permissions**](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#storage-perms) | 1. [Create the Cloud Storage bucket and managed folder.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#create-storage-bucket) 2. [Create the custom IAM role.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#configure-KSA) 3. [Create the Kubernetes namespace and the Kubernetes service account (KSA).](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#configure-KSA) 4. [Bind the IAM role to the Kubernetes service account.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#configure-KSA) 5. [Grant permissions to the snapshot controller.](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#grant-controller-perms) |
| [**Configure snapshot resources**](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#snapshot-resources) | 1. [Create a `PodSnapshotStorageConfig` resource](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#define-storage-rules) 2. [Create a `PodSnapshotPolicy` resource](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#define-storage-rules) 3. [Create `SandboxTemplate`, `SandboxWarmPool`, and `SandboxClaim` resources](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox-pod-snapshots.md.txt#create-sandbox-template) |

## Cluster setup

A sandboxed app runs inside a Pod on a GKE cluster node, so you
need to set up a cluster environment. This section shows you how to create a
GKE cluster, and deploy the Agent Sandbox controller.

### Create a new GKE cluster that meets the requirements

Create a new GKE cluster with Pod snapshots enabled. Pod
snapshots require GKE version 1.35.3-gke.1234000 or later. The
following commands enroll the cluster in the Rapid release channel, whose
default version meets this requirement:

### Autopilot

Create an Autopilot cluster with the required features:

```bash
gcloud container clusters create-auto ${CLUSTER_NAME} \
   --release-channel=rapid \
   --enable-pod-snapshots \
   --location=${GKE_LOCATION}
```

### Standard

Create a Standard cluster with the required features. To reduce
costs, the following command creates a zonal cluster, which runs its
control plane and nodes in one zone:

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

Create a node pool with
[GKE Sandbox](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods.md.txt) enabled.
GKE Sandbox is a container security feature based on the open-source
gVisor project that provides an additional layer of isolation between
running applications and the host operating system:

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

### Retrieve credentials

Retrieve the cluster's credentials so that the `kubectl` CLI can connect to
the cluster:

### Autopilot

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

### Standard

```bash
gcloud container clusters get-credentials ${CLUSTER_NAME} \
    --location=${ZONE}
```

### Deploy the Agent Sandbox Controller to your cluster

You can deploy the Agent Sandbox controller and its required components by
applying the official release manifest to your cluster. This manifest is a
configuration file that instructs Kubernetes to download all the necessary
components that are required to deploy and run the Agent Sandbox controller on
your cluster.

To deploy Agent Sandbox to your GKE
cluster, run the following command:

```bash
# Apply the release manifest for the controller and its CustomResourceDefinitions
kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/${AGENT_SANDBOX_VERSION}/sandbox-with-extensions.yaml
```

For more information about installing Agent Sandbox, see
[Install Agent Sandbox on
GKE](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/how-install-agent-sandbox).

### Verify the controller

After applying the manifest, check that the Agent Sandbox controller Pod is
running correctly in the `agent-sandbox-system` namespace. The manifest
automatically created the `agent-sandbox-system` namespace when you applied it
in the previous step.

```bash
kubectl get pods -n agent-sandbox-system
```

Wait for the Pod to show 'Running' in the **STATUS** column and '1/1' in the
**READY** column. When the Pod is running correctly, the output looks similar to
this:

    NAME                                        READY   STATUS    RESTARTS   AGE
    agent-sandbox-controller-7d5c9b8f6d-x2k9p   1/1     Running   0          2m

Now that the Agent Sandbox controller is running, it can automatically create
and manage sandboxed environments for any `Sandbox` resources that you create in
your cluster.

## Configure storage and permissions

This section shows you how to configure the storage and permissions required for
Pod snapshots. You create a Cloud Storage bucket and a managed folder to
store the snapshot data. Then, you grant your sandbox and the snapshot
controller the permissions they need to access that storage.

### Create the Cloud Storage bucket

Create a [bucket](https://docs.cloud.google.com/storage/docs/buckets.md.txt) to store your snapshots. To help ensure
that the snapshot process is fast and cost-effective, create the bucket with the
following settings:

- **Enable hierarchical namespaces:** the hierarchical namespaces feature organizes your bucket into a file system hierarchy rather than a flat namespace. This configuration allows for higher read and write throughput, and consequently speeds up saving and restoring snapshots.
- **Disable soft delete:** the soft delete feature protects data by retaining deleted files for a set period. However, the snapshot process creates and deletes many temporary files during upload. Disable soft delete to avoid unnecessary charges for storing these temporary files.

To create the bucket with these settings, run the following command:

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

### Create a managed folder

Create a managed folder to organize snapshots within your bucket. Managed
folders allow you to apply IAM permissions to a specific folder
rather than to the entire bucket. This folder-level access limits your sandbox's
access to only its own snapshots, and isolates those snapshots from other data
in the bucket.

To create a managed folder, run this command:

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

### Configure the service account and IAM roles

To allow GKE to save snapshots securely, the Kubernetes service
account used by the Pods running your sandboxed workload needs permission to
write to your bucket. You grant this permission by binding Google Cloud
IAM roles to the Kubernetes service account used by the Pods.
This section shows you how to create a custom IAM role, create
the Kubernetes service account, and configure the necessary permissions.

1. Create a custom IAM role called `podSnapshotGcsReadWriter`
   that contains the permissions required to write snapshot data. If this role
   already exists in your project, for example from an earlier run of this
   document, skip this step. Otherwise, run the following command:

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

   When the role is created successfully, the output looks like this:

       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

   If the command fails with a `FAILED_PRECONDITION` error that says the role
   ID has been marked for deletion, you deleted a role with this ID recently,
   for example in the clean-up steps of an earlier run of this document.
   IAM doesn't let you reuse that ID for up to 37 days. Run the
   command again with a different role ID, such as
   `podSnapshotGcsReadWriter2`, and use that ID instead of
   `podSnapshotGcsReadWriter` in the rest of this document.
2. Create the namespace in which your sandbox and its service account will
   reside:

   ```bash
   kubectl create namespace "${SNAPSHOT_NAMESPACE}"
   ```
3. Create the Kubernetes service account in the namespace you just
   created. Together, the Kubernetes service account and the namespace form a
   unique identity used to grant your sandbox secure access to Google Cloud
   resources:

   ```bash
   kubectl create serviceaccount "${SNAPSHOT_KSA_NAME}" \
       --namespace "${SNAPSHOT_NAMESPACE}"
   ```
4. Grant the `roles/storage.bucketViewer` role to all service accounts in
   the namespace. This role allows the accounts to view the bucket's metadata
   but not to read or write the data itself:

   ```bash
   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. Grant your custom `podSnapshotGcsReadWriter` role to the Kubernetes service
   account for your sandbox. This binding allows only this specific account to
   write data to the managed folder. A new custom role can take a few minutes
   to become available, so if this command fails because the role doesn't
   exist, wait a minute and then run the command again:

   ```bash
   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. Grant the `roles/storage.objectUser` role to the Kubernetes service account.
   This role is required for the Pod snapshot agent to perform operations on
   managed folders:

   ```bash
   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"
   ```

### Grant permissions to the snapshot controller

Grant the `objectUser` role to the GKE system's snapshot
controller. This permission allows the controller to manage the snapshot
lifecycle, such as deleting snapshot objects when you delete a `PodSnapshot`
resource:

```bash
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"
```

## Configure snapshot resources

This section shows you how to configure the snapshot resources for your
Agent Sandbox on GKE workload.

### Define snapshot storage and rules

To specify where GKE saves your snapshots and which rules govern
the snapshot process, you create two custom resources:

- **`PodSnapshotStorageConfig`**: this resource specifies the Cloud Storage bucket and folder location where GKE saves your snapshot files.
- **`PodSnapshotPolicy`** : this resource defines which Pods are eligible for snapshots based on their Kubernetes labels. It also specifies the trigger rules, such as whether snapshots are manual or initiated by the sandbox workload. This example groups snapshots by the `agents.x-k8s.io/sandbox-name-hash` label, which the Agent Sandbox controller adds to the Pod of each sandbox. This grouping means that GKE restores each sandbox only from its own snapshots.

To apply both resources in one step, run the following command in
Cloud Shell. This method helps to ensure that your environment variables are
correctly injected:

```bash
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
  snapshotGroupingRules:
    groupByLabelValue:
      labels:
      - agents.x-k8s.io/sandbox-name-hash
EOF
```

### Verify the configuration

After you apply the snapshot storage configuration and policy, verify that the
resources are ready to use. This section shows you how to check the status of
these custom resources.

1. Check the status of the `PodSnapshotStorageConfig` resource:

   ```bash
   kubectl get podsnapshotstorageconfigs.podsnapshot.gke.io cpu-pssc-gcs -o yaml
   ```

   The output should contain a condition with `type: Ready` and `status:
   "True"`:

   ```yaml
   status:
     conditions:
     - lastTransitionTime: "2025-10-31T18:18:02Z"
       message: Valid PodSnapshotStorageConfig
       reason: StorageConfigValid
       status: "True"
       type: Ready
   ```
2. Check the status of the `PodSnapshotPolicy` resource:

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

   The output should contain a condition with `type: Ready` and `status:
   "True"`. It should also indicate that the referenced
   `PodSnapshotStorageConfig` resource was found:

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

### Create the sandbox template

Now that the storage policies and permissions are in place, you create the
`SandboxTemplate`, `SandboxWarmPool`, and `SandboxClaim` resources. The
`SandboxWarmPool` resource keeps a pre-warmed sandbox running, and the
`SandboxClaim` resource claims that sandbox from the pool. For the snapshot
process to work, the sandbox must run with the Kubernetes service account you
created earlier in this document. The sandbox must also have the labels that
you specified earlier in the `PodSnapshotPolicy` resource.

This example uses a Python app that prints an incrementing counter to the
logs. This counter lets you verify that the state is successfully saved and
restored later.

### Autopilot

Pod snapshots don't support E2 machine types. In Autopilot,
GKE might default to machine types that don't support
Pod snapshots. To help ensure your workloads run on compatible hardware,
you should use a
[custom ComputeClass](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/node-attributes-compute-classes.md.txt)
to prioritize compatible machine families.

1. Save the following manifest as `non-e2-class.yaml`:

   ```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. Apply the manifest:

   ```bash
   kubectl apply -f non-e2-class.yaml
   ```
3. To create the `SandboxTemplate` and `SandboxWarmPool` resources, apply
   the following manifest. Notice that the `SandboxTemplate` resource
   refers to the `ComputeClass` you just created using the
   `cloud.google.com/compute-class: non-e2-class` node selector.

   ```bash
   kubectl apply -f - <<EOF
   ---
   apiVersion: extensions.agents.x-k8s.io/v1beta1
   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/v1beta1
   kind: SandboxWarmPool
   metadata:
     name: python-sandbox-warmpool
     namespace: ${SNAPSHOT_NAMESPACE}
   spec:
     replicas: 1
     sandboxTemplateRef:
       name: python-runtime-template
   EOF
   ```

### Standard

To create the `SandboxTemplate` and `SandboxWarmPool` resources, apply
the following manifest:

```bash
kubectl apply -f - <<EOF
---
apiVersion: extensions.agents.x-k8s.io/v1beta1
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/v1beta1
kind: SandboxWarmPool
metadata:
  name: python-sandbox-warmpool
  namespace: ${SNAPSHOT_NAMESPACE}
spec:
  replicas: 1
  sandboxTemplateRef:
    name: python-runtime-template
EOF
```

After you create the resources, claim a sandbox from the warm pool:

1. Wait until the warm pool's sandbox is ready:

   ```bash
   kubectl wait sandboxwarmpool python-sandbox-warmpool \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --for=jsonpath='{.status.readyReplicas}'=1 \
     --timeout=600s
   ```
2. Create a `SandboxClaim` resource that claims the sandbox from the warm pool:

   ```bash
   kubectl apply -f - <<EOF
   apiVersion: extensions.agents.x-k8s.io/v1beta1
   kind: SandboxClaim
   metadata:
     name: python-sandbox-example
     namespace: ${SNAPSHOT_NAMESPACE}
   spec:
     warmPoolRef:
       name: python-sandbox-warmpool
   EOF
   ```
3. Wait until the claim is ready, and then save the name of the sandbox that
   the claim uses. The sandbox's Pod has the same name as the sandbox:

   ```bash
   kubectl wait sandboxclaim python-sandbox-example \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --for=condition=Ready \
     --timeout=300s

   export SANDBOX_NAME=$(kubectl get sandboxclaim python-sandbox-example \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     -o jsonpath='{.status.sandbox.name}')
   echo "${SANDBOX_NAME}"
   ```

Your sandbox is now running with the correct identity and is ready to be
snapshotted.

## Create a snapshot

This section shows you how to manually trigger a snapshot of your running
sandbox. You create a trigger resource that targets your sandbox Pod and then
you verify that the snapshot process completes successfully.

1. **Check the initial counter logs:** Before triggering the snapshot, view the
   logs of the running sandbox to see the current counter value. Viewing the logs
   establishes a baseline to compare against after restoring.

   ```bash
   kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}" --tail=5
   ```

   The output shows the last few lines of the counter, for example:

       Count: 15
       Count: 16
       Count: 17

   Note the last few "Count" values printed.
2. **Create a `PodSnapshotManualTrigger` resource:** Initiate the snapshot:

   ```bash
   kubectl apply -f - <<EOF
   apiVersion: podsnapshot.gke.io/v1
   kind: PodSnapshotManualTrigger
   metadata:
     name: cpu-snapshot-trigger
     namespace: ${SNAPSHOT_NAMESPACE}
   spec:
     targetPod: ${SANDBOX_NAME}
   EOF
   ```
3. **Verify that the manual trigger was successful:**

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

   The output should show a status of `Complete`, indicating that
   GKE successfully triggered the snapshot of the target Pod:

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

4. **View more details about the captured state** by describing the trigger:

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

   The output contains a `Snapshot Created` section with the unique name of the
   snapshot files stored in your bucket:

   ```yaml
   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>
   ```

## Restore from a snapshot

After you capture a snapshot, you can suspend the sandbox to free up its
compute resources, and later resume the sandbox from its saved state. When you
suspend a sandbox, the Agent Sandbox controller deletes the
sandbox's Pod but keeps the `Sandbox` resource. When you resume the sandbox, the
controller re-creates the Pod, and the Pod snapshot controller automatically
restores the Pod from the most recent snapshot of that sandbox.

1. Wait until the snapshot is ready. GKE restores a Pod only
   from a snapshot that's ready. If you suspend the sandbox before the
   snapshot is ready, the sandbox starts without the saved state when you
   resume it.

   ```bash
   export SNAPSHOT_NAME=$(kubectl get podsnapshotmanualtriggers.podsnapshot.gke.io cpu-snapshot-trigger \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     -o jsonpath='{.status.snapshotCreated.name}')

   kubectl wait podsnapshots.podsnapshot.gke.io "${SNAPSHOT_NAME}" \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --for=condition=Ready \
     --timeout=600s
   ```
2. To suspend the sandbox, set its `operatingMode` field to `Suspended`, and
   then wait until the controller deletes the sandbox's Pod:

   ```bash
   kubectl patch sandbox "${SANDBOX_NAME}" \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --type=merge \
     -p '{"spec":{"operatingMode":"Suspended"}}'

   kubectl wait pod "${SANDBOX_NAME}" \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --for=delete \
     --timeout=120s
   ```
3. To resume the sandbox, set its `operatingMode` field to `Running`, and then
   wait until the sandbox is ready:

   ```bash
   kubectl patch sandbox "${SANDBOX_NAME}" \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --type=merge \
     -p '{"spec":{"operatingMode":"Running"}}'

   kubectl wait sandbox "${SANDBOX_NAME}" \
     --namespace "${SNAPSHOT_NAMESPACE}" \
     --for=condition=Ready \
     --timeout=300s
   ```
4. Verify that the restore took place by viewing the logs. Note that the
   counter continues from the point where the snapshot was taken:

   ```bash
   kubectl logs "${SANDBOX_NAME}" --namespace "${SNAPSHOT_NAMESPACE}"
   ```

   The output should show the counter resuming, for example:

       Count: 18
       Count: 19
       Count: 20
       Count: 21

   If the counter starts from `0` instead, the Pod started without restoring
   from the snapshot.

## Clean up resources

To avoid incurring charges to your Google Cloud account for the resources used
in this document, perform the following steps in order to delete the resources
you created:

1. Delete the sandbox claims and warm pools to stop any running Pods and allow
   the Agent Sandbox controller to gracefully terminate the containers.

   ```bash
   kubectl delete sandboxclaims --all --namespace "${SNAPSHOT_NAMESPACE}"
   kubectl delete sandboxwarmpools --all --namespace "${SNAPSHOT_NAMESPACE}"
   ```
2. Delete the sandbox templates and manual triggers used to create sandboxes and
   initiate snapshots.

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

   # Delete the snapshot initiation objects
   kubectl delete podsnapshotmanualtriggers --all --namespace "${SNAPSHOT_NAMESPACE}"
   ```
3. Delete the snapshot policies that define which Pods are eligible for
   snapshots within your namespace.

   ```bash
   kubectl delete podsnapshotpolicy cpu-psp --namespace "${SNAPSHOT_NAMESPACE}"
   ```
4. Delete the snapshot storage configuration, which is the global definition of
   your snapshot storage backend. Because this resource is cluster-scoped,
   don't use a namespace flag.

   ```bash
   kubectl delete podsnapshotstorageconfig cpu-pssc-gcs
   ```
5. If you created one for Autopilot, delete the ComputeClass.

   ```bash
   kubectl delete computeclass non-e2-class
   ```
6. Delete the Kubernetes namespace to automatically remove the Kubernetes
   service account and any remaining namespaced metadata.

   ```bash
   kubectl delete namespace "${SNAPSHOT_NAMESPACE}"
   ```
7. Delete the GKE cluster to remove the underlying infrastructure
   and all nodes associated with the tutorial.

   ### Autopilot

   ```bash
   gcloud container clusters delete "${CLUSTER_NAME}" \
       --location="${GKE_LOCATION}" --quiet
   ```

   ### Standard

   ```bash
   gcloud container clusters delete "${CLUSTER_NAME}" \
       --location="${ZONE}" --quiet
   ```
8. Delete the Cloud Storage bucket (optional) by using the recursive remove
   command if you want to fully reset your storage. Note that you can skip this
   if you intend to reuse your correctly configured bucket for future tests.

   ```bash
   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. Delete the custom IAM role (optional) if you want to return
   your project to a completely clean state. Because IAM roles
   persist even after the cluster is deleted, you must delete them separately.

   ```bash
   gcloud iam roles delete podSnapshotGcsReadWriter --project="${PROJECT_ID}"
   ```

## What's next

- Learn more about [GKE Pod
  Snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots).
- Learn more about the Agent Sandbox open-source project on [GitHub](https://github.com/kubernetes-sigs/agent-sandbox).
- Learn how to [Isolate AI code execution with Agent Sandbox on
  GKE](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox).