CSI external-snapshot-metadata

Status and Releases

Git Repository: https://github.com/kubernetes-csi/external-snapshot-metadata

Supported Versions

Alpha

Description

This sidecar securely serves snapshot metadata to Kubernetes clients through the Kubernetes SnapshotMetadata Service API. This API is similar to the CSI SnapshotMetadata Service but is designed to be used by Kuberetes authenticated and authorized backup applications. Its protobuf specification is available in the sidecar repository.

The sidecar authenticates and authorizes each Kubernetes backup application request made through the Kubernetes SnapshotMetadata Service API. It then acts as a proxy as it fetches the desired metadata from the CSI driver and streams it directly to the requesting application with no load on the Kubernetes API server.

See "The External Snapshot Metadata Sidecar" section in the CSI Changed Block Tracking KEP for additional details on the sidecar.

Usage

Backup applications, identified by their authorized ServiceAccount objects, directly communicate with the sidecar using the Kubernetes SnapshotMetadata Service API. The authorization needed is described in the "Risks and Mitigations" section of the CSI Changed Block Tracking KEP. In particular, this requires the ability to use the Kubernetes TokenRequest API and to access the objects required to use the API.

The availability of this optional feature is advertised to backup applications by the presence of a Snapshot Metadata Service CR that is named for the CSI driver that provisioned the PersistentVolume and VolumeSnapshot objects involved. The CR contains a gRPC service endpoint and CA certificate, and an audience string for authentication. A backup application must use the Kubernetes TokenRequest API with the audience string to obtain a Kubernetes authentication token for use in the Kubernetes SnapshotMetadata Service API call. The backup application should establish trust for the CA certificate before making the gRPC call to the service endpoint.

The Kubernetes SnapshotMetadata Service API uses a gRPC stream to return VolumeSnapshot metadata to the backup application. Metadata can be lengthy, so the API supports restarting an interrupted metadata request from an intermediate point in case of failure. The Resources section below describes the programming artifacts available to support backup application use of this API.

Deployment

The CSI external-snapshot-metadata sidecar should be deployed by CSI drivers that support the Changed Block Tracking feature. The sidecar must be deployed in the same pod as the CSI driver and will communicate with its gRPC CSI SnapshotMetadata Service and CSI Identity Service over a UNIX domain socket.

The sidecar should be configured to run under the authority of its CSI driver ServiceAccount, which must be authorized as described in the "Risks and Mitigations" section of the CSI Changed Block Tracking KEP. In particular, this requires the ability to use the Kubernetes TokenReview and SubjectAccessReview APIs.

A Service object must be created to expose the endpoints of the Kubernetes SnapshotMetadata Service API gRPC server implemented by the sidecar.

A SnapshotMetadataService CR, named for the CSI driver, must be created to advertise the availability of this optional feature to Kubernetes backup application clients. The CR contains the CA certificate and Service endpoint address of the sidecar and the audience string needed for the client authentication token.

Resources

The external-snapshot-metadata repository contains the protobuf specification of the Kubernetes SnapshotMetadata Service API.

In addition, the repository has a number of useful artifacts to support Go language programs:

• The Go client interface for the Kubernetes SnapshotMetadata Service API.

• The pkg/iterator client helper package. This may be used by backup applications instead of working directly with the Kubernetes SnapshotMetadata Service gRPC client interfaces. The snapshot-metadata-lister example Go command illustrates the use of this helper package.

• Go language CSI SnapshotMetadataService API client mocks.

The sample Hostpath CSI driver has been extended to support the Changed Block Tracking feature and provides an illustration on how to deploy a CSI driver.