OSDOCS#14017: HostedCluster and NodePool version compatibility

Author: xenolinux

hosted_control_planes/hcp-updating.adoc

@@ -19,6 +19,9 @@ include::modules/hcp-updating-requirements.adoc[leveloffset=+1]
 * xref:../hosted_control_planes/hcp-updating.adoc#hcp-update-ocp-hc_hcp-updating[Updating a control plane in a hosted cluster]
 * xref:../hosted_control_planes/hcp-updating.adoc#hcp-update-node-pools_hcp-updating[Updating node pools in a hosted cluster]
 
+// HostedCluster and NodePool version compatibility check (SupportedVersionSkew)
+include::modules/hcp-np-version-skew.adoc[leveloffset=+1]
+
 include::modules/hcp-get-ocp-channel.adoc[leveloffset=+1]
 
 include::modules/hcp-get-upgrade-versions.adoc[leveloffset=+1]

hosted_control_planes/index.adoc

@@ -21,6 +21,7 @@ include::modules/hosted-control-planes-version-support.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
+* xref:../hosted_control_planes/hcp-updating/hcp-np-version-skew.adoc#hcp-np-version-skew_hcp-updating[HostedCluster and NodePool version compatibility]
 * link:https://amd64.ocp.releases.ci.openshift.org/[AMD64 release images]
 * link:https://arm64.ocp.releases.ci.openshift.org/[ARM64 release images]
 * link:https://multi.ocp.releases.ci.openshift.org/[Multi-arch release images]

modules/hcp-np-version-skew.adoc

@@ -0,0 +1,35 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-updating.adoc
+
+
+:_mod-docs-content-type: REFERENCE
+[id="hcp-np-version-skew_{context}"]
+= HostedCluster and NodePool version compatibility
+
+In {hcp}, you can check that your `NodePool` version is compatible with your `HostedCluster` version.
+
+Review the following supported node pool version rules:
+
+* `NodePool` version cannot be higher than the `HostedCluster` version.
+
+** For `4.<x>` versions, where `<x>` is an _even_ release number, such as 4.18, you must use up to 2 minor versions, for example, 4.17 and 4.16.
+
+** For `4.<x>` versions, where `<x>` is an _odd_ release number, such as 4.17, you must use up to 1 minor version, for example, 4.16.
+
+.Example table of the supported node pool versions for your hosted cluster
+
+[cols="2,3,3", options="header"]
+|===
+|Hosted cluster version |Supported node pool versions |Unsupported node pool versions
+|4.18 |4.17, 4.16 |4.15, 4.14
+|4.17 |4.16 |4.15
+|4.18.5 |4.18.5, 4.18.4, 4.17.z, 4.16.z |4.15.z and below, 4.19.z and above
+|4.17.5 |4.17.5, 4.17.4, 4.16.z | 4.15.z and below, 4.18.z and above
+|===
+
+
+* The `NodePool` controller sets the `SupportedVersionSkew` condition by default to report one of the following version compatibility statuses:
+
+** `True`: Indicates that the `NodePool` version is compatible with the HostedCluster version.
+** `False`: Indicates that the `NodePool` version is incompatible with detailed error messages. If you see the version incompatibility issues, you must upgrade or downgrade `NodePool` to a compatible version.

modules/hcp-updates-hosted-cluster.adoc

@@ -10,11 +10,13 @@ The `spec.release.image` value dictates the version of the control plane. The `H
 
 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).
 
+Before updating the hosted cluster, see "HostedCluster and NodePool version compatibility".
+
 [IMPORTANT]
 ====
 In {hcp}, the `NodeHealthCheck` resource cannot detect the status of the CVO. A cluster administrator must manually pause the remediation triggered by `NodeHealthCheck`, before performing critical operations, such as updating the cluster, to prevent new remediation actions from interfering with cluster updates.
 
 To pause the remediation, enter the array of strings, for example, `pause-test-cluster`, as a value of the `pauseRequests` field in the `NodeHealthCheck` resource. For more information, see link:https://docs.redhat.com/en/documentation/workload_availability_for_red_hat_openshift/24.4/html/remediation_fencing_and_maintenance/node-health-check-operator#about-node-health-check-operator_node-health-check-operator[About the Node Health Check Operator].
 
 After the cluster update is complete, you can edit or delete the remediation. Navigate to the *Compute* -> *NodeHealthCheck* page, click your node health check, and then click *Actions*, which shows a drop-down list.
-====
+====

modules/hcp-updates-node-pools.adoc

@@ -12,6 +12,8 @@ With node pools, you can configure the software that is running in the nodes by
 * 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.
 
+For more information about hosted cluster and node pool compatibility, see "HostedCluster and NodePool version compatibility".
+
 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.

modules/hosted-control-planes-version-support.adoc

@@ -1,7 +1,7 @@
 // Module included in the following assemblies:
 //
 // * architecture/control-plane.adoc
-// * hosted-control-planes/index.adoc
+// * hosted_control_planes/index.adoc
 
 
 :_mod-docs-content-type: CONCEPT
@@ -64,7 +64,7 @@ You can use the `hypershift.openshift.io` API resources, such as, `HostedCluster
 
 The API version policy generally aligns with the policy for link:https://kubernetes.io/docs/reference/using-api/#api-versioning[Kubernetes API versioning].
 
-Updates for {hcp} involve updating the hosted cluster and the node pools. For more information, see "Updates for {hcp}".
+Updates for {hcp} involve updating the hosted cluster and the node pools. For more information, see "Updates for {hcp}" and "HostedCluster and NodePool version compatibility".
 
 [id="hcp-versioning-cpo_{context}"]
 == Control Plane Operator