[OSDOCS-4236]: Updating control plane config

Author: jeana-redhat

_topic_maps/_topic_map.yml

@@ -1979,8 +1979,8 @@ Topics:
     File: cpmso-getting-started
   - Name: Control Plane Machine Set Operator configuration
     File: cpmso-configuration
-  #- Name: Using the Control Plane Machine Set Operator
-  #  File: cpmso-using
+  - Name: Using the Control Plane Machine Set Operator
+    File: cpmso-using
   - Name: Control plane resiliency and recovery
     File: cpmso-resiliency
   #- Name: Troubleshooting the Control Plane Machine Set Operator

machine_management/control_plane_machine_management/cpmso-configuration.adoc

@@ -10,11 +10,17 @@ These example YAML file and snippets demonstrate the base structure for a contro
 
 //Sample YAML for a control plane machine set custom resource
 include::modules/cpmso-yaml-sample-cr.adoc[leveloffset=+1]
-////
+
 [role="_additional-resources"]
 .Additional resources
-* xr@f:../../machine_management/control_plane_machine_management/cpmso-using.adoc#cpmso-feat-config-update_cpmso-using[Updating the control plane configuration]
-////
+* xref:../../machine_management/control_plane_machine_management/cpmso-getting-started.adoc#cpmso-getting-started[Getting started with the Control Plane Machine Set Operator]
+
+* xref:../../machine_management/control_plane_machine_management/cpmso-using.adoc#cpmso-feat-config-update_cpmso-using[Updating the control plane configuration]
+
+[discrete]
+[id="cpmso-sample-yaml-provider-specific_{context}"]
+=== Provider-specific configuration
+
 The `<platform_failure_domains>` and `<platform_provider_spec>` sections of the control plane machine set resources are provider-specific. Refer to the example YAML for your cluster:
 
 * xref:../../machine_management/control_plane_machine_management/cpmso-configuration.adoc#cpmso-sample-yaml-aws_cpmso-configuration[Sample YAML snippets for configuring Amazon Web Services clusters]
@@ -35,6 +41,10 @@ include::modules/cpmso-yaml-failure-domain-aws.adoc[leveloffset=+2]
 //Sample AWS provider specification
 include::modules/cpmso-yaml-provider-spec-aws.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/control_plane_machine_management/cpmso-using.adoc#cpmso-supported-features-aws_cpmso-using[Enabling Amazon Web Services features for control plane machines]
+
 [id="cpmso-sample-yaml-azure_{context}"]
 == Sample YAML for configuring Microsoft Azure clusters
 
@@ -46,6 +56,10 @@ include::modules/cpmso-yaml-failure-domain-azure.adoc[leveloffset=+2]
 //Sample Azure provider specification
 include::modules/cpmso-yaml-provider-spec-azure.adoc[leveloffset=+2]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../machine_management/control_plane_machine_management/cpmso-using.adoc#cpmso-supported-features-azure_cpmso-using[Enabling Microsoft Azure features for control plane machines]
+
 [id="cpmso-sample-yaml-vsphere_{context}"]
 == Sample YAML for configuring VMware vSphere clusters
 

machine_management/control_plane_machine_management/cpmso-using.adoc

@@ -6,13 +6,71 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-The Control Plane Machine Set Operator automates the following capabilities:
+The Control Plane Machine Set Operator automates several essential aspects of control plane management.
 
 //Vertical resizing of the control plane
-include::modules/cpmso-feat-vertical-resize.adoc[leveloffset=+1]
+//include::modules/cpmso-feat-vertical-resize.adoc[leveloffset=+1]
 
 //Updating the control plane configuration
 include::modules/cpmso-feat-config-update.adoc[leveloffset=+1]
 
+//Automatically updating the control plane configuration
+include::modules/cpmso-feat-auto-update.adoc[leveloffset=+2]
+
 //Testing changes to the control plane configuration
 include::modules/cpmso-feat-test-changes.adoc[leveloffset=+2]
+
+[id="cpmso-supported-features-aws_{context}"]
+== Enabling Amazon Web Services features for control plane machines
+
+You can enable Amazon Web Services (AWS) features on 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.
+
+//Machine sets that enable the Amazon EC2 Instance Metadata Service
+include::modules/machineset-imds-options.adoc[leveloffset=+2]
+
+//Creating machines that use the Amazon EC2 Instance Metadata Service
+include::modules/machineset-creating-imds-options.adoc[leveloffset=+3]
+
+//Machine sets that deploy machines as Dedicated Instances
+include::modules/machineset-dedicated-instances.adoc[leveloffset=+2]
+
+//Creating Dedicated Instances by using machine sets
+include::modules/machineset-creating-dedicated-instances.adoc[leveloffset=+3]
+
+[id="cpmso-supported-features-azure_{context}"]
+== Enabling Microsoft Azure features for control plane machines
+
+You can enable Microsoft Azure features on 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.
+
+//Selecting an Azure Marketplace image
+include::modules/installation-azure-marketplace-subscribe.adoc[leveloffset=+2]
+
+//Enabling Azure boot diagnostics
+include::modules/machineset-azure-boot-diagnostics.adoc[leveloffset=+2]
+
+//Machine sets that deploy machines on ultra disks as data disks
+include::modules/machineset-azure-ultra-disk.adoc[leveloffset=+2]
+
+[role="_additional-resources"]
+.Additional resources
+* link:https://docs.microsoft.com/en-us/azure/virtual-machines/disks-types#ultra-disks[Microsoft Azure ultra disks documentation]
+
+//Creating machines on ultra disks by using machine sets
+include::modules/machineset-creating-azure-ultra-disk.adoc[leveloffset=+3]
+
+//Troubleshooting resources for machine sets that enable ultra disks
+include::modules/machineset-troubleshooting-azure-ultra-disk.adoc[leveloffset=+3]
+
+//Enabling customer-managed encryption keys for a machine set
+include::modules/machineset-customer-managed-encryption-azure.adoc[leveloffset=+2]
+
+// Accelerated Networking for Microsoft Azure VMs
+include::modules/machineset-azure-accelerated-networking.adoc[leveloffset=+2]
+
+//Not applicable for 4.12, possibly 4.13?
+//[role="_additional-resources"]
+//.Additional resources
+//* xref:../../installing/installing_azure/installing-azure-customizations.adoc#machineset-azure-enabling-accelerated-networking-new-install_installing-azure-customizations[Enabling Accelerated Networking during installation]
+
+// Enabling Accelerated Networking on an existing Microsoft Azure cluster
+include::modules/machineset-azure-enabling-accelerated-networking-existing.adoc[leveloffset=+3]

machine_management/creating_machinesets/creating-machineset-aws.adoc

@@ -29,7 +29,7 @@ include::modules/machineset-creating-imds-options.adoc[leveloffset=+2]
 //Machine sets that deploy machines as Dedicated Instances
 include::modules/machineset-dedicated-instances.adoc[leveloffset=+1]
 
-//Creating Dedicated Instances by using compute machine sets
+//Creating Dedicated Instances by using machine sets
 include::modules/machineset-creating-dedicated-instances.adoc[leveloffset=+2]
 
 //Machine sets that deploy machines as Spot Instances

machine_management/creating_machinesets/creating-machineset-azure.adoc

@@ -23,7 +23,7 @@ include::modules/machineset-creating.adoc[leveloffset=+1]
 //Selecting an Azure Marketplace image
 include::modules/installation-azure-marketplace-subscribe.adoc[leveloffset=+1]
 
-//Enabling Azure boot diagnostics on compute machines
+//Enabling Azure boot diagnostics
 include::modules/machineset-azure-boot-diagnostics.adoc[leveloffset=+1]
 
 //Machine sets that deploy machines as Spot VMs
@@ -47,13 +47,13 @@ include::modules/machineset-azure-ultra-disk.adoc[leveloffset=+1]
 * xref:../../storage/container_storage_interface/persistent-storage-csi-azure.adoc#machineset-azure-ultra-disk_persistent-storage-csi-azure[Machine sets that deploy machines on ultra disks using CSI PVCs]
 * xref:../../storage/persistent_storage/persistent-storage-azure.adoc#machineset-azure-ultra-disk_persistent-storage-azure[Machine sets that deploy machines on ultra disks using in-tree PVCs]
 
-//Creating machines on ultra disks by using compute machine sets
+//Creating machines on ultra disks by using machine sets
 include::modules/machineset-creating-azure-ultra-disk.adoc[leveloffset=+2]
 
-//Troubleshooting resources for compute machine sets that enable ultra disks
+//Troubleshooting resources for machine sets that enable ultra disks
 include::modules/machineset-troubleshooting-azure-ultra-disk.adoc[leveloffset=+2]
 
-//Enabling customer-managed encryption keys for a compute machine set
+//Enabling customer-managed encryption keys for a machine set
 include::modules/machineset-customer-managed-encryption-azure.adoc[leveloffset=+1]
 
 // Accelerated Networking for Microsoft Azure VMs

modules/cpmso-feat-auto-update.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+//
+// * machine_management/control_plane_machine_management/cpmso-using.adoc
+
+:_content-type: CONCEPT
+[id="cpmso-feat-auto-update_{context}"]
+= Automatically updating the control plane configuration
+
+You can use the `RollingUpdate` update strategy to automatically propagate changes to your control plane configuration.
+
+For clusters that use the default `RollingUpdate` update strategy, the Operator creates a replacement control plane machine with the configuration that is specified in the CR. When the replacement control plane machine is ready, the Operator deletes the control plane machine that is marked for replacement. The replacement machine then joins the control plane.
+
+If multiple control plane machines are marked for replacement, the Operator repeats this replacement process one machine at a time until each machine is replaced.

modules/cpmso-feat-config-update.adoc

@@ -1,7 +1,39 @@
 // Module included in the following assemblies:
 //
-// * machine_management/cpmso-about.adoc
+// * machine_management/control_plane_machine_management/cpmso-using.adoc
 
-:_content-type: CONCEPT
+:_content-type: PROCEDURE
 [id="cpmso-feat-config-update_{context}"]
-= Updating the control plane configuration
+= Updating the control plane configuration
+
+You can make changes to the configuration of the machines in the control plane by updating the specification in the control plane machine set custom resource (CR).
+
+The Control Plane Machine Set Operator monitors the control plane machines and compares their configuration with the specification in the control plane machine set CR. When there is a discrepancy between the specification in the CR and the configuration of a control plane machine, the Operator marks that control plane machine for replacement.
+
+[NOTE]
+====
+For more information about the parameters in the CR, see "Control Plane Machine Set Operator configuration".
+====
+
+.Prerequisites
+
+* Your cluster has an activated and functioning Control Plane Machine Set Operator.
+
+.Procedure
+
+. Edit your control plane machine set CR by running the following command:
++
+[source,terminal]
+----
+$ oc --namespace openshift-machine-api edit controlplanemachineset.machine.openshift.io cluster
+----
+
+. Change the values of any fields that you want to update in your cluster configuration.
+
+. Save your changes.
+
+.Next steps
+
+* For clusters that use the default `RollingUpdate` update strategy, the Operator automatically propagates the changes to your control plane configuration.
+
+* For clusters that are configured to use the `OnDelete` update strategy, you must replace your control plane machines manually.

modules/cpmso-feat-test-changes.adoc

@@ -1,7 +1,13 @@
 // Module included in the following assemblies:
 //
-// * machine_management/cpmso-about.adoc
+// * machine_management/control_plane_machine_management/cpmso-using.adoc
 
 :_content-type: CONCEPT
 [id="cpmso-feat-test-changes_{context}"]
-= Testing changes to the control plane configuration
+= Testing changes to the control plane configuration
+
+You can use the `OnDelete` update strategy to test changes to your control plane configuration. With this update strategy, you replace control plane machines manually. Manually replacing machines allows you to test changes to your configuration on a single machine before applying the changes more broadly.
+
+For clusters that are configured to use the `OnDelete` update strategy, the Operator creates a replacement control plane machine when you delete an existing machine. When the replacement control plane machine is ready, the etcd Operator allows the existing machine to be deleted. The replacement machine then joins the control plane.
+
+If multiple control plane machines are deleted, the Operator creates all of the required replacement machines simultaneously.

modules/cpmso-yaml-provider-spec-aws.adoc

@@ -57,7 +57,7 @@ providerSpec:
     userDataSecret:
       name: master-user-data <12>
 ----
-<1> Specifies the Amazon Machine Images (AMI) ID for the cluster. The AMI must belong to the same region as the cluster.
+<1> Specifies the {op-system-first} Amazon Machine Images (AMI) ID for the cluster. The AMI must belong to the same region as the cluster. If you want to use an AWS Marketplace image, you must complete the {product-title} subscription from the link:https://aws.amazon.com/marketplace/fulfillment?productId=59ead7de-2540-4653-a8b0-fa7926d5c845[AWS Marketplace] to obtain an AMI ID for your region.
 <2> Specifies the configuration of an encrypted EBS volume.
 <3> Specifies the secret name for the cluster. Do not change this value.
 <4> Specifies the AWS Identity and Access Management (IAM) instance profile. Do not change this value.

modules/cpmso-yaml-sample-cr.adoc

@@ -56,8 +56,7 @@ $ oc get -o jsonpath='{.status.infrastructureName}{"\n"}' infrastructure cluster
 ====
 Before you activate the Operator, you must ensure that the `ControlPlaneMachineSet` CR configuration is correct for your cluster requirements. For more information about activating the Control Plane Machine Set Operator, see "Getting started with the Control Plane Machine Set Operator".
 ====
-<5> Specifies the update strategy for the cluster. The allowed values are `OnDelete` and `RollingUpdate`. The default value is `RollingUpdate`. 
-//For more information about update strategies, see "Updating the control plane configuration".
+<5> Specifies the update strategy for the cluster. The allowed values are `OnDelete` and `RollingUpdate`. The default value is `RollingUpdate`. For more information about update strategies, see "Updating the control plane configuration".
 <6> Specifies the cloud provider platform name. Do not change this value.
 <7> Specifies 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.
 +