Merge pull request #56336 from lahinson/hcp-upgrades-osdocs-5327

[OSDOCS-5327]: Adding updates docs for hosted control planes

Author: stevsmit

_topic_maps/_topic_map.yml

@@ -622,6 +622,8 @@ Topics:
   File: updating-hardware-on-nodes-running-on-vsphere
 - Name: Preflight validation for Kernel Module Management (KMM) Modules
   File: kmm-preflight-validation
+- Name: Updating hosted control planes
+  File: updating-hosted-control-planes
 # - Name: Troubleshooting an update
 #  File: updating-troubleshooting
 ---

hosted_control_planes/hcp-managing.adoc

@@ -8,7 +8,9 @@ toc::[]
 
 After you configure your environment for hosted control planes and create a hosted cluster, you can further manage your clusters and nodes.
 
-//updating hosted control planes
+include::modules/updates-for-hosted-control-planes.adoc[leveloffset=+1]
+include::modules/updating-node-pools-for-hcp.adoc[leveloffset=+1]
+include::modules/configuring-node-pools-for-hcp.adoc[leveloffset=+1]
 //restarting hosted control plane components
 //pausing reconciliation
 //debugging why nodes have not joined the cluster

modules/configuring-node-pools-for-hcp.adoc

@@ -0,0 +1,64 @@
+// Module included in the following assemblies:
+//
+// * updates/updating-hosted-control-planes.adoc
+// * hosted_control_planes/hcp-managing.adoc
+
+:_content-type: PROCEDURE
+[id="configuring-node-pools-for-hcp_{context}"]
+= Configuring node pools for hosted control planes
+
+On hosted control planes, you can configure node pools by creating a `MachineConfig` object inside of a config map in the management cluster.
+
+//.Prerequisites
+
+//Are any prerequisites needed for this procedure? i.e., does the customer need to perform an update first?
+
+.Procedure
+
+. To create a `MachineConfig` object inside of a config map in the management cluster, enter the following information:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: <configmap-name>
+  namespace: clusters
+data:
+  config: |
+    apiVersion: machineconfiguration.openshift.io/v1
+    kind: MachineConfig
+    metadata:
+      labels:
+        machineconfiguration.openshift.io/role: worker
+      name: <machineconfig-name>
+    spec:
+      config:
+        ignition:
+          version: 3.2.0
+        storage:
+          files:
+          - contents:
+              source: data:...
+            mode: 420
+            overwrite: true
+            path: ${PATH} <1>
+----
+<1> Sets the path on the node where the `MachineConfig` object is stored.
+
+. After you add the object to the config map, you can apply the config map to the node pool as follows:
++
+[source,yaml]
+----
+spec:
+  config:
+    - name: ${CONFIGMAP_NAME}
+----
+
+//.Verification
+
+// Does the user need to do anything to verify that the procedure was successful?
+
+
+
+

modules/updates-for-hosted-control-planes.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+//
+// * updates/updating-hosted-control-planes.adoc
+// * hosted_control_planes/hcp-managing.adoc
+
+:_content-type: CONCEPT
+[id="updates-for-hosted-control-planes_{context}"]
+= Updates for hosted control planes
+
+Updates for hosted control planes involve updating the hosted cluster and the node pools. For a cluster to remain fully operational during an update process, you must meet the requirements of the link:https://kubernetes.io/releases/version-skew-policy/[Kubernetes version skew policy] while completing the control plane and node updates.
+
+[id="updates-for-hosted-control-planes-hostedcluster_{context}"]
+== Updates for the hosted cluster
+
+The `spec.release` value dictates the version of the control plane. The `HostedCluster` object transmits the intended `spec.release` value to the `HostedControlPlane.spec.release` value and runs the appropriate Control Plane Operator version.
+
+The hosted control plane manages the rollout of the new version of the control plane components along with any {product-title} components through the new version of the Cluster Version Operator (CVO).
+
+[id="updates-for-hosted-control-planes-nodepools_{context}"]
+== Updates for node pools
+
+With node pools, you can configure the software that is running in the nodes by exposing the `spec.release` and `spec.config` values. You can start a rolling node pool update in the following ways:
+
+* Changing the `spec.release` or `spec.config` values.
+* Changing any platform-specific field, such as the AWS instance type. The result is a set of new instances with the new type.
+* Changing the cluster configuration, if the change propagates to the node.
+
+Node pools support replace updates and in-place updates. The `nodepool.spec.release` value dictates the version of any particular node pool. A `NodePool` object completes a replace or an in-place rolling update according to the `.spec.management.upgradeType` value. 
+
+After you create a node pool, you cannot change the update type. If you want to change the update type, you must create a node pool and delete the other one. 
+
+[id="updates-for-nodepools-replace_{context}"]
+=== Replace updates for node pools
+
+A _replace_ update creates instances in the new version while it removes old instances from the previous version. This update type is effective in cloud environments where this level of immutability is cost effective. 
+
+Replace updates do not preserve any manual changes because the node is entirely re-provisioned.
+
+[id="updates-for-nodepools-inplace_{context}"]
+=== In place updates for node pools
+
+An _in-place_ update directly updates the operating systems of the instances. This type is suitable for environments where the infrastructure constraints are higher, such as bare metal.
+
+In-place updates can preserve manual changes, but will report errors if you make manual changes to any file system or operating system configuration that the cluster directly manages, such as kubelet certificates.

modules/updating-node-pools-for-hcp.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+//
+// * updates/updating-hosted-control-planes.adoc
+// * hosted_control_planes/hcp-managing.adoc
+
+:_content-type: PROCEDURE
+[id="updating-node-pools-for-hcp_{context}"]
+= Updating node pools for hosted control planes
+
+On hosted control planes, you update your version of {product-title} by updating the node pools. The node pool version must not surpass the hosted control plane version.
+
+.Procedure
+
+* To start the process to update to a new version of {product-title}, change the `spec.release.image` value of the node pool by entering the following command:
++
+[source,terminal]
+----
+$ oc -n NAMESPACE patch HC HCNAME --patch '{"spec":{"release":{"image": "example"}}}' --type=merge
+----
+
+.Verification
+
+* To verify that the new version was rolled out, check the `.status.version` value and the status conditions.
+
+
+

updating/index.adoc

@@ -96,3 +96,11 @@ xref:../updating/updating-hardware-on-nodes-running-on-vsphere.adoc#updating-har
 ====
 Using hardware version 13 for your cluster nodes running on vSphere is now deprecated. This version is still fully supported, but support will be removed in a future version of {product-title}. Hardware version 15 is now the default for vSphere virtual machines in {product-title}.
 ====
+
+[id="updating-clusters-overview-hosted-control-planes"]
+== Updating hosted control planes
+
+xref:../updating/updating-hosted-control-planes.adoc#updating-hosted-control-planes[Updating hosted control planes]: On hosted control planes for {product-title}, updates are decoupled between the control plane and the nodes. Your service cluster provider, which is the user that hosts the cluster control planes, can manage the updates as needed. The hosted cluster handles control plane updates, and node pools handle node upgrades. For more information, see the following information:
+
+* xref:../updating/updating-hosted-control-planes.adoc#updates-for-hosted-control-planes_updating-hosted-control-planes[Updates for hosted control planes]
+* xref:../updating/updating-hosted-control-planes.adoc#updating-node-pools-for-hcp_updating-hosted-control-planes[Updating node pools for hosted control planes]

updating/understanding-openshift-updates.adoc

@@ -25,4 +25,7 @@ include::modules/update-common-terms.adoc[leveloffset=+1]
 .Additional resources
 
 * xref:../post_installation_configuration/machine-configuration-tasks.adoc#machine-config-overview-post-install-machine-configuration-tasks[Machine config overview]
+ifdef::openshift-enterprise[]
+* xref:../updating/updating-restricted-network-cluster/restricted-network-update-osus.adoc#update-service-overview_updating-restricted-network-cluster-osus[About the OpenShift Update Service]
+endif::openshift-enterprise[]
 * xref:../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels_understanding-upgrade-channels-releases[Update channels and releases]

updating/updating-hosted-control-planes.adoc

@@ -0,0 +1,13 @@
+:_content-type: ASSEMBLY
+[id="updating-hosted-control-planes"]
+= Updating hosted control planes
+include::_attributes/common-attributes.adoc[]
+:context: updating-hosted-control-planes
+
+toc::[]
+
+On hosted control planes for {product-title}, updates are decoupled between the control plane and the nodes. Your service cluster provider, which is the user that hosts the cluster control planes, can manage the updates as needed. The hosted cluster handles control plane updates, and node pools handle node upgrades.
+
+include::modules/updates-for-hosted-control-planes.adoc[leveloffset=+1]
+include::modules/updating-node-pools-for-hcp.adoc[leveloffset=+1]
+include::modules/configuring-node-pools-for-hcp.adoc[leveloffset=+1]