Add doc for snapshot validation webhook

xing-yang · xing-yang · commit 671ce6084638 · 2020-11-01T01:10:58.000Z
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -5,6 +5,7 @@
     - [Kubernetes Changelog](kubernetes-changelog.md)
     - [Kubernetes Cluster Controllers](kubernetes-cluster-controllers.md)
         - [Snapshot Controller](snapshot-controller.md)
+        - [Snapshot Validation Webhook](snapshot-validation-webhook.md)
     - [Sidecar Containers](sidecar-containers.md)
         - [Kubernetes Compatibility](kubernetes-compatibility.md)
         - [external-attacher](external-attacher.md)
diff --git a/book/src/snapshot-restore-feature.md b/book/src/snapshot-restore-feature.md
@@ -2,11 +2,11 @@
 
 ## Status
 
-Status | Min K8s Version | Max K8s Version | snapshot-controller Version | CSI external-snapshotter sidecar Version | external-provisioner Version
---|--|--|--|--|--
-Alpha | 1.12 | 1.12 | | 0.4.0 <= version < 1.0 | 0.4.1 <= version < 1.0
-Alpha | 1.13 | 1.16 | | 1.0.1 <= version < 2.0 | 1.0.1 <= version < 1.5
-Beta  | 1.17 | - | 2.0+ | 2.0+ | 1.5+
+Status | Min K8s Version | Max K8s Version | snapshot-controller Version | snapshot-validation-webhook Version | CSI external-snapshotter sidecar Version | external-provisioner Version
+--|--|--|--|--|--|--
+Alpha | 1.12 | 1.12 | | | 0.4.0 <= version < 1.0 | 0.4.1 <= version < 1.0
+Alpha | 1.13 | 1.16 | | | 1.0.1 <= version < 2.0 | 1.0.1 <= version < 1.5
+Beta  | 1.17 | - | 2.0+ | 3.0+ | 2.0+ | 1.5+
 
 ## Overview
 
@@ -37,7 +37,7 @@ The Kubernetes CSI development team maintains the [external-snapshotter](externa
 
 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.
 
-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.
+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.
 
 #### Hightlights in the snapshot v1beta1 APIs
 
@@ -55,15 +55,21 @@ The snapshot controller is deployed by the Kubernetes distributions and is respo
 
 The CSI external-snapshotter sidecar watches Kubernetes VolumeSnapshotContent CRD objects and triggers CreateSnapshot/DeleteSnapshot against a CSI endpoint.
 
+### Snapshot Validation Webhook
+
+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.
+
 ### Kubernetes Cluster Setup
 
 Volume snapshot is promoted to beta in Kubernetes 1.17 so the `VolumeSnapshotDataSource` feature gate is enabled by default.
 
 See the Deployment section of [Snapshot Controller](snapshot-controller.md) on how to set up the snapshot controller and CRDs.
 
+See the Deployment section of [Snapshot Validation Webhook](snapshot-validation-webhook.md) for more details on how to use the webhook.
+
 ### Test Snapshot Feature
 
-To test snapshot Beta version, use the following [example yaml files](https://github.com/kubernetes-csi/external-snapshotter/tree/release-2.0/examples/kubernetes).
+To test snapshot Beta version, use the following [example yaml files](https://github.com/kubernetes-csi/external-snapshotter/tree/release-3.0/examples/kubernetes).
 
 Create a _StorageClass_:
 ```
@@ -90,13 +96,6 @@ Create a _PVC_ from a _VolumeSnapshot_:
 kuberctl create -f restore.yaml
 ```
 
-#### PersistentVolumeClaim not Bound
-
-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.
-
-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.
-
-
 ## Snapshot Alpha
 ### Snapshot APIs
 
diff --git a/book/src/snapshot-validation-webhook.md b/book/src/snapshot-validation-webhook.md
@@ -0,0 +1,27 @@
+# Snapshot Validation Webhook
+
+## Status and Releases
+
+**Git Repository:** [https://github.com/kubernetes-csi/external-snapshotter](https://github.com/kubernetes-csi/external-snapshotter)
+
+**Status:** v3.0.1 (Beta)
+
+### Snapshot Validation Webhook
+
+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.
+
+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)
+--|--|--|--|--|--|--|--
+[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
+
+## Description
+
+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.
+
+> :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.
+
+## Deployment
+
+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).
+
+Read more about how to install the example webhook [here](https://github.com/kubernetes-csi/external-snapshotter/tree/master/deploy/kubernetes/webhook-example).
