To reduce startup latency for Google Kubernetes Engine (GKE) workloads, you can
restore new Pods from a saved snapshot of a running Pod. This document shows you
how to view existing snapshots, restore workloads from the latest snapshot or a
specific snapshot, and disable or delete snapshots. For more information about
how Pod snapshots work, see [About GKE Pod snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots.md.txt).

This document is for Platform admins and operators and Application developers
who manage Pod snapshots for their workloads. For more information about the
common roles and example tasks referenced in Google Cloud content, see
[Common GKE user roles and tasks](https://docs.cloud.google.com/kubernetes-engine/enterprise/docs/concepts/roles-tasks.md.txt).

## Before you begin


Before you start, make sure that you have performed the following tasks:

- Enable the Google Kubernetes Engine API.
[Enable Google Kubernetes Engine API](https://console.cloud.google.com/apis/enableflow?apiid=container.googleapis.com)
- To use the Google Cloud CLI for this task, [install](https://docs.cloud.google.com/sdk/docs/install) and then [initialize](https://docs.cloud.google.com/sdk/docs/initialize.md.txt) the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running the `gcloud components update` command. Earlier gcloud CLI versions might not support running the commands in this document.

  > [!NOTE]
  > **Note:** For existing gcloud CLI installations, make sure to set the `compute/region` [property](https://docs.cloud.google.com/sdk/docs/properties.md.txt#setting_properties). If you use primarily zonal clusters, set the `compute/zone` instead. By setting a default location, you can avoid errors in the gcloud CLI like the following: `One of [--zone, --region] must be supplied: Please specify location`. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

<!-- -->

- Prepare your cluster and storage environment, and trigger a snapshot of your
  workload. To meet these prerequisites, complete the tasks in the following
  documents in order:

  1. [Prepare for Pod snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/pod-snapshots-prepare.md.txt)
  2. [Trigger a Pod snapshot](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/pod-snapshots-trigger.md.txt)

## View snapshots

When you trigger a Pod snapshot, GKE creates a PodSnapshot custom
resource that represents the Pod state at that time. The `status` field of
this custom resource indicates whether the snapshot operation succeeded and
whether the snapshot is available to restore Pods.

To view all PodSnapshots in a namespace, run the following command:

```bash
kubectl get podsnapshots.podsnapshot.gke.io \
    --namespace NAMESPACE
```

Replace `NAMESPACE` with the namespace for your Pods.

The output is similar to the following:

    NAME                                  STATUS                 POLICY          AGE
    de334898-1e7a-4cdb-9f2e-7cc2181c29e4  AllSnapshotsAvailable  example-policy  47h

In this output, the `NAME` column shows the unique name that GKE
automatically generates for each PodSnapshot. The `STATUS` column shows the
`AllSnapshotsAvailable` value, which means that the snapshot is ready to restore
Pods.

## Restore a workload from the latest snapshot

When a Pod starts and [matches an existing snapshot](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots.md.txt#snapshot-matching), GKE
automatically restores the Pod from the latest snapshot instead of starting the
Pod from a fresh state. You can trigger this restoration in either of the
following ways:

- **Create a new Pod**: deploy a Pod with an identical specification, such as when you add replicas.
- **Redeploy an existing Pod**: delete the existing Pod, and then redeploy it.

To restore an existing Pod by deleting and redeploying it, follow these steps:

1. Delete the Pod:

   ```bash
   kubectl delete pod POD_NAME \
       --namespace NAMESPACE
   ```

   Replace the following:
   - `POD_NAME`: the name of your Pod.
   - `NAMESPACE`: the namespace for your Pods.
2. Redeploy the Pod:

   ```bash
   kubectl apply -f MANIFEST_FILE
   ```

   Replace `MANIFEST_FILE` with the path to the
   manifest file for your Pod.
3. To confirm that GKE restored the Pod from the snapshot, view
   the Pod logs:

   ```bash
   kubectl logs POD_NAME \
       --namespace NAMESPACE
   ```

   The output depends on how you configured your application. For example, if
   you deployed the example Python application from
   [Trigger a snapshot from a workload](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/pod-snapshots-trigger.md.txt#trigger-snapshot-workload), then the logs show
   `GKE Pod Snapshot: restore` when GKE restores the Pod.

## Restore a workload from a specific snapshot

By default, GKE restores workloads from the latest PodSnapshot
that matches the Pod. To restore a workload from a specific PodSnapshot, add the
`podsnapshot.gke.io/ps-name` annotation to your workload Pod specification by
following these steps:

1. To find the name of the PodSnapshot that you want to restore from, list the
   PodSnapshots in your namespace:

   ```bash
   kubectl get podsnapshots.podsnapshot.gke.io \
       --namespace NAMESPACE
   ```

   Replace `NAMESPACE` with the namespace for your
   Pods.
2. In your Pod manifest, add the `podsnapshot.gke.io/ps-name` annotation and
   specify the name of the PodSnapshot:

   ```yaml
   apiVersion: v1
   kind: Pod
   metadata:
     name: my-app
     namespace: NAMESPACE
     labels:
       app: my-app
     annotations:
       podsnapshot.gke.io/ps-name: "POD_SNAPSHOT_NAME"
   spec:
     serviceAccountName: SERVICEACCOUNT_NAME
     runtimeClassName: gvisor
     containers:
     # Multiple lines are omitted here
   ```

   Replace the following:
   - `POD_SNAPSHOT_NAME`: the name of the PodSnapshot that you want to restore from. Use the name that you found in the previous step.
   - `SERVICEACCOUNT_NAME`: the name of the ServiceAccount object that you granted Cloud Storage access to in [Prepare for Pod snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/pod-snapshots-prepare.md.txt).
3. Apply the manifest:

   ```bash
   kubectl apply -f MANIFEST_FILE
   ```

   Replace `MANIFEST_FILE` with the path to the
   manifest file for your Pod.

For GKE to restore the Pod from the specified snapshot, the
PodSnapshot must exist in the same namespace as the Pod and have a `Ready`
status condition. If the PodSnapshot doesn't meet these requirements, then the
Pod starts from a fresh state instead of restoring from the snapshot.

## Snapshot matching and compatibility

When GKE restores a Pod from a snapshot, GKE
checks whether an available snapshot is compatible with the Pod. To determine
compatibility, GKE evaluates the selection order, the match
criteria for the configured `whole-pod` or `rootfs-only` snapshot scope, and
any snapshot grouping rules.

For more information about matching requirements, compatibility criteria, and
the Pod specification fields that affect compatibility, see
[Snapshot matching and compatibility](https://docs.cloud.google.com/kubernetes-engine/docs/concepts/pod-snapshots.md.txt#snapshot-matching).

## Disable or delete snapshots

Whether you delete a PodSnapshotPolicy or a PodSnapshot depends on whether you
want to disable snapshots for an entire workload or delete one saved snapshot. A
PodSnapshotPolicy governs snapshot behavior for all of the Pods that match its
selector, and each PodSnapshot represents a single snapshot.

To disable snapshots for a workload, delete the PodSnapshotPolicy that governs
those Pods. Deleting the policy stops GKE from taking new
snapshots or restoring Pods for that workload, but doesn't affect running Pods.
However, if you delete the policy while GKE is saving or
restoring a Pod, then the Pod might enter a failed state.

To delete a PodSnapshotPolicy, run the following command:

```bash
kubectl delete podsnapshotpolicies.podsnapshot.gke.io \
    SNAPSHOT_POLICY \
    --namespace NAMESPACE
```

Replace the following:

- `SNAPSHOT_POLICY`: the name of the PodSnapshotPolicy that you want to delete, such as `example-pod-snapshot-policy`.
- `NAMESPACE`: the namespace for your Pods.

You can also delete a specific PodSnapshot so that GKE no longer
restores Pods from that snapshot. Deleting the PodSnapshot also deletes the
corresponding snapshot files stored in Cloud Storage.

To delete a specific PodSnapshot, run the following command:

```bash
kubectl delete podsnapshots.podsnapshot.gke.io \
    POD_SNAPSHOT_NAME \
    --namespace NAMESPACE
```

Replace `POD_SNAPSHOT_NAME` with the name of the
PodSnapshot that you want to delete, such as
`de334898-1e7a-4cdb-9f2e-7cc2181c29e4`.

## What's next

- [Troubleshoot Pod snapshots](https://docs.cloud.google.com/kubernetes-engine/docs/troubleshooting/pod-snapshots.md.txt)