From aab788384fc2712ef5347bc5c60e49e419ab9d5c Mon Sep 17 00:00:00 2001 From: Jan Safranek Date: Fri, 15 Mar 2019 17:34:05 +0100 Subject: [PATCH] Third round of review --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 439e74583..28dd8f7f5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # CSI provisioner -The external-provisioner is a sidecar container that dynamically provisions volumes by calling `ControllerCreateVolume` and `ControlerDeleteVolume` functions of CSI drivers. It is necessary because internal persistent volume controller running in Kubernetes controller-manager does not have any direct interfaces to CSI drivers. +The external-provisioner is a sidecar container that dynamically provisions volumes by calling `ControllerCreateVolume` and `ControllerDeleteVolume` functions of CSI drivers. It is necessary because internal persistent volume controller running in Kubernetes controller-manager does not have any direct interfaces to CSI drivers. ## Overview The external-provisioner is an external controller that monitors `PersistentVolumeClaim` objects created by user and creates/deletes volumes for them. Full design can be found at Kubernetes proposal at [container-storage-interface.md](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/storage/container-storage-interface.md) @@ -21,9 +21,9 @@ Various external-provisioner releases come with different alpha / beta features. Following table reflects the head of this branch. -| Feature | Status | Default | Min. K8s version | Description | -| -------- | ------ | ------- | ---------------- | ------------------------------------------------------------------------------------------ | -| Topology | Beta | Off | 1.14 | [Topology aware dynamic provisioning](https://kubernetes-csi.github.io/docs/topology.html) | +| Feature | Status | Default | Min. K8s version | Description | +| -------- | ------- | ------- | ---------------- | ------------------------------------------------------------------------------------------ | +| Topology | Alpha | Off | 1.14 | [Topology aware dynamic provisioning](https://kubernetes-csi.github.io/docs/topology.html) | All other external-provisioner features and the external-provisioner itself is considered GA and fully supported. @@ -46,7 +46,7 @@ Note that the external-provisioner does not scale with more replicas. Only one e * `--enable-leader-election`: Enables leader election. This is useful when there are multiple replicas of the same external-provisioner running for one CSI driver. Only one of them may be active (=leader). A new leader will be re-elected when current leader dies or becomes unresponsive for ~15 seconds. -* `--timeout `: Timeout of all calls to CSI driver. It should be set to value that accommodates majority of `ControllerCreateVolume` and `ControlerDeleteVolume` calls. See [CSI error and timeout handling](#csi-error-and-timeout-handling) for details. 15 seconds is used by default. +* `--timeout `: Timeout of all calls to CSI driver. It should be set to value that accommodates majority of `ControllerCreateVolume` and `ControllerDeleteVolume` calls. See [CSI error and timeout handling](#csi-error-and-timeout-handling) for details. 15 seconds is used by default. * `--retry-interval-start ` - Initial retry interval of failed provisioning or deletion. It doubles with each failure, up to `--retry-interval-max` and then it stops increasing. Default value is 1 second. [CSI error and timeout handling](#csi-error-and-timeout-handling) for details. @@ -63,7 +63,7 @@ Note that the external-provisioner does not scale with more replicas. Only one e * `--volume-name-prefix `: Prefix of PersistentVolume names created by the external-provisioner. Default value is "pvc", i.e. created PersistentVolume objects will have name `pvc-`. -* `--volume-name-uuid-length`: Length of UUID to be added to `--volume-name-prefix`. Defaults behavior is to NOT truncate the UUID. +* `--volume-name-uuid-length`: Length of UUID to be added to `--volume-name-prefix`. Default behavior is to NOT truncate the UUID. * `--version`: Prints current external-provisioner version and quits. @@ -76,16 +76,16 @@ Note that the external-provisioner does not scale with more replicas. Only one e ### CSI error and timeout handling The external-provisioner invokes all gRPC calls to CSI driver with timeout provided by `--timeout` command line argument (15 seconds by default). -Correct timeout value and number of worker threads depends on the storage backend and how quickly it is able to processes `ControllerCreateVolume` and `ControllerDeleteVolume` calls. The value should be set to accommodate majority of them. It is fine if some calls time out - such calls will be re-tried after exponential backoff (starting with 1s by default), however, this backoff will introduce delay when the call times out several times for a single volume. +Correct timeout value and number of worker threads depends on the storage backend and how quickly it is able to processes `ControllerCreateVolume` and `ControllerDeleteVolume` calls. The value should be set to accommodate majority of them. It is fine if some calls time out - such calls will be retried after exponential backoff (starting with 1s by default), however, this backoff will introduce delay when the call times out several times for a single volume. -Frequency of `ControllerCreateVolume` and `ControllerDeleteVolume` retries can be configured by `--retry-interval-start` and `--retry-interval-max` parameters. The external-provisioner starts retries with `retry-interval-start` interval (1s by default) and doubles it with each failure until it reaches `retry-interval-max` (5 minutes by default). The external provisioner stops increasing the retry interval when it reaches `retry-interval-max`, however, it still re-tries provisioning/deletion of a volume until it's provisioned. The external-provisioner keeps its own number of provisioning/deletion failures for each volume. +Frequency of `ControllerCreateVolume` and `ControllerDeleteVolume` retries can be configured by `--retry-interval-start` and `--retry-interval-max` parameters. The external-provisioner starts retries with `retry-interval-start` interval (1s by default) and doubles it with each failure until it reaches `retry-interval-max` (5 minutes by default). The external provisioner stops increasing the retry interval when it reaches `retry-interval-max`, however, it still retries provisioning/deletion of a volume until it's provisioned. The external-provisioner keeps its own number of provisioning/deletion failures for each volume. The external-provisioner can invoke up to `--worker-threads` (100 by default) `ControllerCreateVolume` **and** up to `--worker-threads` `ControllerDeleteVolume` calls in parallel, i.e. these two calls are counted separately. The external-provisioner assumes that the storage backend can cope with such high number of parallel requests and that the requests are handled in relatively short time (ideally sub-second). Lower value should be used for storage backends that expect slower processing related to newly created / deleted volumes or can handle lower amount of parallel calls. Details of error handling of individual CSI calls: -* `ControllerCreateVolume`: The call might have timed out just before the driver provisioned a volume and was sending a response. From that reason, timeouts from `ControllerCreateVolume` is considered as "*volume may be provisioned*" or "*volume is being provisioned in the background*." The external-provisioner will re-try calling `ControllerCreateVolume` after exponential backoff until it gets either successful response or final (non-timeout) error that the volume cannot be created. -* `ControllerDeleteVolume`: This is similar to `ControllerCreateVolume`, The external-provisioner will re-try calling `ControllerDeleteVolume` with exponential backoff after timeout until it gets either successful response or a final error that the volume cannot be deleted. -* `Probe`: The external-provisioner re-tries calling Probe until the driver reports it's ready. It re-tries also when it receives timeout from `Probe` call. The external-provisioner has no limit of retries. It is expected that ReadinessProbe on the driver container will catch case when the driver takes too long time to get ready. +* `ControllerCreateVolume`: The call might have timed out just before the driver provisioned a volume and was sending a response. From that reason, timeouts from `ControllerCreateVolume` is considered as "*volume may be provisioned*" or "*volume is being provisioned in the background*." The external-provisioner will retry calling `ControllerCreateVolume` after exponential backoff until it gets either successful response or final (non-timeout) error that the volume cannot be created. +* `ControllerDeleteVolume`: This is similar to `ControllerCreateVolume`, The external-provisioner will retry calling `ControllerDeleteVolume` with exponential backoff after timeout until it gets either successful response or a final error that the volume cannot be deleted. +* `Probe`: The external-provisioner retries calling Probe until the driver reports it's ready. It retries also when it receives timeout from `Probe` call. The external-provisioner has no limit of retries. It is expected that ReadinessProbe on the driver container will catch case when the driver takes too long time to get ready. * `GetPluginInfo`, `GetPluginCapabilitiesRequest`, `ControllerGetCapabilities`: The external-provisioner expects that these calls are quick and does not retry them on any error, including timeout. Instead, it assumes that the driver is faulty and exits. Note that Kubernetes will likely start a new provisioner container and it will start with `Probe` call. ## Community, discussion, contribution, and support