Merge pull request #53397 from jeana-redhat/OSDOCS-4623-CPMS-tidying

jeana-redhat · web-flow · commit 3a22305effb7 · 2022-12-14T16:56:32.000-05:00
[OSDOCS-4623]: Sweeping for CPMS changes in repo
diff --git a/machine_management/control_plane_machine_management/cpmso-using.adoc b/machine_management/control_plane_machine_management/cpmso-using.adoc
@@ -25,6 +25,14 @@ include::modules/cpmso-feat-test-changes.adoc[leveloffset=+2]
 
 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.
 
+:context: cpmso-using-aws
+//Restricting the API server to private (AWS control plane machine set version)
+include::modules/private-clusters-setting-api-private.adoc[leveloffset=+2]
+:context: cpmso-using
+
+//Selecting a larger Amazon Web Services instance type for control plane machines
+include::modules/cpms-changing-aws-instance-type.adoc[leveloffset=+2]
+
 //Machine sets that enable the Amazon EC2 Instance Metadata Service
 include::modules/machineset-imds-options.adoc[leveloffset=+2]
 
@@ -42,6 +50,11 @@ include::modules/machineset-creating-dedicated-instances.adoc[leveloffset=+3]
 
 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.
 
+:context: cpmso-using-azure
+//Restricting the API server to private (Azure control plane machine set version)
+include::modules/private-clusters-setting-api-private.adoc[leveloffset=+2]
+:context: cpmso-using
+
 //Selecting an Azure Marketplace image
 include::modules/installation-azure-marketplace-subscribe.adoc[leveloffset=+2]
 
diff --git a/machine_management/deleting-machine.adoc b/machine_management/deleting-machine.adoc
@@ -14,4 +14,5 @@ include::modules/machine-delete.adoc[leveloffset=+1]
 [id="additional-resources_unhealthy-etcd-member"]
 == Additional resources
 
-* xref:../backup_and_restore/control_plane_backup_and_restore/replacing-unhealthy-etcd-member.adoc[Replacing an unhealthy etcd member].
+* xref:../backup_and_restore/control_plane_backup_and_restore/replacing-unhealthy-etcd-member.adoc[Replacing an unhealthy etcd member]
+* xref:../machine_management/control_plane_machine_management/cpmso-using.adoc#cpmso-using[Managing control plane machines with the Control Plane Machine Set Operator]
diff --git a/modules/architecture-machine-roles.adoc b/modules/architecture-machine-roles.adoc
@@ -1,14 +1,15 @@
 // Module included in the following assemblies:
 //
-// * architecture/architecture.adoc
+// * architecture/control-plane.adoc
+
 [id="architecture-machine-roles_{context}"]
 = Machine roles in {product-title}
 
-{product-title} assigns hosts different roles. These roles define the function of the machine within the cluster. The cluster contains definitions for the standard master and worker role types.
+{product-title} assigns hosts different roles. These roles define the function of the machine within the cluster. The cluster contains definitions for the standard `master` and `worker` role types.
 
 [NOTE]
 ====
-The cluster also contains the definition for the bootstrap role. Because the bootstrap machine is used only during cluster installation, its function is explained in the cluster installation documentation.
+The cluster also contains the definition for the `bootstrap` role. Because the bootstrap machine is used only during cluster installation, its function is explained in the cluster installation documentation.
 ====
 
 == Control plane and node host compatibility
@@ -47,24 +48,26 @@ In a Kubernetes cluster, the worker nodes are where the actual workloads request
 For information about how to enable crun instead of the default runC, see the documentation for creating a `ContainerRuntimeConfig` CR.
 ====
 
-In {product-title}, compute machine sets control the compute machines, which are assigned the `worker` machine role. Machines with the worker role drive compute workloads that are governed by a specific machine pool that autoscales them. Because {product-title} has the capacity to support multiple machine types, the worker machines are classed as _compute_ machines. In this release, the terms _worker machine_ and _compute machine_ are used interchangeably because the only default type of compute machine is the worker machine. In future versions of {product-title}, different types of compute machines, such as infrastructure machines, might be used by default.
+In {product-title}, compute machine sets control the compute machines, which are assigned the `worker` machine role. Machines with the `worker` role drive compute workloads that are governed by a specific machine pool that autoscales them. Because {product-title} has the capacity to support multiple machine types, the machines with the `worker` role are classed as _compute_ machines. In this release, the terms _worker machine_ and _compute machine_ are used interchangeably because the only default type of compute machine is the worker machine. In future versions of {product-title}, different types of compute machines, such as infrastructure machines, might be used by default.
 
 [NOTE]
 ====
 Compute machine sets are groupings of compute machine resources under the `machine-api` namespace. Compute machine sets are configurations that are designed to start new compute machines on a specific cloud provider. Conversely, machine config pools (MCPs) are part of the Machine Config Operator (MCO) namespace. An MCP is used to group machines together so the MCO can manage their configurations and facilitate their upgrades.
 ====
 
 [id="defining-masters_{context}"]
-== Cluster masters
+== Cluster control planes
+
+In a Kubernetes cluster, the _master_ nodes run services that are required to control the Kubernetes cluster. In {product-title}, the control plane is comprised of control plane machines that have a `master` machine role. They contain more than just the Kubernetes services for managing the {product-title} cluster. 
 
-In a Kubernetes cluster, the control plane nodes run services that are required to control the Kubernetes cluster. In {product-title}, the control plane machines are the control plane. They contain more than just the Kubernetes services for managing the {product-title} cluster. Because all of the machines with the control plane role are control plane machines, the terms _master_ and _control plane_ are used interchangeably to describe them. Instead of being grouped into a compute machine set, control plane machines are defined by a series of standalone machine API resources. Extra controls apply to control plane machines to prevent you from deleting all control plane machines and breaking your cluster.
+For most {product-title} clusters, control plane machines are defined by a series of standalone machine API resources. For supported cloud provider and {product-title} version combinations, control planes can be managed with control plane machine sets. Extra controls apply to control plane machines to prevent you from deleting all control plane machines and breaking your cluster.
 
 [NOTE]
 ====
 Exactly three control plane nodes must be used for all production deployments.
 ====
 
-Services that fall under the Kubernetes category on the master include the Kubernetes API server, etcd, the Kubernetes controller manager, and the Kubernetes scheduler.
+Services that fall under the Kubernetes category on the control plane include the Kubernetes API server, etcd, the Kubernetes controller manager, and the Kubernetes scheduler.
 
 .Kubernetes services that run on the control plane
 [cols="1,2",options="header"]
@@ -75,7 +78,7 @@ Services that fall under the Kubernetes category on the master include the Kuber
 and replication controllers. It also provides a focal point for the shared state of the cluster.
 
 |etcd
-|etcd stores the persistent master state while other components watch etcd for
+|etcd stores the persistent control plane state while other components watch etcd for
 changes to bring themselves into the specified state.
 //etcd can be optionally configured for high availability, typically deployed with 2n+1 peer services.
 
@@ -118,7 +121,7 @@ Some of these services on the control plane machines run as systemd services, wh
 Systemd services are appropriate for services that you need to always come up on that particular system shortly after it starts. For control plane machines, those include sshd, which allows remote login. It also includes services such as:
 
 * The CRI-O container engine (crio), which runs and manages the containers. {product-title} {product-version} uses CRI-O instead of the Docker Container Engine.
-* Kubelet (kubelet), which accepts requests for managing containers on the machine from master services.
+* Kubelet (kubelet), which accepts requests for managing containers on the machine from control plane services.
 
 CRI-O and Kubelet must run directly on the host as systemd services because they need to be running before you can run other containers.
 
diff --git a/modules/aws-console-changing-aws-instance-type.adoc b/modules/aws-console-changing-aws-instance-type.adoc
@@ -0,0 +1,31 @@
+// Module included in the following assemblies:
+//
+// * scalability_and_performance/recommended-host-practices.adoc
+
+:_content-type: PROCEDURE
+[id="aws-console-changing-aws-instance-type_{context}"]
+= Changing the Amazon Web Services instance type by using the AWS console
+
+You can change the Amazon Web Services (AWS) instance type that your control plane machines use by updating the instance type in the AWS console.
+
+.Prerequisites
+
+* You have access to the AWS console with the permissions required to modify the EC2 Instance for your cluster.
+
+.Procedure
+
+. Open the AWS console and fetch the instances for the control plane machines.
+
+. Choose one control plane machine instance.
+
+.. For the selected control plane machine, back up the etcd data by creating an etcd snapshot. For more information, see "Backing up etcd".
+
+.. In the AWS console, stop the control plane machine instance.
+
+.. Select the stopped instance, and click *Actions* -> *Instance Settings* -> *Change instance type*.
+
+.. Change the instance to a larger type, ensuring that the type is the same base as the previous selection, and apply changes. For example, you can change `m6i.xlarge` to `m6i.2xlarge` or `m6i.4xlarge`.
+
+.. Start the instance.
+
+. Repeat this process for each control plane machine.
diff --git a/modules/cpms-changing-aws-instance-type.adoc b/modules/cpms-changing-aws-instance-type.adoc
@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * scalability_and_performance/recommended-host-practices.adoc
+// * machine_management/control_plane_machine_management/cpmso-using.adoc
+
+ifeval::["{context}" == "recommended-host-practices"]
+:scale-host:
+endif::[]
+ifeval::["{context}" == "cpmso-using"]
+:cpmso-using:
+endif::[]
+
+:_content-type: PROCEDURE
+[id="cpms-changing-aws-instance-type_{context}"]
+= Changing the Amazon Web Services instance type by using a control plane machine set
+
+You can change the Amazon Web Services (AWS) instance type that your control plane machines use by updating the specification in the control plane machine set custom resource (CR).
+
+.Prerequisites
+
+* Your AWS cluster uses a control plane machine set.
+
+.Procedure
+
+ifdef::scale-host[]
+. 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
+----
+endif::scale-host[]
+
+. Edit the following line under the `providerSpec` field:
++
+[source,yaml]
+----
+providerSpec:
+  value:
+    ...
+    instanceType: <compatible_aws_instance_type> <1>
+----
+<1> Specify a larger AWS instance type with the same base as the previous selection. For example, you can change `m6i.xlarge` to `m6i.2xlarge` or `m6i.4xlarge`.
+
+. Save your changes.
+
+ifdef::scale-host[]
+** 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.
+endif::scale-host[]
+
+ifeval::["{context}" == "recommended-host-practices"]
+:!scale-host:
+endif::[]
+ifeval::["{context}" == "cpmso-using"]
+:!cpmso-using:
+endif::[]
diff --git a/modules/dr-restoring-cluster-state.adoc b/modules/dr-restoring-cluster-state.adoc
@@ -10,6 +10,11 @@
 
 You can use a saved etcd backup to restore a previous cluster state or restore a cluster that has lost the majority of control plane hosts.
 
+[NOTE]
+====
+If your cluster uses a control plane machine set, see "Troubleshooting the control plane machine set" for a more simple etcd recovery procedure. 
+====
+
 [IMPORTANT]
 ====
 When you restore your cluster, you must use an etcd backup that was taken from the same z-stream release. For example, an {product-title} 4.7.2 cluster must use an etcd backup that was taken from 4.7.2.
diff --git a/modules/increasing-aws-flavor-size.adoc b/modules/increasing-aws-flavor-size.adoc
diff --git a/modules/installation-aws-user-infra-requirements.adoc b/modules/installation-aws-user-infra-requirements.adoc
@@ -554,7 +554,7 @@ or the following individual permissions.
 You need `AWS::EC2::Instance` objects for the following machines:
 
 * A bootstrap machine. This machine is required during installation, but you can remove it after your cluster deploys.
-* Three control plane machines. The control plane machines are not governed by a compute machine set.
+* Three control plane machines. The control plane machines are not governed by a control plane machine set.
 * Compute machines. You must create at least two compute machines, which are also known as worker machines, during installation. These machines are not governed by a compute machine set.
 
 ////
diff --git a/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc b/modules/installation-user-infra-generate-k8s-manifest-ignition.adoc
@@ -167,7 +167,7 @@ By removing these files, you prevent the cluster from automatically generating c
 endif::aws,azure,ash,gcp[]
 
 ifdef::aws[]
-. Remove the Kubernetes manifest files that define the control plane machineset:
+. Remove the Kubernetes manifest files that define the control plane machine set:
 +
 [source,terminal]
 ----
diff --git a/modules/machine-api-overview.adoc b/modules/machine-api-overview.adoc
@@ -27,9 +27,11 @@ Machine sets:: `MachineSet` resources are groups of compute machines. Compute ma
 [WARNING]
 ====
 Control plane machines cannot be managed by compute machine sets. 
+
+Control plane machine sets provide management capabilities for supported control plane machines that are similar to what compute machine sets provide for compute machines. 
+
+For more information, see “Managing control plane machines".
 ====
-// For more information, see “Managing control plane machines."
-//to-do: add this line to the WARNING block once CPMS content exists
 
 The following custom resources add more capabilities to your cluster:
 
diff --git a/modules/machine-delete.adoc b/modules/machine-delete.adoc
@@ -1,6 +1,6 @@
 // Module included in the following assemblies:
 //
-// * machine_management/delete-machine.adoc
+// * machine_management/deleting-machine.adoc
 // * windows_containers/removing-windows-nodes.adoc
 
 :_content-type: PROCEDURE
@@ -9,11 +9,10 @@
 
 You can delete a specific machine. 
 
-//todo: confirm if this statement is still accurate w/CPMS
-[NOTE]
+[IMPORTANT]
 ====
-You cannot delete a control plane machine.
-====  
+Do not delete a control plane machine unless your cluster uses a control plane machine set.
+==== 
 
 .Prerequisites
 
diff --git a/modules/machine-health-checks-creating.adoc b/modules/machine-health-checks-creating.adoc
@@ -5,10 +5,14 @@
 
 :_content-type: PROCEDURE
 [id="machine-health-checks-creating_{context}"]
-= Creating a MachineHealthCheck resource
+= Creating a machine health check resource
 
-You can create a `MachineHealthCheck` resource for all `MachineSets` in your cluster.
-You should not create a `MachineHealthCheck` resource that targets control plane machines.
+You can create a `MachineHealthCheck` resource for machine sets in your cluster.
+
+[NOTE]
+====
+You can only apply a machine health check to control plane machines on clusters that use control plane machine sets.
+====
 
 .Prerequisites
 
diff --git a/modules/machineset-migrating-control-plane-nodes-to-diff-sd-rhv.adoc b/modules/machineset-migrating-control-plane-nodes-to-diff-sd-rhv.adoc
@@ -5,7 +5,6 @@
 [id="machineset-migrating-control-plane-nodes-to-diff-sd-rhv_{context}"]
 = Migrating control plane nodes to a different storage domain on {rh-virtualization}
 
-//todo: confirm if this statement is still accurate w/CPMS
 {product-title} does not manage control plane nodes, so they are easier to migrate than compute nodes. You can migrate them like any other virtual machine on {rh-virtualization-first}.
 
 Perform this procedure for each node separately.
diff --git a/modules/master-node-sizing.adoc b/modules/master-node-sizing.adoc
@@ -109,7 +109,13 @@ Operator Lifecycle Manager (OLM ) runs on the control plane nodes and it's memor
 
 [IMPORTANT]
 ====
-If you used an installer-provisioned infrastructure installation method, you cannot modify the control plane node size in a running {product-title} {product-version} cluster. Instead, you must estimate your total node count and use the suggested control plane node size during installation.
+You can modify the control plane node size in a running {product-title} {product-version} cluster for the following configurations only:
+
+* Clusters installed with a user-provisioned installation method.
+* AWS clusters installed with an installer-provisioned infrastructure installation method.
+* Clusters that use a control plane machine set to manage control plane machines.
+
+For all other configurations, you must estimate your total node count and use the suggested control plane node size during installation.
 ====
 
 [IMPORTANT]
diff --git a/modules/private-clusters-setting-api-private.adoc b/modules/private-clusters-setting-api-private.adoc
diff --git a/modules/restore-replace-stopped-etcd-member.adoc b/modules/restore-replace-stopped-etcd-member.adoc
diff --git a/scalability_and_performance/recommended-host-practices.adoc b/scalability_and_performance/recommended-host-practices.adoc

Original file line number	Diff line number	Diff line change
`@@ -167,7 +167,7 @@ By removing these files, you prevent the cluster from automatically generating c`
`167`	`167`	`endif::aws,azure,ash,gcp[]`
`168`	`168`
`169`	`169`	`ifdef::aws[]`
`170`		`-. Remove the Kubernetes manifest files that define the control plane machineset:`
	`170`	`+. Remove the Kubernetes manifest files that define the control plane machine set:`
`171`	`171`	`+`
`172`	`172`	`[source,terminal]`
`173`	`173`	`----`