This document explains how to create a copy, or snapshot, of a storage volume at a
specific point in time for your container application. A volume snapshot lets
you bring a volume back to a prior state or provision a new volume.

This document is for developers within the application operator group, who are
responsible for creating application workloads for their organization. For more
information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

To complete the tasks in this document, you must request the necessary
permissions and prepare your environment.

### Request IAM roles

You must have specific roles to get the permissions you need to create volume
snapshots. The roles you require depend on whether you are working within an
organization-scoped shared cluster or project-scoped standard cluster. For more
information, see
[Kubernetes cluster configurations](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/cluster-configs.md.txt).

#### Shared cluster roles

To create, delete, edit, or view volume snapshots in a shared cluster, ask your
IAM Project Admin to grant you the **Namespace Admin** (`namespace-admin`) role.
This role is bound to your project namespace.

#### Standard cluster roles

To create, delete, edit, or view volume snapshots in a standard cluster, ask
your IAM Project Admin to grant you the **Cluster Developer**
(`cluster-developer`) role. This role is bound to your project namespace.

### Prepare your environment

To run commands against a
[Kubernetes cluster](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/clusters.md.txt#cluster-architecture)
using the API, make sure you have the following resources:

- Locate the Kubernetes cluster name, or ask a member of the platform
  administrator group what the cluster name is.

- [Sign in and generate](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/iam/sign-in.md.txt#zonal-cluster-kubeconfig)
  the kubeconfig file for the Kubernetes cluster.

- Use the kubeconfig path of the Kubernetes cluster to replace
  `KUBERNETES_CLUSTER_KUBECONFIG` in these
  instructions.

## Take a volume snapshot

To take a snapshot of a `PersistentVolumeClaim` object, create a
`VolumeSnapshot` object. The system does not guarantee data consistency. Pause
the application and flush data before taking a snapshot.

1. Create a `VolumeSnapshot` custom resource:

   ```bash
   kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG \
       --namespace NAMESPACE apply -f - <<EOF
   apiVersion: snapshot.storage.k8s.io/v1
   kind: VolumeSnapshot
   metadata:
     name: VOLUME_SNAPSHOT_NAME
   spec:
     source:
       persistentVolumeClaimName: PVC_NAME
   EOF
   ```

   Replace the following:
   - `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for
     the cluster.

   - `NAMESPACE`: the namespace in which to create the
     volume snapshot. For shared clusters, this must be a project namespace.
     For standard clusters, it can be any namespace.

   - `VOLUME_SNAPSHOT_NAME`: the `VolumeSnapshot` object
     name.

   - `PVC_NAME`: the name of the PVC for which you are
     creating a snapshot.

2. The snapshot operation is complete when the `.status.readyToUse` field
   becomes `true`. You can use the following command to check the status:

   ```bash
     kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG get volumesnapshot \
       -o custom-columns='NAME:.metadata.name,READY:.status.readyToUse'
   ```
3. Update the PVC manifest with the volume snapshot specified as a data
   source:

   ```bash
   kubectl --kubeconfig KUBERNETES_CLUSTER_KUBECONFIG \
       --namespace NAMESPACE apply -f - <<EOF
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: PVC_NAME
   spec:
     dataSource:
       name: VOLUME_SNAPSHOT_NAME
       kind: VolumeSnapshot
       apiGroup: snapshot.storage.k8s.io
     storageClassName: standard-rwo
     accessModes:
       - ReadWriteOnce
   resources:
     requests:
       storage: 10Gi
   EOF
   ```

   Replace the following:
   - `KUBERNETES_CLUSTER_KUBECONFIG`: the kubeconfig file for
     the cluster.

   - `NAMESPACE`: the namespace in which the PVC
     resource exists. For shared clusters, this must be a project namespace.
     For standard clusters, it can be any namespace.

   - `PVC_NAME`: the name of the PVC for which you are
     creating a snapshot.

   - `VOLUME_SNAPSHOT_NAME`: the name of the volume
     snapshot.

## What's next

- [Container workloads overview](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/containers/containers-intro.md.txt)
- [Create stateful workloads](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/containers/create-stateful-workloads.md.txt)
- [Access persistent storage](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/containers/access-persistent-storage.md.txt)