cinder: Add prechecks and docs for HA/clustering

Change-Id: I33a3ec11b0cdef94b08cd7551008284755824cb7

ansible/roles/cinder/defaults/main.yml

@@ -356,3 +356,9 @@ cinder_ks_user_roles:
 # TLS
 ####################
 cinder_enable_tls_backend: "{{ kolla_enable_tls_backend }}"
+
+############
+# Clustering
+############
+cinder_cluster_name: ""
+cinder_cluster_skip_precheck: false

ansible/roles/cinder/tasks/precheck.yml

@@ -68,3 +68,28 @@
     - cinder_backup_s3_access_key
     - cinder_backup_s3_secret_key
   when: cinder_backup_driver == "s3"
+
+- name: Check if cinder_cluster_name is configured for HA configurations
+  assert:
+    that:
+      - cinder_cluster_name != ""
+    msg: |
+      Multiple cinder-volume instances detected but cinder_cluster_name is not set- please see
+      https://docs.openstack.org/kolla-ansible/latest/reference/storage/cinder-guide.html#ha
+      for guidance.
+  when:
+    - not cinder_cluster_skip_precheck
+    - groups['cinder-volume'] | length > 1
+
+- name: Check if cinder_cluster_name is configured and configuration is non-HA
+  assert:
+    that:
+      - cinder_cluster_name == ""
+    msg: |
+      Single cinder-volume instance detected but cinder_cluster_name is set (cluster
+      configuration will not be applied) - please see
+      https://docs.openstack.org/kolla-ansible/latest/reference/storage/cinder-guide.html#ha
+      for guidance.
+  when:
+    - not cinder_cluster_skip_precheck
+    - groups['cinder-volume'] | length == 1

ansible/roles/cinder/templates/cinder.conf.j2

@@ -20,6 +20,10 @@ glance_api_servers = {{ glance_internal_endpoint }}
 glance_num_retries = {{ groups['glance-api'] | length }}
 glance_ca_certificates_file = {{ openstack_cacert }}
 
+{% if service_name == "cinder-volume" and cinder_cluster_name != "" %}
+cluster = {{ cinder_cluster_name }}
+{% endif %}
+
 {% if cinder_enabled_backends %}
 enabled_backends = {{ cinder_enabled_backends|map(attribute='name')|join(',') }}
 {% endif %}

doc/source/reference/storage/cinder-guide.rst

@@ -16,6 +16,23 @@ backends:
 * lvm
 * nfs
 
+HA
+~~
+
+When using cinder-volume in an HA configuration (more than one host in
+cinder-volume/storage group):
+
+- Make sure that the driver you are using supports `Active/Active High Availability <https://docs.openstack.org/cinder/|KOLLA_OPENSTACK_RELEASE|/reference/support-matrix.html#operation_active_active_ha>`
+  configuration
+- Add ``cinder_cluster_name: example_cluster_name`` to your ``globals.yml`` (or
+  host_vars for advanced multi-cluster configuration)
+
+.. note::
+
+   In case of non-standard configurations (e.g. mixed HA and non-HA Cinder backends),
+   you can skip the prechecks by setting ``cinder_cluster_skip_precheck`` to
+   ``true``.
+
 LVM
 ~~~
 

releasenotes/notes/cinder-ha-precheck-ca93901f1362ac0d.yaml

@@ -0,0 +1,16 @@
+---
+upgrade:
+  - |
+    A precheck for running Cinder HA has been introduced, which checks
+    for multiple cinder-volume instances and fails when ``cinder_cluster_name``
+    is unset. For details on configuration guidelines please check the
+    `HA section of Cinder guide <https://docs.openstack.org/kolla-ansible/latest/reference/storage/cinder-guide.html#ha>`_.
+    To disable the precheck please set ``cinder_cluster_skip_precheck`` to
+    ``true``.
+features:
+  - |
+    A new variable ``cinder_cluster_name`` which controls the name of
+    cinder-volume High Availability cluster (for those backend drivers
+    that support it).
+    It replaces possible user-defined config overrides that already may have
+    implemented this feature.

tests/templates/globals-default.j2

@@ -141,6 +141,7 @@ enable_rabbitmq: "no"
 {% if scenario == "cephadm" %}
 # kolla-ansible vars
 enable_cinder: "yes"
+cinder_cluster_name: "kolla_ceph"
 # External Ceph
 glance_backend_ceph: "yes"
 cinder_backend_ceph: "yes"