[cinder-csi-plugin] Update ignore-volume-az docs (#2985)

* docs: Add troubleshooting steps for AZ mismatches

Signed-off-by: Stephen Finucane <[email protected]>

* docs: Correct nits with Cinder CSI docs

Signed-off-by: Stephen Finucane <[email protected]>

---------

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

docs/cinder-csi-plugin/features.md

@@ -41,7 +41,7 @@ For usage, refer [sample app](./examples.md#use-topology)
 
 ## Block Volume
 
-Cinder volumes to be exposed inside containers as a block device instead of as a mounted file system. The corresponding CSI feature (CSIBlockVolume) is GA since Kubernetes 1.18.
+Cinder volumes to be exposed inside containers as a block device instead of as a mounted file system. The corresponding CSI feature (CSIBlockVolume) is GA since Kubernetes v1.18.
 
 Prerequisites to use the feature:
 * Make sure the volumeMode is `Block` in Persistence Volume Claim Spec
@@ -54,19 +54,20 @@ For usage, refer [sample app](./examples.md#using-block-volume)
 Driver supports both `Offline` and `Online` resize of cinder volumes. Cinder online resize support is available since cinder 3.42 microversion. 
 The same should be supported by underlying OpenStack Cloud to avail the feature.
 
-* As of kubernetes v1.16, Volume Expansion is a beta feature and enabled by default.
+* As of Kubernetes v1.16, Volume Expansion is a beta feature and enabled by default.
 * Make sure to set `allowVolumeExpansion` to `true` in Storage class spec.
-* For usage, refer [sample app](./examples.md#volume-expansion-example)
+
+For usage, refer [sample app](./examples.md#volume-expansion-example)
 
 ### Rescan on in-use volume resize
 
-Some hypervizors (like VMware) don't automatically send a new volume size to a Linux kernel, when a volume is in-use. Sending a "1" to `/sys/class/block/XXX/device/rescan` is telling the SCSI block device to refresh it's information about where it's ending boundary is (among other things) to give the kernel information about it's updated size. When a `rescan-on-resize` flag is set in a CSI node driver cloud-config `[BlockStorage]` section, a CSI node driver will rescan block device and verify its size before expanding the filesystem. CSI driver will raise an error, when expected volume size cannot be detected.
+Some hypervisors (like VMware) don't automatically send a new volume size to a Linux kernel, when a volume is in-use. Sending a "1" to `/sys/class/block/XXX/device/rescan` is telling the SCSI block device to refresh it's information about where it's ending boundary is (among other things) to give the kernel information about it's updated size. When a `rescan-on-resize` flag is set in a CSI node driver cloud-config `[BlockStorage]` section, a CSI node driver will rescan block device and verify its size before expanding the filesystem. CSI driver will raise an error, when expected volume size cannot be detected.
 
-Not all hypervizors have a `/sys/class/block/XXX/device/rescan` location, therefore if you enable this option and your hypervizor doesn't support this, you'll get a warning log on resize event. It is recommended to disable this option in this case.
+Not all hypervisors have a `/sys/class/block/XXX/device/rescan` location, therefore if you enable this option and your hypervisor doesn't support this, you'll get a warning log on resize event. It is recommended to disable this option in this case.
 
 ## Volume Snapshots
 
-This feature enables creating volume snapshots and restore volume from snapshot. The corresponding CSI feature (VolumeSnapshotDataSource) is GA since kubernetes 1.20.
+This feature enables creating volume snapshots and restore volume from snapshot. The corresponding CSI feature (VolumeSnapshotDataSource) is GA since Kubernetes v1.20.
 
 * To avail the feature. deploy the snapshot-controller and CRDs as part of their Kubernetes cluster management process (independent of any CSI Driver) . For more info, refer [Snapshot Controller](https://kubernetes-csi.github.io/docs/snapshot-controller.html)
 * For example on using snapshot feature, refer [sample app](./examples.md#snapshot-create-and-restore)
@@ -77,7 +78,7 @@ Two different Kubernetes features allow volumes to follow the Pod's lifecycle: C
 
 ### [DEPRECATED] CSI Ephemeral Volumes
 
-**Note: This feature support is deprecated in 1.24 release in favor of [Generic Ephemeral Volumes](#generic-ephemeral-volumes) and will no longer be available from 1.27.**
+**Note: This feature support is deprecated in v1.24 release in favor of [Generic Ephemeral Volumes](#generic-ephemeral-volumes) and will no longer be available from v1.27.**
 
 This feature allows CSI volumes to be directly embedded in the Pod specification instead of a PersistentVolume. Volumes specified in this way are ephemeral and do not persist across Pod restarts.
 
@@ -98,7 +99,7 @@ This feature enables cloning a volume from existing PVCs in Kubernetes. As of Ku
 
 Prerequisites:
 * The source PVC must be bound and available (not in use).
-* source and destination PVCs must be in the same namespace.
+* Source and destination PVCs must be in the same namespace.
 * Cloning is only supported within the same Storage Class. Destination volume must be the same storage class as the source
 
 For example, refer [sample app](../../examples/cinder-csi-plugin/clone)
@@ -113,6 +114,6 @@ This should enable to attach a volume to multiple hosts/servers simultaneously.
 
 ## Liveness probe
 
-The [liveness probe](https://github.com/kubernetes-csi/livenessprobe) is a sidecar container that exposes an HTTP /healthz endpoint, which serves as kubelet's livenessProbe hook to monitor health of a CSI driver.
+The [liveness probe](https://github.com/kubernetes-csi/livenessprobe) is a sidecar container that exposes an HTTP `/healthz` endpoint, which serves as kubelet's `livenessProbe` hook to monitor health of a CSI driver.
 
 Cinder CSI driver added liveness probe side container by default and refer to [manifest](../../manifests/cinder-csi-plugin/cinder-csi-controllerplugin.yaml) and [charts](../../charts/cinder-csi-plugin) for more information.

docs/cinder-csi-plugin/multi-region-clouds.md

@@ -5,6 +5,7 @@
 Create a configuration file with a subsection per openstack cluster to manage (pay attention to enable ignore-volume-az in BlockStorage section).
 
 Example of configuration with 3 regions (The default is backward compatible with mono cluster configuration but not mandatory).
+
 ```yaml
 apiVersion: v1
 kind: Secret

docs/cinder-csi-plugin/troubleshooting.md

@@ -17,3 +17,10 @@ The error likely can be spotted as a 403 in the logs.
 
 In that case. The section `nova` in [`cinder.conf`](https://docs.openstack.org/cinder/latest/configuration/block-storage/samples/cinder.conf.html)
 must be configured properly, and with a user with sufficient privileges.
+
+## When trying to use the topology feature, pods are not able to schedule
+
+The Controller plugin reports the AZ of the host VM - a Compute (Nova) AZ retrieved from either the [config drive or the metadata service](https://docs.openstack.org/nova/latest/user/metadata.html) - to provide the accessible topology of the node. This AZ is then used when generating Volume create requests for the Block Storage (Cinder) service. For this to work as expected, the set of Compute and Block Storage AZs must match. If they do not - and you do not have the ability to re-configure the OpenStack deployment to change this - then you must do one of the following.
+
+* Disable the topology feature by passing the `--with-topology=false` option to both the node driver (to prevent it reporting topology information) and controller (to prevent it requesting AZs from Cinder) services.
+* Set the `availability` parameter on the Storage Class(es) and configure the `[BlockStorage] ignore-volume-az` config option for the controller plugin. The former overrides the topology value reported from the node driver and will be used instead when creating the Cinder Volume. The latter ensure the topology value reported from the node driver *is* used for the CSI Volume topology value. Failure to configure the latter will result in the Cinder Volume's AZ being used for the CSI Volume, which will cause any pods using the volume (via a PV) to be unschedulable due to the AZ mismatch.

docs/cinder-csi-plugin/using-cinder-csi-plugin.md

@@ -151,13 +151,13 @@ For Cinder CSI Plugin to authenticate with OpenStack Keystone, required paramete
 These configuration options pertain to block storage and should appear in the `[BlockStorage]` section of the `$CLOUD_CONFIG` file.
 
 * `node-volume-attach-limit`
-  Optional. To configure maximum volumes that can be attached to the node. Its default value is `256`.
+  Optional. To configure maximum volumes that can be attached to the node. Defaults to `256`.
 * `rescan-on-resize`
-  Optional. Set to `true`, to rescan block device and verify its size before expanding the filesystem. Not all hypervizors have a /sys/class/block/XXX/device/rescan location, therefore if you enable this option and your hypervizor doesn't support this, you'll get a warning log on resize event. It is recommended to disable this option in this case. Defaults to `false`
+  Optional. Set to `true` to rescan block device and verify its size before expanding the filesystem. Not all hypervisors have a `/sys/class/block/XXX/device/rescan` location, therefore if you enable this option and your hypervisor doesn't support this, you'll get a warning log on resize event. It is recommended to disable this option in this case. Defaults to `false`
 * `ignore-volume-az`
-  Optional. When `Topology` feature enabled, by default, PV volume node affinity is populated with volume accessible topology, which is volume AZ. But, some of the openstack users do not have compute zones named exactly the same as volume zones. This might cause pods to go in pending state as no nodes available in volume AZ. Enabling `ignore-volume-az=true`, ignores volumeAZ and schedules on any of the available node AZ. Default `false`. Check `cross_az_attach` in [nova configuration](https://docs.openstack.org/nova/latest/configuration/config.html) for further information.
+  Optional. Set to `true` if your set of Block Storage (Cinder) AZs does not match your set of Compute (Nova) AZs and you are manually setting the `topology` parameter on your Storage Class(es). For more information, refer to [When trying to use the topology feature, pods are not able to schedule](./troubleshooting.md#when-trying-to-use-the-topology-feature-pods-are-not-able-to-schedule). Defaults to `false`.
 * `ignore-volume-microversion`
-  Optional. Set to `true` only when your cinder microversion is older than 3.34. This might cause some features to not work as expected, but aims to allow basic operations like creating a volume.
+  Optional. Set to `true` only when your cinder microversion is older than 3.34. This might cause some features to not work as expected, but aims to allow basic operations like creating a volume. Defaults to `false`
 
 ### Metadata
 These configuration options pertain to metadata and should appear in the `[Metadata]` section of the `$CLOUD_CONFIG` file.
@@ -174,7 +174,7 @@ These configuration options pertain to metadata and should appear in the `[Metad
 
 ### Using the manifests
 
-All the manifests required for the deployment of the plugin are found at ```manifests/cinder-csi-plugin```
+All the manifests required for the deployment of the plugin are found at `manifests/cinder-csi-plugin`
 
 Configuration file specified in `$CLOUD_CONFIG` is passed to cinder CSI driver via kubernetes `secret`. If the secret `cloud-config` is already created in the cluster, you can remove the file, `manifests/cinder-csi-plugin/csi-secret-cinderplugin.yaml` and directly proceed to the step of creating controller and node plugins.