Kubernetes Volume Group Snapshots: From Alpha to GA – A Complete Guide

Overview

Kubernetes volume group snapshots, first introduced as an Alpha feature in v1.27, then moved to Beta in v1.32 and again to a second Beta in v1.34, have finally reached General Availability (GA) with the release of Kubernetes v1.36. This milestone means the feature is now stable, production-ready, and enabled by default. Volume group snapshots allow you to create crash-consistent snapshots across multiple PersistentVolumeClaims (PVCs) simultaneously, making them indispensable for workloads that span several volumes—such as databases storing data and logs separately. Behind the scenes, the feature leverages a label selector to group PVCs and relies on the Container Storage Interface (CSI) driver to take the actual snapshot. This guide walks you through everything you need to know to start using volume group snapshots in your Kubernetes environment.

Kubernetes Volume Group Snapshots: From Alpha to GA – A Complete Guide

Prerequisites

Before you dive into volume group snapshots, ensure your environment meets these requirements:

A Kubernetes cluster running version 1.36 or later (GA requires v1.36).
A CSI driver that supports volume group snapshots (check your storage provider’s documentation). Not all CSI drivers implement this capability.
The VolumeGroupSnapshot APIs enabled (they are by default in v1.36). You can verify with: kubectl api-resources | grep volumegroupsnapshot.
kubectl configured to communicate with your cluster.
Basic understanding of Kubernetes PVCs, storage classes, and the VolumeSnapshot API.

Understanding the Volume Group Snapshot APIs

Three custom resource definitions (CRDs) form the backbone of this feature:

VolumeGroupSnapshot – The user-facing request to create a group snapshot from a set of PVCs.
VolumeGroupSnapshotContent – A cluster resource created by the snapshot controller that contains the actual snapshot details; binds to a VolumeGroupSnapshot.
VolumeGroupSnapshotClass – Defines the parameters for creating group snapshots, such as the CSI driver and deletion policy.

When you create a VolumeGroupSnapshot, Kubernetes uses a label selector to identify which PVCs to include. For example, you might label all PVCs belonging to the same application with app=my-app and then use that selector in your VolumeGroupSnapshot spec.

Step-by-Step Instructions

1. Label Your PersistentVolumeClaims

First, ensure the PVCs you want to snapshot together share a common label. For example:

kubectl label pvc data-pvc app=my-app
kubectl label pvc logs-pvc app=my-app

Verify with:

kubectl get pvc --selector app=my-app

2. Create a VolumeGroupSnapshotClass

This class tells Kubernetes which CSI driver to use and how to handle snapshot deletion. Example YAML:

apiVersion: groupsnapshot.storage.k8s.io/v1beta1
kind: VolumeGroupSnapshotClass
metadata:
  name: csi-group-snapclass
spec:
  driver: csi-hostpath  # Replace with your CSI driver name
  deletionPolicy: Delete  # or Retain

Apply it:

kubectl apply -f groupsnapshotclass.yaml

3. Create a VolumeGroupSnapshot

Now, request a group snapshot by referencing the label selector and the snapshot class. Example:

apiVersion: groupsnapshot.storage.k8s.io/v1beta1
kind: VolumeGroupSnapshot
metadata:
  name: my-group-snapshot
spec:
  volumeGroupSnapshotClassName: csi-group-snapclass
  source:
    selector:
      matchLabels:
        app: my-app
  # optional: specify a different namespace if needed
  # source: (same resource)

Apply:

kubectl create -f groupsnapshot.yaml

Check status:

kubectl describe volumegroupsnapshot my-group-snapshot

Once ready, the status.readyToUse field will be true.

4. Restore Volumes from a Group Snapshot

To restore, you create new PVCs from the individual snapshots within the group. Kubernetes automatically creates a VolumeSnapshot for each PVC in the group. List them:

kubectl get volumesnapshot

You’ll see snapshots named like my-group-snapshot-data-pvc-xxx. Use those to create new PVCs:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: restored-data-pvc
spec:
  storageClassName: standard
  dataSource:
    apiGroup: snapshot.storage.k8s.io
    kind: VolumeSnapshot
    name: my-group-snapshot-data-pvc-xxx  # Use correct snapshot name
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Apply for each volume you want to restore. The new PVC will be pre-populated with the snapshot data at the same point-in-time.

5. Clean Up (Optional)

Delete the group snapshot and its content when no longer needed:

kubectl delete volumegroupsnapshot my-group-snapshot

Depending on the DeletionPolicy in your VolumeGroupSnapshotClass, the underlying snapshot content may be removed or retained.

Common Mistakes

Label selector mismatches: Ensure the label selector in the VolumeGroupSnapshot matches exactly the labels on the PVCs. Extra or missing labels cause the snapshot to include the wrong volumes or none at all.
CSI driver not supporting group snapshots: Not all storage backends support this feature. Check your CSI driver’s documentation. If unsupported, the VolumeGroupSnapshot will remain in a pending state.
Forgetting to create a VolumeGroupSnapshotClass: Without a class, the snapshot controller cannot determine the driver or deletion policy, and the request will fail.
Namespace confusion: The VolumeGroupSnapshot and the PVCs must be in the same namespace. If your selector spans multiple namespaces, you need separate group snapshot objects.
Assuming individual snapshots are also group snapshots: The VolumeGroupSnapshot creates individual VolumeSnapshot objects per PVC, but they are tied together as a group. You cannot restore the group as a single unit; you must restore each PVC individually from the corresponding snapshot.

Summary

Volume group snapshots in Kubernetes v1.36 GA provide a reliable way to create crash-consistent backup points across multiple persistent volumes. By labeling PVCs and using the VolumeGroupSnapshot API, you can snapshot entire application data sets without quiescing the workload. This feature relies on CSI drivers and is ideal for stateful applications that use multiple volumes. Follow the steps above to label, create, and restore group snapshots, and watch for common pitfalls like label mismatches or incompatible CSI drivers. With GA status, volume group snapshots are now a stable, essential tool for Kubernetes data protection.

Tags: