Skip to content

Commit 95a3072

Browse files
carlbraganzacarlbraganza
committed
Documentation on the external-snaphot-metadata sidecar (alpha).
1 parent 1360f37 commit 95a3072

File tree

3 files changed

+97
-0
lines changed

3 files changed

+97
-0
lines changed

‎book/src/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
- [cluster-driver-registrar](cluster-driver-registrar.md) (deprecated)
1919
- [external-health-monitor-controller](external-health-monitor-controller.md)
2020
- [external-health-monitor-agent](external-health-monitor-agent.md)
21+
- [external-snapshot-metadata](external-snapshot-metadata.md)
2122
- [CSI objects](csi-objects.md)
2223
- [CSIDriver Object](csi-driver-object.md)
2324
- [CSINode Object](csi-node-object.md)
@@ -43,6 +44,7 @@
4344
- [CSI Windows](csi-windows.md)
4445
- [Volume Mode Conversion](prevent-volume-mode-conversion.md)
4546
- [Cross-Namespace Data Sources](cross-namespace-data-sources.md)
47+
- [Changed Block Tracking](changed-block-tracking.md)
4648
- [Deploying a CSI Driver on Kubernetes](deploying.md)
4749
- [Example](example.md)
4850
- [Driver Testing](testing-drivers.md)

‎book/src/changed-block-tracking.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changed Block Tracking
2+
3+
## Status
4+
5+
Status | Min K8s Version | Max K8s Version | external-provisioner Version
6+
-------|-----------------|-----------------|-----------------------------
7+
Alpha | 1.32 | - | *Unknown*
8+
9+
10+
## Overview
11+
12+
This optional feature provides a secure mechanism to obtain metadata
13+
on the allocated blocks of a CSI VolumeSnapshot, or the changed blocks between two arbitrary pairs of CSI VolumeSnapshot objects of the same PersistentVolume.
14+
15+
Snapshot metadata must be fetched directly with the
16+
[Kuberenets SnapshotMetadata](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#the-kubernetes-snapshotmetadata-service-api)
17+
gRPC service from an [external-snapshot-metadata](./external-snapshot-metadata.md)
18+
sidecar configured by the CSI driver.
19+
This bypasses the Kubernetes API server for the most part: the API
20+
server is used only to fetch the Kubernetes objects needed for secure, authorized and mutually authenticated communication.
21+
22+
> See the [Kubernetes Enhancement Proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking)
23+
> for details of the Changed Block Tracking feature.

‎book/src/external-snapshot-metadata.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# CSI external-snapshot-metadata
2+
3+
## Status and Releases
4+
5+
**Git Repository:** [https://github.com/kubernetes-csi/external-snapshot-metadata](https://github.com/kubernetes-csi/external-snapshot-metadata)
6+
7+
### Supported Versions
8+
9+
Latest stable release | Branch | Min CSI Version | Max CSI Version | Container Image | [Min K8s Version](project-policies.md#minimum-version) | [Max K8s Version](project-policies.md#maximum-version) | [Recommended K8s Version](project-policies.md#recommended-version) |
10+
--|--|--|--|--|--|--|--
11+
*Unavailable* | *Unavailable* | [v1.10.0](https://github.com/container-storage-interface/spec/releases/tag/v1.10.0) | - |*Unavailable* | v1.32 | - | v1.32
12+
13+
14+
## Alpha
15+
16+
### Description
17+
The sidecar securely serves snapshot metadata to Kubernetes clients through the
18+
[Kubernetes SnapshotMetadata gRPC Service](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#the-kubernetes-snapshotmetadata-service-api).
19+
It handles all aspects of Kubernetes client authentication and authorization necessary, with minimal load on the Kubernetes API server.
20+
21+
See [The External Snapshot Metadata Sidecar](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#the-external-snapshot-metadata-sidecar)
22+
section in the CSI Changed Block Tracking KEP
23+
for additional details on the sidecar.
24+
25+
26+
### Usage
27+
Backup applications communicate with the sidecar using the
28+
[Kubernetes SnapshotMetadata](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#the-kubernetes-snapshotmetadata-service-api)
29+
gRPC service.
30+
To support mutual authentication and authorization, the backup application must trust the CA certificate used by the sidecar and must use the Kubernetes
31+
[TokenRequest](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/)
32+
API with the sidecar's audience string to obtain an authentication token.
33+
34+
The sidecar audience string and CA certificate should be obtained from the
35+
[Snapshot Metadata Service CR](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#snapshot-metadata-service-custom-resource)
36+
named for the CSI driver that provisions the PersistentVolumes involved.
37+
38+
The sidecar authenticates and authorizes each backup application
39+
request, and then acts as a proxy as it fetches the desired metadata from
40+
the CSI driver for that request, and streams it to the requesting application.
41+
42+
### Deployment
43+
The CSI `external-snapshot-metadata` sidecar should be deployed by
44+
CSI drivers that support the
45+
[Changed Block Tracking](./changed-block-tracking.md) feature.
46+
The sidecar must be deployed in the same pod as the CSI driver and
47+
will communicate with its CSI [SnapshotMetadata](https://github.com/container-storage-interface/spec/blob/master/spec.md#snapshot-metadata-service-rpcs)
48+
and [Identity](https://github.com/container-storage-interface/spec/blob/master/spec.md#identity-service-rpc) gRPC services
49+
over a UNIX domain socket.
50+
51+
The sidecar should be configured to run under the authority of its
52+
CSI driver ServiceAccount, which must be authorized as described
53+
in the
54+
[Risks and Mitigations](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#risks-and-mitigations)
55+
section of the CSI Changed Block Tracking KEP.
56+
In particular, this requires the ability to
57+
use the Kubernetes
58+
[TokenReview](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-review-v1/)
59+
and
60+
[SubjectAccessReview](https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/subject-access-review-v1/)
61+
APIs.
62+
63+
A Service object must be created for the TCP based [Kubernetes SnapshotMetadata](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#the-kubernetes-snapshotmetadata-service-api)
64+
gRPC service implemented by the sidecar.
65+
66+
A [SnapshotMetadataService CR](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/3314-csi-changed-block-tracking#snapshot-metadata-service-custom-resource),
67+
named for the CSI driver, must be created to advertise the
68+
availability of this optional feature.
69+
The CR contains the CA certificate and Service endpoint address
70+
of the sidecar and the audience string needed for the client
71+
authentication token.
72+

0 commit comments

Comments
 (0)