[enterprise-4.13] [OSDOCS-5249] TP - Failure domains for ShiftStack

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

@@ -37,6 +37,7 @@ See xref:../installing_openstack/installing-openstack-installer-custom.adoc#inst
 
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
+include::modules/installation-osp-failure-domains-config.adoc[leveloffset=+3]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-deploying-bare-metal-machines.adoc[leveloffset=+2]
 include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]

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

@@ -40,6 +40,7 @@ include::modules/installation-obtaining-installer.adoc[leveloffset=+1]
 include::modules/installation-initializing.adoc[leveloffset=+1]
 include::modules/installation-configure-proxy.adoc[leveloffset=+2]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
+include::modules/installation-osp-failure-domains-config.adoc[leveloffset=+3]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2]
 include::modules/installation-osp-external-lb-config.adoc[leveloffset=+2]

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

@@ -29,6 +29,7 @@ include::modules/installation-osp-bootstrap-machine.adoc[leveloffset=+2]
 include::modules/cluster-entitlements.adoc[leveloffset=+1]
 include::modules/installation-osp-enabling-swift.adoc[leveloffset=+1]
 include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1]
+include::modules/installation-osp-failure-domains-config.adoc[leveloffset=+3]
 include::modules/installation-osp-setting-cloud-provider-options.adoc[leveloffset=+1]
 include::modules/installation-creating-image-restricted.adoc[leveloffset=+1]
 include::modules/installation-initializing.adoc[leveloffset=+1]

installing/installing_openstack/installing-openstack-user-kuryr.adoc

@@ -46,6 +46,7 @@ include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2]
 include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1]
 include::modules/installation-initializing.adoc[leveloffset=+1]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
+include::modules/installation-osp-failure-domains-config.adoc[leveloffset=+3]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-kuryr-config-yaml.adoc[leveloffset=+2]
 include::modules/installation-osp-provider-networks.adoc[leveloffset=+2]

installing/installing_openstack/installing-openstack-user.adoc

@@ -38,6 +38,7 @@ include::modules/installation-osp-accessing-api-no-floating.adoc[leveloffset=+2]
 include::modules/installation-osp-describing-cloud-parameters.adoc[leveloffset=+1]
 include::modules/installation-initializing.adoc[leveloffset=+1]
 include::modules/installation-configuration-parameters.adoc[leveloffset=+1]
+include::modules/installation-osp-failure-domains-config.adoc[leveloffset=+3]
 include::modules/installation-osp-custom-subnet.adoc[leveloffset=+2]
 include::modules/installation-osp-config-yaml.adoc[leveloffset=+2]
 include::modules/installation-osp-fixing-subnet.adoc[leveloffset=+2]

modules/installation-configuration-parameters.adoc

@@ -1073,6 +1073,86 @@ If you deploy to a custom subnet, you cannot specify an external DNS server to t
 
 |A UUID as a string. For example, `fa806b2f-ac49-4bce-b9db-124bc64209bf`.
 |====
+
+[id="installation-configuration-parameters-failure-domains-osp_{context}"]
+== {rh-openstack} parameters for failure domains
+
+:FeatureName: {rh-openstack} failure domains
+[IMPORTANT]
+====
+[subs="attributes+"]
+{FeatureName} is a Technology Preview feature only. Technology Preview features
+are not supported with Red Hat production service level agreements (SLAs) and
+might not be functionally complete. Red Hat does not recommend using them
+in production. These features provide early access to upcoming product
+features, enabling customers to test functionality and provide feedback during
+the development process.
+
+For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope].
+====
+// Undefine {FeatureName} attribute, so that any mistakes are easily spotted
+:!FeatureName:
+
+{rh-openstack-first} deployments do not have a single implementation of failure domains. Instead, availability zones are defined individually for each service, such as the compute service, Nova; the networking service, Neutron; and the storage service, Cinder. 
+
+Beginning with {product-title} 4.13, there is a unified definition of failure domains for {rh-openstack} deployments that covers all supported availability zone types. You can use failure domains to control related aspects of Nova, Neutron, and Cinder configurations from a single place. 
+
+In {rh-openstack}, a port describes a network connection and maps to an interface inside a compute machine. A port also:
+* Is defined by a network or by one more or subnets
+* Connects a machine to one or more subnets
+
+Failure domains group the services of your deployment by using ports. If you use failure domains, each machine connects to:
+* The `portTarget` object with the ID `control-plane` while that object exists.
+* All non-control-plane `portTarget` objects within its own failure domain.
+* All networks in the machine pool's `additionalNetworkIDs` list.
+
+To configure failure domains for a machine pool, edit availability zone and port target parameters under `controlPlane.platform.openstack.failureDomains`.
+
+.{rh-openstack} parameters for failure domains
+[cols=".^2,.^3a,.^3a",options="header"]
+|====
+|Parameter|Description|Values
+
+|`platform.openstack.failuredomains.computeAvailabilityZone`
+|An availability zone for the server. If not specified, the cluster default is used.
+|The name of the availability zone. For example, `nova-1`.
+
+|`platform.openstack.failuredomains.storageAvailabilityZone`
+|An availability zone for the root volume. If not specified, the cluster default is used.
+|The name of the availability zone. For example, `cinder-1`.
+
+|`platform.openstack.failuredomains.portTargets`
+|A list of `portTarget` objects,  each of which defines a network connection to attach to machines within a failure domain.
+|A list of `portTarget` objects.
+
+|`platform.openstack.failuredomains.portTargets.portTarget.id`
+|The ID of an individual port target. To select that port target as the first network for machines, set the value of this parameter to `control-plane`. If this parameter has a different value, it is ignored.
+|`control-plane` or an arbitrary string.
+
+|`platform.openstack.failuredomains.portTargets.portTarget.network`
+|Required. The name or ID of the network to attach to machines in the failure domain.
+|A `network` object that contains either a name or UUID. For example:
++
+[source,yaml]
+----
+network:
+  id: 8db6a48e-375b-4caa-b20b-5b9a7218bfe6
+----
++
+or:
++
+[source,yaml]
+----
+network:
+  name: my-network-1
+----
+
+|`platform.openstack.failuredomains.portTargets.portTarget.fixedIPs`
+|Subnets to allocate fixed IP addresses to. These subnets must exist within the same network as the port.
+|A list of `subnet` objects.
+|====
+
+NOTE: You cannot combine zone fields and failure domains. If you want to use failure domains, the `controlPlane.zone` and `controlPlane.rootVolume.zone` fields must be left unset.
 endif::osp[]
 
 ifdef::azure[]

modules/installation-osp-failure-domains-config.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+// * installing/installing_openstack/installing-openstack-*.adoc
+
+:_content-type: PROCEDURE
+[id="installation-osp-failure-domains-config_{context}"]
+= An example installation configuration section that uses failure domains
+
+:FeatureName: {rh-openstack} failure domains
+include::snippets/technology-preview.adoc[]
+
+The following section of an `install-config.yaml` file demonstrates the use of failure domains in a cluster to deploy on {rh-openstack-first}:
+
+[source,yaml]
+----
+...
+controlPlane:
+  name: master
+  platform:
+    openstack:
+      type: m1.large
+      failureDomains:
+      - computeAvailabilityZone: 'nova-1'
+        storageAvailabilityZone: 'cinder-1'
+        portTargets:
+        - id: control-plane
+          network:
+            id: 8db6a48e-375b-4caa-b20b-5b9a7218bfe6
+      - computeAvailabilityZone: 'nova-2'
+        storageAvailabilityZone: 'cinder-2'
+        portTargets:
+        - id: control-plane
+          network:
+            id: 39a7b82a-a8a4-45a4-ba5a-288569a6edd1
+      - computeAvailabilityZone: 'nova-3'
+        storageAvailabilityZone: 'cinder-3'
+        portTargets:
+        - id: control-plane
+          network:
+            id: 8e4b4e0d-3865-4a9b-a769-559270271242
+featureSet: TechPreviewNoUpgrade
+...
+----