Merge pull request #66212 from maxwelldb/cpms-shiftstack-OSDOCS6989

[OSDOCS-6989] Control plane machine sets for clusters on RHOSP

Author: maxwelldb

machine_management/control_plane_machine_management/cpmso-about.adoc

@@ -25,7 +25,7 @@ The Control Plane Machine Set Operator has the following limitations:
 
 * The Operator requires the Machine API Operator to be operational and is therefore not supported on clusters with manually provisioned machines. When installing a {product-title} cluster with manually provisioned machines for a platform that creates an active generated `ControlPlaneMachineSet` custom resource (CR), you must remove the Kubernetes manifest files that define the control plane machine set as instructed in the installation process.
 
-* Only Amazon Web Services (AWS), Google Cloud Platform (GCP), {ibmpowerProductName} Virtual Server, Microsoft Azure, Nutanix, and VMware vSphere clusters are supported.
+* Only Amazon Web Services (AWS), Google Cloud Platform (GCP), {ibmpowerProductName} Virtual Server, Microsoft Azure, Nutanix, VMware vSphere, and {rh-openstack-first} clusters are supported.
 
 * Only clusters with three control plane machines are supported.
 

machine_management/control_plane_machine_management/cpmso-configuration.adoc

@@ -33,6 +33,8 @@ The `<platform_provider_spec>` and `<platform_failure_domains>` sections of the
 
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-vsphere_cpmso-configuration[Sample YAML snippets for configuring VMware vSphere clusters]
 
+* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-openstack_cpmso-configuration[Sample YAML snippets for configuring {rh-openstack-first} clusters]
+
 [id="cpmso-sample-yaml-aws_{context}"]
 == Sample YAML for configuring Amazon Web Services clusters
 
@@ -94,3 +96,14 @@ Some sections of the control plane machine set CR are provider-specific. The fol
 
 //Sample VMware vSphere provider specification
 include::modules/cpmso-yaml-provider-spec-vsphere.adoc[leveloffset=+2]
+
+[id="cpmso-sample-yaml-openstack_{context}"]
+== Sample YAML for configuring {rh-openstack-first} clusters
+
+Some sections of the control plane machine set CR are provider-specific. The following example YAML snippets show provider specification and failure domain configurations for an {rh-openstack} cluster.
+
+//Sample OpenStack provider specification
+include::modules/cpmso-yaml-provider-spec-openstack.adoc[leveloffset=+2]
+
+//Sample OpenStack failure domain configuration
+include::modules/cpmso-yaml-failure-domain-openstack.adoc[leveloffset=+2]

machine_management/control_plane_machine_management/cpmso-getting-started.adoc

@@ -52,12 +52,17 @@ The status of the control plane machine set after installation depends on your c
 |
 |
 |X
+
+|{rh-openstack-first}
+|X ^[3]^
+|X
+|
 |====
 [.small]
 --
 1. AWS clusters that are upgraded from version 4.11 or earlier require xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[CR activation].
 2. GCP and Azure clusters that are upgraded from version 4.12 or earlier require xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[CR activation].
-3. Nutanix clusters that are upgraded from version 4.13 or earlier require xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[CR activation].
+3. Nutanix and {rh-openstack} clusters that are upgraded from version 4.13 or earlier require xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-activating_cpmso-getting-started[CR activation].
 --
 
 //Checking the control plane machine set custom resource state
@@ -82,3 +87,4 @@ include::modules/cpmso-creating-cr.adoc[leveloffset=+1]
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-azure_cpmso-configuration[Sample YAML for configuring Microsoft Azure clusters]
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-nutanix_cpmso-configuration[Sample YAML for configuring Nutanix clusters]
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-vsphere_cpmso-configuration[Sample YAML for configuring VMware vSphere clusters]
+* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-openstack_cpmso-configuration[Sample YAML for configuring {rh-openStack-first} clusters]

machine_management/control_plane_machine_management/cpmso-resiliency.adoc

@@ -23,6 +23,8 @@ include::modules/cpmso-failure-domains-provider.adoc[leveloffset=+2]
 
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-yaml-failure-domain-azure_cpmso-configuration[Sample Microsoft Azure failure domain configuration]
 
+* xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-yaml-failure-domain-openstack_cpmso-configuration[Sample {rh-openstack-first} failure domain configuration]
+
 //Balancing control plane machines
 include::modules/cpmso-failure-domains-balancing.adoc[leveloffset=+2]
 

machine_management/control_plane_machine_management/cpmso-troubleshooting.adoc

@@ -28,4 +28,16 @@ include::modules/cpmso-ts-mhc-etcd-degraded.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state]
+* xref:../../backup_and_restore/control_plane_backup_and_restore/disaster_recovery/scenario-2-restoring-cluster-state.adoc#dr-restoring-cluster-state[Restoring to a previous cluster state]
+
+[id="cpmso-troubleshooting-shiftstack-upgrade_{context}"]
+== Upgrading clusters that run on {rh-openstack}
+
+For clusters that run on {rh-openstack-first} that you upgrade from {product-title} 4.13 to 4.14, you might have to perform post-upgrade tasks before you can use control plane machine sets.
+
+// TODO: Rejigger
+// Post-upgrade config for ShiftStack with machine AZs explicitly defined and rootVolumes w/out AZs
+include::modules/cpmso-openstack-ts-root-volume-azs.adoc[leveloffset=+2]
+
+// Post-upgrade config for ShiftStack with control plane AZs explicitly defined
+include::modules/cpmso-openstack-with-az-config.adoc[leveloffset=+2]

machine_management/control_plane_machine_management/cpmso-using.adoc

@@ -115,6 +115,7 @@ include::modules/machineset-gcp-confidential-vm.adoc[leveloffset=+2]
 
 //Configuring Shielded VM options by using machine sets
 include::modules/machineset-gcp-shielded-vms.adoc[leveloffset=+2]
+
 [role="_additional-resources"]
 .Additional resources
 * link:https://cloud.google.com/compute/shielded-vm/docs/shielded-vm[What is Shielded VM?]
@@ -123,4 +124,12 @@ include::modules/machineset-gcp-shielded-vms.adoc[leveloffset=+2]
 ** link:https://cloud.google.com/compute/shielded-vm/docs/shielded-vm#integrity-monitoring[Integrity monitoring]
 
 //Enabling customer-managed encryption keys for a machine set
-include::modules/machineset-gcp-enabling-customer-managed-encryption.adoc[leveloffset=+2]
+include::modules/machineset-gcp-enabling-customer-managed-encryption.adoc[leveloffset=+2]
+
+[id="cpmso-supported-features-openstack_{context}"]
+== Updating the configuration for {rh-openstack} control plane machines
+
+You can configure {rh-openstack-first} control plane machines by changing the configuration of your control plane machine set. When you save an update to the control plane machine set, the Control Plane Machine Set Operator updates the control plane machines according to your configured update strategy.
+
+//Changing the OpenStack Nova flavor by using a control plane machine set
+include::modules/cpms-changing-openstack-flavor-type.adoc[leveloffset=+2]

modules/cpms-changing-openstack-flavor-type.adoc

@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+// * machine_management/control_plane_machine_management/cpmso-using.adoc
+
+:_content-type: PROCEDURE
+[id="cpms-changing-openstack-flavor-type_{context}"]
+= Changing the {rh-openstack} compute flavor by using a control plane machine set
+
+You can change the {rh-openstack-first} compute service (Nova) flavor that your control plane machines use by updating the specification in the control plane machine set custom resource.
+
+In {rh-openstack}, flavors define the compute, memory, and storage capacity of computing instances. By increasing or decreasing the flavor size, you can scale your control plane vertically.
+
+.Prerequisites
+
+* Your {rh-openstack} cluster uses a control plane machine set.
+
+.Procedure
+
+. Edit the following line under the `providerSpec` field:
++
+[source,yaml]
+----
+providerSpec:
+  value:
+# ...
+    flavor: m1.xlarge <1>
+----
+<1> Specify a {rh-openstack} flavor type that has the same base as the existing selection. For example, you can change `m6i.xlarge` to `m6i.2xlarge` or `m6i.4xlarge`. You can choose larger or smaller flavors depending on your vertical scaling needs.
+
+. Save your changes.
+
+After you save your changes, machines are replaced with ones that use the flavor you chose.

modules/cpmso-creating-cr.adoc

@@ -65,7 +65,7 @@ $ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
 Before you activate the CR, you must ensure that its configuration is correct for your cluster requirements.
 ====
 <3> Specify the update strategy for the cluster. Valid values are `OnDelete` and `RollingUpdate`. The default value is `RollingUpdate`. For more information about update strategies, see "Updating the control plane configuration".
-<4> Specify your cloud provider platform name. Valid values are `AWS`, `Azure`, `GCP`, `Nutanix`, and `VSphere`.
+<4> Specify your cloud provider platform name. Valid values are `AWS`, `Azure`, `GCP`, `Nutanix`, `VSphere`, and `OpenStack`.
 <5> Add the `<platform_failure_domains>` configuration for the cluster. The format and values of this section are provider-specific. For more information, see the sample failure domain configuration for your cloud provider.
 +
 [NOTE]

modules/cpmso-failure-domains-provider.adoc

@@ -2,6 +2,8 @@
 //
 // * machine_management/cpmso-resiliency.adoc
 
+// TODO: See if I can find RHOSP docs links for the proposed changes.
+
 :_content-type: REFERENCE
 [id="cpmso-failure-domains-provider_{context}"]
 = Failure domain platform support and configuration
@@ -33,6 +35,10 @@ The control plane machine set concept of a failure domain is analogous to existi
 |VMware vSphere
 |
 |Not applicable
+
+|{rh-openstack-first}
+|X
+|link:https://docs.openstack.org/nova/2023.2/admin/availability-zones.html[OpenStack Nova availability zones] and link:https://docs.openstack.org/cinder/2023.2/admin/availability-zone-type.html[OpenStack Cinder availability zones]
 |====
 [.small]
 --

modules/cpmso-openstack-ts-root-volume-azs.adoc

@@ -0,0 +1,101 @@
+// Module included in the following assemblies:
+//
+// * machine_management/control_plane_machine_management/cpmso-troubleshooting.adoc
+
+:_content-type: PROCEDURE
+[id="cpmso-openstack-ts-root-volume-azs_{context}"]
+= Configuring {rh-openstack} clusters that have machines with root volume availability zones after an upgrade
+
+For some clusters that run on {rh-openstack-first} that you upgrade, you must manually update machine resources before you can use control plane machine sets if the following configurations are true:
+
+* You upgraded the cluster from {product-title} 4.13 to 4.14.
+ 
+* The cluster infrastructure is installer-provisioned.
+
+* Machines were distributed across multiple availability zones.
+
+* Machines were configured to use root volumes for which block storage availability zones were not defined.
+
+To understand why this procedure is necessary, see link:https://access.redhat.com/solutions/7013893[Solution #7024383].
+
+.Procedure
+
+. For all control plane machines, edit the provider spec for all control plane machines that match the environment. For example, to edit the machine `master-0`, enter the following command:
++
+[source,terminal]
+----
+$ oc edit machine/<cluster_id>-master-0 -n openshift-machine-api
+----
++
+where:
++
+`<cluster_id>`:: Specifies the ID of the upgraded cluster.
+
+. In the provider spec, set the value of the property `rootVolume.availabilityZone` to the volume of the availability zone you want to use.
++
+.An example {rh-openstack} provider spec
+[source,yaml]
+----
+providerSpec:
+  value:
+    apiVersion: machine.openshift.io/v1alpha1
+    availabilityZone: az0
+      cloudName: openstack
+    cloudsSecret:
+      name: openstack-cloud-credentials
+      namespace: openshift-machine-api
+    flavor: m1.xlarge
+    image: rhcos-4.14
+    kind: OpenstackProviderSpec
+    metadata:
+      creationTimestamp: null
+    networks:    
+    - filter: {}
+      subnets:  
+      - filter:
+          name: refarch-lv7q9-nodes
+          tags: openshiftClusterID=refarch-lv7q9
+    rootVolume:
+        availabilityZone: nova <1>
+        diskSize: 30
+        sourceUUID: rhcos-4.12
+        volumeType: fast-0
+    securityGroups:
+    - filter: {}
+      name: refarch-lv7q9-master
+    serverGroupName: refarch-lv7q9-master
+    serverMetadata:
+      Name: refarch-lv7q9-master
+      openshiftClusterID: refarch-lv7q9
+    tags:
+    - openshiftClusterID=refarch-lv7q9
+    trunk: true
+    userDataSecret:
+      name: master-user-data
+----
+<1> Set the zone name as this value.
++
+[NOTE]
+====
+If you edited or recreated machine resources after your initial cluster deployment, you might have to adapt these steps for your configuration. 
+
+In your {rh-openstack} cluster, find the availability zone of the root volumes for your machines and use that as the value.
+====
+
+. Run the following command to retrieve information about the control plane machine set resource:
++
+[source,terminal]
+----
+$ oc describe controlplanemachineset.machine.openshift.io/cluster --namespace openshift-machine-api
+----
+
+. Run the following command to edit the resource:
++
+[source,terminal]
+----
+$ oc edit controlplanemachineset.machine.openshift.io/cluster --namespace openshift-machine-api
+----
+
+. For that resource, set the value of the `spec.state` property to `Active` to activate control plane machine sets for your cluster. 
+
+Your control plane is ready to be managed by the Cluster Control Plane Machine Set Operator.