Skip to content

KEP-3314: updated to reflect the latest state #5670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+20 −1
Open

KEP-3314: updated to reflect the latest state #5670

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion keps/sig-storage/3314-csi-changed-block-tracking/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -769,6 +769,7 @@ The following conditions are well defined:
|-----------|-----------|-------------|-------------------|
| Missing or otherwise invalid argument | 3 INVALID_ARGUMENT | Indicates that a required argument field was not specified or an argument value is invalid | The caller should correct the error and resubmit the call. |
| Invalid `base_snapshot` or `target_snapshot` | 5 NOT_FOUND | Indicates that the snapshots specified were not found. | The caller should re-check that these objects exist. |
| Changed block tracking is not enabled | 9 FAILED_PRECONDITION | Changed block tracking has not been enabled in the underlying storage subsystem. | The caller should perform a full backup instead. The operation would proceed if changed block tracking was enabled in the storage subsystem, but how this is to be accomplished is beyond the scope of this specification. |
| Invalid `starting_offset` | 11 OUT_OF_RANGE | The starting offset exceeds the volume size. | The caller should specify a `starting_offset` less than the volume's size. |

### Kubernetes Components
Expand Down Expand Up @@ -858,12 +859,30 @@ message GetMetadataAllocatedRequest {
message GetMetadataDeltaRequest {
string security_token = 1;
string namespace = 2;
string base_snapshot_name = 3;
string base_snapshot_id = 3;
string target_snapshot_name = 4;
int64 starting_offset = 5;
int32 max_results = 6;
}
```
The `GetMetadataDeltaRequest` requires that the invoking backup
application provide the **CSI snapshot handle** of the base snapshot
against which changes are to be computed, and **not the name** of the base
`VolumeSnapshot` object.
The invoking backup application should fetch this value from the
`Status.SnapshotHandle` field of the `VolumeSnapshotContent` object
associated with the base `VolumeSnapshot` object.
This supports storage infrastructures that do not require that
the base `VolumeSnapshot` object exist in the cluster in order to generate
changed block metadata against a later `VolumeSnapshot`.

> Note: It is the backup application's responsibility to determine if the
underlying CSI driver provides this support.
If it does, the backup application should take that into consideration in
its snapshot retention policy, and should save the CSI snapshot handle
somewhere for future use if it deletes the `VolumeSnapshot` object
immediately after it has performed a backup.
Comment on lines +879 to +884
Copy link

@kaovilai kaovilai Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there any consideration to how backup application could delete the underlying snapshot handle from storage infra or is that left to the storage infra application outside the scope of backup application responsibility?

Copy link
Contributor Author

@carlbraganza carlbraganza Nov 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. In discussions in the WG meeting we decided that this issue is beyond the scope of the spec.

That would be something between the backup application and the storage infrastructure. The spec does not require support for 0 snapshot retention to exist; this change merely allows CBT to be used in such a circumstance.

In practical terms, in the only supported case that I'm aware of (VMware), and I believe there is no need to "delete" the previous snapshot handle, because it is just a tag in the disk file metadata.


The full specification of the Kubernetes SnapshotMetadata API will be
published in the source code repository of the
[external-snapshot-metadata sidecar](#the-external-snapshot-metadata-sidecar).
Expand Down