DNM: [OCPSTRAT-3035]: Add OpenStack availability zone enablement for IPI installation

installing/installing_openstack/installing-openstack-installer-custom.adoc

@@ -40,6 +40,15 @@ include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+
 
 include::modules/installation-osp-setting-cloud-provider-options.adoc[leveloffset=+1]
 
+include::modules/installation-osp-availability-zones.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../installing/installing_openstack/installation-config-parameters-openstack.adoc#installation-config-parameters-openstack[Installation configuration parameters for {rh-openstack}]
+
+* xref:../../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-openstack.adoc#cpmso-yaml-failure-domain-openstack_cpmso-config-options-openstack[Sample {rh-openstack-first} failure domain configuration for the Control Plane Machine Set Operator]
+
 include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 
 include::modules/installation-initializing.adoc[leveloffset=+1]
@@ -69,6 +78,9 @@ After you deploy your cluster, you can attach pods to additional networks. For m
 
 include::modules/installation-osp-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-osp-multiaz-config-yaml.adoc[leveloffset=+2]
+
+include::modules/installation-osp-configuring-availability-zones.adoc[leveloffset=+2]
 
 //Dual-stack networking
 include::modules/install-osp-dualstack.adoc[leveloffset=+2]

installing/installing_openstack/installing-openstack-installer-restricted.adoc

@@ -39,6 +39,15 @@ include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+
 
 include::modules/installation-osp-setting-cloud-provider-options.adoc[leveloffset=+1]
 
+include::modules/installation-osp-availability-zones.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../installing/installing_openstack/installation-config-parameters-openstack.adoc#installation-config-parameters-openstack[Installation configuration parameters for {rh-openstack}]
+
+* xref:../../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-openstack.adoc#cpmso-yaml-failure-domain-openstack_cpmso-config-options-openstack[Sample {rh-openstack-first} failure domain configuration for the Control Plane Machine Set Operator]
+
 include::modules/installation-creating-image-restricted.adoc[leveloffset=+1]
 
 include::modules/installation-initializing.adoc[leveloffset=+1]
@@ -51,6 +60,8 @@ include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 
 include::modules/installation-osp-restricted-config-yaml.adoc[leveloffset=+2]
 
+include::modules/installation-osp-configuring-availability-zones.adoc[leveloffset=+2]
+
 // include::modules/installation-osp-setting-worker-affinity.adoc[leveloffset=+1]
 include::modules/ssh-agent-using.adoc[leveloffset=+1]
 

modules/installation-initializing.adoc

@@ -365,6 +365,19 @@ ifdef::osp[]
 ... Specify a {rh-openstack} flavor with at least 16 GB RAM to use for control plane nodes
 and 8 GB RAM for compute nodes.
 +
+ifeval::["{context}" == "installing-openstack-installer-custom"]
+[NOTE]
+====
+After you create the installation configuration file, you can modify the file to deploy machines across multiple {rh-openstack} availability zones. For more information, see "{rh-openstack} availability zone enablement".
+====
+endif::[]
+ifeval::["{context}" == "installing-openstack-installer-restricted"]
+[NOTE]
+====
+After you create the installation configuration file, you can modify the file to deploy machines across multiple {rh-openstack} availability zones. For more information, see "{rh-openstack} availability zone enablement".
+====
+endif::[]
++
 ... Select the base domain to deploy the cluster to. All DNS records will be
 sub-domains of this base and will also include the cluster name.
 endif::osp[]

modules/installation-osp-availability-zones.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+// * installing/installing_openstack/installing-openstack-installer-restricted.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="installation-osp-availability-zones_{context}"]
+= {rh-openstack} availability zone enablement
+
+You can deploy an {product-title} cluster across multiple {rh-openstack-first} availability zones (AZs) by configuring Nova compute placement and Cinder root volume placement in the installation configuration file. Spreading control plane and compute machines across AZs reduces the risk that a failure in a single compute or storage failure domain takes down the cluster.
+
+[IMPORTANT]
+====
+Availability zones in {rh-openstack} do not inherently guarantee physical fault isolation. The isolation boundary depends on how your {rh-openstack} administrator configured the zones. Confirm with your cloud provider which failure domains each AZ represents before you rely on them for high availability.
+====
+
+The default installation configuration deploys machines by using the default Nova and Cinder settings for your cloud. Those defaults often place the cluster in a single effective failure domain. To deploy a cluster across multiple availability zones, you must edit the `install-config.yaml` file so that each machine pool specifies Nova `zones` and matching Cinder `rootVolume.zones`.
+
+The `install-config.yaml` file includes the following fields for availability zone placement:
+
+* `controlPlane.platform.openstack.zones` and `compute.platform.openstack.zones`: Nova availability zones where the installation program creates machines.
+* `controlPlane.platform.openstack.rootVolume.zones` and `compute.platform.openstack.rootVolume.zones`: Cinder availability zones where the installation program creates root volumes.
+
+[NOTE]
+====
+If you set `zones` for a machine pool and define a `rootVolume` block, you must also set `rootVolume.zones` for that machine pool. Pair each Nova availability zone with a Cinder availability zone that can serve machines in that failure domain. Nova and Cinder zone names do not have to match.
+====
+
+When the number of replicas does not divide evenly across AZs, the installer round-robins placement. For strict high-availability requirements, match the replica count to the AZ count (for example, 3 replicas across 3 AZs).
+
+After installation, the installation program encodes these values into machine resources. Control plane failure domains appear in the `ControlPlaneMachineSet` custom resource as paired Nova and Cinder availability zones. Compute machines use the Nova and Cinder zones that you configured for the compute machine pool.

modules/installation-osp-configuring-availability-zones.adoc

@@ -0,0 +1,100 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+// * installing/installing_openstack/installing-openstack-installer-restricted.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="installation-osp-configuring-availability-zones_{context}"]
+= Configuring availability zones for {rh-openstack}
+
+You can modify the `install-config.yaml` file so that the installation program deploys control plane and compute machines across multiple {rh-openstack-first} availability zones.
+
+.Prerequisites
+
+* You have an existing `install-config.yaml` installation configuration file.
+* Your {rh-openstack} cloud provides multiple Nova availability zones with schedulable compute capacity in each zone.
+* Your {rh-openstack} cloud provides Cinder volume availability zones that you can pair with the Nova availability zones that you plan to use.
+* You have installed and configured the OpenStack command-line interface (`openstack`).
+
+.Procedure
+
+. List the Nova and Cinder availability zones in your cloud:
++
+[source,terminal]
+----
+$ openstack availability zone list --compute
+$ openstack availability zone list --volume
+----
+
+. Edit your `install-config.yaml` file. For each machine pool that you want to spread across availability zones, set `platform.openstack.zones` to the Nova availability zones and `platform.openstack.rootVolume.zones` to the paired Cinder availability zones.
++
+The lists must contain the same number of entries. The installation program pairs zones by position in each list.
++
+[NOTE]
+====
+You can optionally set `platform.openstack.serverGroupPolicy` to `soft-anti-affinity` to spread machines across different compute hosts within an availability zone. This setting does not replace availability zone placement.
+====
++
+.Sample `install-config.yaml` availability zone configuration
+[%collapsible]
+====
+[source,yaml]
+----
+# ...
+controlPlane:
+  name: master
+  replicas: 3
+  platform:
+    openstack:
+      type: <control_plane_flavor>
+      zones:
+      - <nova_az_0>
+      - <nova_az_1>
+      - <nova_az_2>
+      rootVolume:
+        size: 25
+        types:
+        - <volume_type>
+        zones:
+        - <cinder_az_0>
+        - <cinder_az_1>
+        - <cinder_az_2>
+      serverGroupPolicy: soft-anti-affinity
+compute:
+- name: worker
+  replicas: 6
+  platform:
+    openstack:
+      type: <compute_flavor>
+      zones:
+      - <nova_az_0>
+      - <nova_az_1>
+      - <nova_az_2>
+      rootVolume:
+        size: 25
+        types:
+        - <volume_type>
+        zones:
+        - <cinder_az_0>
+        - <cinder_az_1>
+        - <cinder_az_2>
+      serverGroupPolicy: soft-anti-affinity
+# ...
+----
+====
+
+. Change to the directory that contains the installation program and generate manifests to validate the configuration:
++
+[source,terminal]
+----
+$ ./openshift-install create manifests --dir <installation_directory>
+----
+
+. Optional: Inspect the generated `ControlPlaneMachineSet` manifest in `<installation_directory>/openshift/` and confirm that `failureDomains.openstack` lists the Nova and Cinder availability zone pairs that you configured.
+
+[role="_additional-resources"]
+.Additional resources
+
+* xref:../../machine_management/control_plane_machine_management/cpmso_provider_configurations/cpmso-config-options-openstack.adoc#cpmso-yaml-failure-domain-openstack_cpmso-config-options-openstack[Sample {rh-openstack-first} failure domain configuration for the Control Plane Machine Set Operator]
+
+* xref:../../installing/installing_openstack/installation-config-parameters-openstack.adoc#installation-config-parameters-openstack[Installation configuration parameters for {rh-openstack}]

modules/installation-osp-multiaz-config-yaml.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-installer-custom.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="installation-osp-multiaz-config-yaml_{context}"]
+= Sample multi-AZ install-config.yaml file for {rh-openstack}
+
+The following example `install-config.yaml` file deploys a highly available cluster across three {rh-openstack-first} availability zones. The example pairs Nova availability zones with Cinder root volume availability zones for the control plane and compute machine pools.
+
+[IMPORTANT]
+This sample file is provided for reference only. You must obtain your `install-config.yaml` file by using the installation program. Replace availability zone names, flavors, volume types, and other values with settings from your cloud.
+
+.Example multi-AZ `install-config.yaml` file
+[%collapsible]
+====
+[source,yaml]
+----
+apiVersion: v1
+baseDomain: example.com
+controlPlane:
+  name: master
+  replicas: 3
+  platform:
+    openstack:
+      type: m1.xlarge
+      zones:
+      - nova-az0
+      - nova-az1
+      - nova-az2
+      rootVolume:
+        size: 25
+        types:
+        - performance
+        zones:
+        - cinder-az0
+        - cinder-az1
+        - cinder-az2
+      serverGroupPolicy: soft-anti-affinity
+compute:
+- name: worker
+  replicas: 6
+  platform:
+    openstack:
+      type: m1.large
+      zones:
+      - nova-az0
+      - nova-az1
+      - nova-az2
+      rootVolume:
+        size: 25
+        types:
+        - performance
+        zones:
+        - cinder-az0
+        - cinder-az1
+        - cinder-az2
+      serverGroupPolicy: soft-anti-affinity
+metadata:
+  name: multiaz
+networking:
+  clusterNetwork:
+  - cidr: 10.128.0.0/14
+    hostPrefix: 23
+  machineNetwork:
+  - cidr: 10.0.0.0/16
+  serviceNetwork:
+  - 172.30.0.0/16
+  networkType: OVNKubernetes
+platform:
+  openstack:
+    cloud: mycloud
+    externalNetwork: external
+ifndef::openshift-origin[]
+fips: false
+endif::openshift-origin[]
+pullSecret: '{"auths": ...}'
+sshKey: ssh-ed25519 AAAA...
+----
+====
+
+For more information about configuring availability zones, see xref:installation-osp-configuring-availability-zones_{context}[Configuring availability zones for {rh-openstack}].