Skip to content

Commit 671ce60

Browse files
committed
Add doc for snapshot validation webhook
1 parent afb5ad8 commit 671ce60

File tree

3 files changed

+41
-14
lines changed

3 files changed

+41
-14
lines changed

book/src/SUMMARY.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- [Kubernetes Changelog](kubernetes-changelog.md)
66
- [Kubernetes Cluster Controllers](kubernetes-cluster-controllers.md)
77
- [Snapshot Controller](snapshot-controller.md)
8+
- [Snapshot Validation Webhook](snapshot-validation-webhook.md)
89
- [Sidecar Containers](sidecar-containers.md)
910
- [Kubernetes Compatibility](kubernetes-compatibility.md)
1011
- [external-attacher](external-attacher.md)

book/src/snapshot-restore-feature.md

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,11 @@
22

33
## Status
44

5-
Status | Min K8s Version | Max K8s Version | snapshot-controller Version | CSI external-snapshotter sidecar Version | external-provisioner Version
6-
--|--|--|--|--|--
7-
Alpha | 1.12 | 1.12 | | 0.4.0 <= version < 1.0 | 0.4.1 <= version < 1.0
8-
Alpha | 1.13 | 1.16 | | 1.0.1 <= version < 2.0 | 1.0.1 <= version < 1.5
9-
Beta | 1.17 | - | 2.0+ | 2.0+ | 1.5+
5+
Status | Min K8s Version | Max K8s Version | snapshot-controller Version | snapshot-validation-webhook Version | CSI external-snapshotter sidecar Version | external-provisioner Version
6+
--|--|--|--|--|--|--
7+
Alpha | 1.12 | 1.12 | | | 0.4.0 <= version < 1.0 | 0.4.1 <= version < 1.0
8+
Alpha | 1.13 | 1.16 | | | 1.0.1 <= version < 2.0 | 1.0.1 <= version < 1.5
9+
Beta | 1.17 | - | 2.0+ | 3.0+ | 2.0+ | 1.5+
1010

1111
## Overview
1212

@@ -37,7 +37,7 @@ The Kubernetes CSI development team maintains the [external-snapshotter](externa
3737

3838
With the promotion of Volume Snapshot to beta, the feature is now enabled by default on standard Kubernetes deployments instead of being opt-in. This involves a revamp of volume snapshot APIs.
3939

40-
The schema definition for the custom resources (CRs) can be found [here](https://github.com/kubernetes-csi/external-snapshotter/blob/release-2.0/pkg/apis/volumesnapshot/v1beta1/types.go). The CRDs are no longer automatically deployed by the sidecar. They should be installed by the Kubernetes distributions.
40+
The schema definition for the custom resources (CRs) can be found [here](https://github.com/kubernetes-csi/external-snapshotter/blob/release-3.0/client/apis/volumesnapshot/v1beta1/types.go). The CRDs are no longer automatically deployed by the sidecar. They should be installed by the Kubernetes distributions.
4141

4242
#### Hightlights in the snapshot v1beta1 APIs
4343

@@ -55,15 +55,21 @@ The snapshot controller is deployed by the Kubernetes distributions and is respo
5555

5656
The CSI external-snapshotter sidecar watches Kubernetes VolumeSnapshotContent CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.
5757

58+
### Snapshot Validation Webhook
59+
60+
There is a new validating webhook server which provides tightened validation on snapshot objects. This SHOULD be installed by the Kubernetes distros along with the snapshot-controller, not end users. It SHOULD be installed in all Kubernetes clusters that has the snapshot feature enabled. See [Snapshot Validation Webhook](snapshot-validation-webhook.md) for more details on how to use the webhook.
61+
5862
### Kubernetes Cluster Setup
5963

6064
Volume snapshot is promoted to beta in Kubernetes 1.17 so the `VolumeSnapshotDataSource` feature gate is enabled by default.
6165

6266
See the Deployment section of [Snapshot Controller](snapshot-controller.md) on how to set up the snapshot controller and CRDs.
6367

68+
See the Deployment section of [Snapshot Validation Webhook](snapshot-validation-webhook.md) for more details on how to use the webhook.
69+
6470
### Test Snapshot Feature
6571

66-
To test snapshot Beta version, use the following [example yaml files](https://github.com/kubernetes-csi/external-snapshotter/tree/release-2.0/examples/kubernetes).
72+
To test snapshot Beta version, use the following [example yaml files](https://github.com/kubernetes-csi/external-snapshotter/tree/release-3.0/examples/kubernetes).
6773

6874
Create a _StorageClass_:
6975
```
@@ -90,13 +96,6 @@ Create a _PVC_ from a _VolumeSnapshot_:
9096
kuberctl create -f restore.yaml
9197
```
9298

93-
#### PersistentVolumeClaim not Bound
94-
95-
If a `PersistentVolumeClaim` is not bound, the attempt to create a volume snapshot from that `PersistentVolumeClaim` will fail. No retries will be attempted. An event will be logged to indicate that the `PersistentVolumeClaim` is not bound.
96-
97-
Note that this could happen if the `PersistentVolumeClaim` spec and the `VolumeSnapshot` spec are in the same YAML file. In this case, when the `VolumeSnapshot` object is created, the `PersistentVolumeClaim` object is created but volume creation is not complete and therefore the `PersistentVolumeClaim` is not yet bound. You must wait until the `PersistentVolumeClaim` is bound and then create the snapshot.
98-
99-
10099
## Snapshot Alpha
101100
### Snapshot APIs
102101

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Snapshot Validation Webhook
2+
3+
## Status and Releases
4+
5+
**Git Repository:** [https://github.com/kubernetes-csi/external-snapshotter](https://github.com/kubernetes-csi/external-snapshotter)
6+
7+
**Status:** v3.0.1 (Beta)
8+
9+
### Snapshot Validation Webhook
10+
11+
There is a new validating webhook server which provides tightened validation on snapshot objects. This SHOULD be installed by the Kubernetes distros along with the snapshot-controller, not end users. It SHOULD be installed in all Kubernetes clusters that has the snapshot feature enabled.
12+
13+
Latest stable release | Branch | Min CSI Version | Max CSI Version | Container Image | [Min K8s Version](kubernetes-compatibility.md#minimum-version) | [Max K8s Version](kubernetes-compatibility.md#maximum-version) | [Recommended K8s Version](kubernetes-compatibility.md#recommended-version)
14+
--|--|--|--|--|--|--|--
15+
[snapshot-validation-webhook v3.0.1](https://github.com/kubernetes-csi/external-snapshotter/releases/tag/v3.0.1) | [release-3.0](https://github.com/kubernetes-csi/external-snapshotter/tree/release-3.0) | [v1.0.0](https://github.com/container-storage-interface/spec/releases/tag/v1.0.0) | - | k8s.gcr.io/sig-storage/snapshot-validation-webhook:v3.0.1 | v1.17 | - | v1.17
16+
17+
## Description
18+
19+
The snapshot validating webhook is an HTTP callback which responds to [admission requests](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/). It is part of a larger [plan](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1900-volume-snapshot-validation-webhook) to tighten validation for volume snapshot objects. This webhook introduces the [ratcheting validation](https://github.com/kubernetes/enhancements/tree/master/keps/sig-storage/1900-volume-snapshot-validation-webhook#backwards-compatibility) mechanism targeting the tighter validation. The cluster admin or Kubernetes distribution admin should install the webhook alongside the snapshot controllers and CRDs.
20+
21+
> :warning: **WARNING**: Cluster admins choosing not to install the webhook server and participate in the phased release process can cause future problems when upgrading from `v1beta1` to `v1` volumesnapshot API, if there are currently persisted objects which fail the new stricter validation. Potential impacts include being unable to delete invalid snapshot objects.
22+
23+
## Deployment
24+
25+
Kubernetes distributors should bundle and deploy the snapshot validation webhook along with the snapshot controller and CRDs as part of their Kubernetes cluster management process (independent of any CSI Driver).
26+
27+
Read more about how to install the example webhook [here](https://github.com/kubernetes-csi/external-snapshotter/tree/master/deploy/kubernetes/webhook-example).

0 commit comments

Comments
 (0)