Kubernetes Changed Block Tracking API – Beta Differences

Kubernetes Changed Block Tracking API - Beta Differences

Changed Block Tracking (CBT) support for CSI drivers

shipped as Alpha in

September 2025. With the March 2026 v1.0.0 release of the

external-snapshot-metadata

project, the feature moved to Beta.

If you aren't yet familiar with changed block tracking for storage in

Kubernetes, the

Alpha announcement covers

the motivation, the three primary components (the CSI SnapshotMetadata

gRPC service, the SnapshotMetadataService CRD, and the

external-snapshot-metadata sidecar), and a walkthrough of how to use the

API. CBT currently applies to block volumes; file-volume and network

file-share changed-list tracking is not covered by this feature. This post

focuses on what is different in Beta.

The main change in that release was the promotion of the

SnapshotMetadataService CRD from v1alpha1 to v1beta1. The CRD used to

advertise a driver's metadata service now serves

cbt.storage.k8s.io/v1beta1. The schema itself is unchanged, but this

release removed v1alpha1 (rather than serving it alongside the new version).

If you are upgrading from Alpha, you need to:

- Re-apply the CRD definition shipped with v1.0.0.

- Update SnapshotMetadataService manifests to use

apiVersion: cbt.storage.k8s.io/v1beta1.

- Update any client or controller code that talks to the CRD.

This is a one-time change. There is no automatic conversion between the two versions.

- Minimum Kubernetes version: 1.33

- CSI spec: 1.10 or newer

- Container image: registry.k8s.io/sig-storage/csi-snapshot-metadata:v1.0.0

The Getting Started section in the Alpha blog still applies. In short:

- Make sure your CSI driver supports volume snapshots and ships the

external-snapshot-metadatasidecar.

- Install the SnapshotMetadataService CRD (the v1beta1definition from thev1.0.0release).

- Create a SnapshotMetadataService resource for your driver.

- Use a client — snapshot-metadata-lister, or your own implementation — to callGetMetadataAllocatedandGetMetadataDelta.

If you want to see the full flow end-to-end, the hostpath driver example is a good starting point.

The focus for the rest of the Beta cycle is wider CSI driver adoption and operational feedback before the feature moves towards GA. If you maintain a CSI driver, this is a good time to evaluate adding support. If you are building a backup application on top of the API, feedback on the streaming clients and the iterator package is very welcome.

- The CSI developer documentation for snapshot metadata.

- KEP-3314.

- The external-snapshot-metadata repository.

- The gRPC schema.

- The snapshot-metadata-lister example client.

This work is the result of contributions from many people across SIG Storage. A big thank you to everyone who helped review, code, and test the feature through Alpha and into Beta:

- Ben Swartzlander (bswartz)

- Carl Braganza (carlbraganza)

- Daniil Fedotov (hairyhum)

- Ivan Sim (ihcsim)

- Nikhil Ladha (Nikhil-Ladha)

- Praveen M (iPraveenParihar)

- Rakshith R (Rakshith-R)

- Xing Yang (xing-yang)

If you would like to get involved with CSI or storage in Kubernetes, SIG Storage is the place to start. The Data Protection Working Group also holds regular meetings, and new attendees are always welcome.