From cc8bc12a090aec5a1f69c0107365f29e80b3a86f Mon Sep 17 00:00:00 2001 From: xenolinux Date: Thu, 26 Sep 2024 18:04:58 +0530 Subject: [PATCH] OSDOCS#12138: Supported OCP versions for hosted clusters --- hosted_control_planes/hcp-updating.adoc | 13 +- modules/hcp-get-ocp-channel.adoc | 135 ++++++++++++++++++ modules/hcp-get-upgrade-versions.adoc | 77 ++++++++++ ...or-hcp.adoc => hcp-update-node-pools.adoc} | 8 +- ...ed-cluster.adoc => hcp-update-ocp-hc.adoc} | 18 ++- modules/hcp-update-using-mce-console.adoc | 22 +++ modules/hcp-updating-requirements.adoc | 2 +- 7 files changed, 265 insertions(+), 10 deletions(-) create mode 100644 modules/hcp-get-ocp-channel.adoc create mode 100644 modules/hcp-get-upgrade-versions.adoc rename modules/{updating-node-pools-for-hcp.adoc => hcp-update-node-pools.adoc} (81%) rename modules/{updating-hosted-cluster.adoc => hcp-update-ocp-hc.adoc} (64%) create mode 100644 modules/hcp-update-using-mce-console.adoc diff --git a/hosted_control_planes/hcp-updating.adoc b/hosted_control_planes/hcp-updating.adoc index 074a5ad73f..0bc225a90c 100644 --- a/hosted_control_planes/hcp-updating.adoc +++ b/hosted_control_planes/hcp-updating.adoc @@ -16,6 +16,10 @@ include::modules/hcp-updating-requirements.adoc[leveloffset=+1] * xref:../updating/updating_a_cluster/updating-cluster-cli.adoc#updating-cluster-cli[Updating a cluster using the CLI] * xref:../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators] +include::modules/hcp-get-ocp-channel.adoc[leveloffset=+1] + +include::modules/hcp-get-upgrade-versions.adoc[leveloffset=+1] + // Updates for the hosted cluster include::modules/hcp-updates-hosted-cluster.adoc[leveloffset=+1] @@ -23,7 +27,10 @@ include::modules/hcp-updates-hosted-cluster.adoc[leveloffset=+1] include::modules/hcp-updates-node-pools.adoc[leveloffset=+1] // Updating node pools for hosted control planes -include::modules/updating-node-pools-for-hcp.adoc[leveloffset=+1] +include::modules/hcp-update-node-pools.adoc[leveloffset=+1] -// Updating a hosted cluster -include::modules/updating-hosted-cluster.adoc[leveloffset=+1] +// Updating an ocp release image in a hosted cluster +include::modules/hcp-update-ocp-hc.adoc[leveloffset=+1] + +// Updating a hosted cluster by using the mce console +include::modules/hcp-update-using-mce-console.adoc[leveloffset=+1] diff --git a/modules/hcp-get-ocp-channel.adoc b/modules/hcp-get-ocp-channel.adoc new file mode 100644 index 0000000000..e98fae7ea7 --- /dev/null +++ b/modules/hcp-get-ocp-channel.adoc @@ -0,0 +1,135 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-updating.adoc + +:_mod-docs-content-type: CONCEPT +[id="hcp-get-ocp-channel_{context}"] += Setting channels in a hosted cluster + +You can see available updates in the `HostedCluster.Status` field of the `HostedCluster` custom resource (CR). + +The available updates are not fetched from the Cluster Version Operator (CVO) of a hosted cluster. The list of the available updates can be different from the available updates from the following fields of the `HostedCluster` custom resource (CR): + +* `status.version.availableUpdates` +* `status.version.conditionalUpdates` + +The initial `HostedCluster` CR does not have any information in the `status.version.availableUpdates` and `status.version.conditionalUpdates` fields. After you set the `spec.channel` field to the stable {product-title} release version, the HyperShift Operator reconciles the `HostedCluster` CR and updates the `status.version` field with the available and conditional updates. + +See the following example of the `HostedCluster` CR that contains the channel configuration: + +[source,yaml] +---- +spec: + autoscaling: {} + channel: stable-4.y <1> + clusterID: d6d42268-7dff-4d37-92cf-691bd2d42f41 + configuration: {} + controllerAvailabilityPolicy: SingleReplica + dns: + baseDomain: dev11.red-chesterfield.com + privateZoneID: Z0180092I0DQRKL55LN0 + publicZoneID: Z00206462VG6ZP0H2QLWK +---- +<1> Replace `<4.y>` with the {product-title} release version you specified in `spec.release`. For example, if you set the `spec.release` to `ocp-release:4.16.4-multi`, you must set `spec.channel` to `stable-4.16`. + +After you configure the channel in the `HostedCluster` CR, to view the output of the `status.version.availableUpdates` and `status.version.conditionalUpdates` fields, run the following command: + +[source,terminal] +---- +$ oc get -n hostedcluster -o yaml +---- + +.Example output +[source,yaml] +---- +version: + availableUpdates: + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:b7517d13514c6308ae16c5fd8108133754eb922cd37403ed27c846c129e67a9a + url: https://access.redhat.com/errata/RHBA-2024:6401 + version: 4.16.11 + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:d08e7c8374142c239a07d7b27d1170eae2b0d9f00ccf074c3f13228a1761c162 + url: https://access.redhat.com/errata/RHSA-2024:6004 + version: 4.16.10 + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:6a80ac72a60635a313ae511f0959cc267a21a89c7654f1c15ee16657aafa41a0 + url: https://access.redhat.com/errata/RHBA-2024:5757 + version: 4.16.9 + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:ea624ae7d91d3f15094e9e15037244679678bdc89e5a29834b2ddb7e1d9b57e6 + url: https://access.redhat.com/errata/RHSA-2024:5422 + version: 4.16.8 + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:e4102eb226130117a0775a83769fe8edb029f0a17b6cbca98a682e3f1225d6b7 + url: https://access.redhat.com/errata/RHSA-2024:4965 + version: 4.16.6 + - channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:f828eda3eaac179e9463ec7b1ed6baeba2cd5bd3f1dd56655796c86260db819b + url: https://access.redhat.com/errata/RHBA-2024:4855 + version: 4.16.5 + conditionalUpdates: + - conditions: + - lastTransitionTime: "2024-09-23T22:33:38Z" + message: |- + Could not evaluate exposure to update risk SRIOVFailedToConfigureVF (creating PromQL round-tripper: unable to load specified CA cert /etc/tls/service-ca/service-ca.crt: open /etc/tls/service-ca/service-ca.crt: no such file or directory) + SRIOVFailedToConfigureVF description: OCP Versions 4.14.34, 4.15.25, 4.16.7 and ALL subsequent versions include kernel datastructure changes which are not compatible with older versions of the SR-IOV operator. Please update SR-IOV operator to versions dated 20240826 or newer before updating OCP. + SRIOVFailedToConfigureVF URL: https://issues.redhat.com/browse/NHE-1171 + reason: EvaluationFailed + status: Unknown + type: Recommended + release: + channels: + - candidate-4.16 + - candidate-4.17 + - eus-4.16 + - fast-4.16 + - stable-4.16 + image: quay.io/openshift-release-dev/ocp-release@sha256:fb321a3f50596b43704dbbed2e51fdefd7a7fd488ee99655d03784d0cd02283f + url: https://access.redhat.com/errata/RHSA-2024:5107 + version: 4.16.7 + risks: + - matchingRules: + - promql: + promql: | + group(csv_succeeded{_id="d6d42268-7dff-4d37-92cf-691bd2d42f41", name=~"sriov-network-operator[.].*"}) + or + 0 * group(csv_count{_id="d6d42268-7dff-4d37-92cf-691bd2d42f41"}) + type: PromQL + message: OCP Versions 4.14.34, 4.15.25, 4.16.7 and ALL subsequent versions + include kernel datastructure changes which are not compatible with older + versions of the SR-IOV operator. Please update SR-IOV operator to versions + dated 20240826 or newer before updating OCP. + name: SRIOVFailedToConfigureVF + url: https://issues.redhat.com/browse/NHE-1171 +---- diff --git a/modules/hcp-get-upgrade-versions.adoc b/modules/hcp-get-upgrade-versions.adoc new file mode 100644 index 0000000000..56f43b4b6a --- /dev/null +++ b/modules/hcp-get-upgrade-versions.adoc @@ -0,0 +1,77 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-updating.adoc + +:_mod-docs-content-type: CONCEPT +[id="hcp-get-upgrade-versions_{context}"] += Updating the {product-title} version in a hosted cluster + +{hcp-capital} enables the decoupling of updates between the control plane and the data plane. + +As a cluster service provider or cluster administrator, you can manage the control plane and the data separately. + +You can update a control plane by modifying the `HostedCluster` custom resource (CR) and a node by modifying its `NodePool` CR. Both the `HostedCluster` and `NodePool` CRs specify an {product-title} release image in a `.release` field. + +To keep your hosted cluster fully operational during an update process, the control plane and the node updates must follow the link:https://kubernetes.io/releases/version-skew-policy/[Kubernetes version skew policy]. + +[id="hcp-mce-hub-cluster_{context}"] +== The {mce-short} hub management cluster + +The {mce} requires a specific {product-title} version for the management cluster to remain in a supported state. You can install the {mce-short} from OperatorHub in the {product-title} web console. + +See the following support matrices for the {mce-short} versions: + +* link:https://access.redhat.com/articles/7086906[{mce-short} 2.7] +* link:https://access.redhat.com/articles/7073030[{mce-short} 2.6] +* link:https://access.redhat.com/articles/7056007[{mce-short} 2.5] +* link:https://access.redhat.com/articles/7027079[{mce-short} 2.4] + +The {mce-short} supports the following {product-title} versions: + +* The latest unreleased version +* The latest released version +* Two versions before the latest released version + +You can also get the {mce-short} version as a part of {rh-rhacm-first}. + +[id="hcp-supported-ocp-versions_{context}"] +== Supported {product-title} versions in a hosted cluster + +When deploying a hosted cluster, the {product-title} version of the management cluster does not affect the {product-title} version of a hosted cluster. + +The HyperShift Operator creates the `supported-versions` ConfigMap in the `hypershift` namespace. The `supported-versions` ConfigMap describes the range of supported {product-title} versions that you can deploy. + +See the following example of the `supported-versions` ConfigMap: + +[source,yaml] +---- +apiVersion: v1 +data: + server-version: 2f6cfe21a0861dea3130f3bed0d3ae5553b8c28b + supported-versions: '{"versions":["4.17","4.16","4.15","4.14"]}' +kind: ConfigMap +metadata: + creationTimestamp: "2024-06-20T07:12:31Z" + labels: + hypershift.openshift.io/supported-versions: "true" + name: supported-versions + namespace: hypershift + resourceVersion: "927029" + uid: f6336f91-33d3-472d-b747-94abae725f70 +---- + +[IMPORTANT] +==== +To create a hosted cluster, you must use the {product-title} version from the support version range. However, the {mce-short} can manage only between `n+1` and `n-2` {product-title} versions, where `n` defines the current minor version. You can check the {mce-short} support matrix to ensure the hosted clusters managed by the {mce-short} are within the supported {product-title} range. +==== + +To deploy a higher version of a hosted cluster on {product-title}, you must update the {mce-short} to a new minor version release to deploy a new version of the Hypershift Operator. Upgrading the {mce-short} to a new patch, or z-stream, release does not update the HyperShift Operator to the next version. + +See the following example output of the `hcp version` command that shows the supported {product-title} versions for {product-title} 4.16 in the management cluster: + +[source,terminal] +---- +Client Version: openshift/hypershift: fe67b47fb60e483fe60e4755a02b3be393256343. Latest supported OCP: 4.17.0 +Server Version: 05864f61f24a8517731664f8091cedcfc5f9b60d +Server Supports OCP Versions: 4.17, 4.16, 4.15, 4.14 +---- diff --git a/modules/updating-node-pools-for-hcp.adoc b/modules/hcp-update-node-pools.adoc similarity index 81% rename from modules/updating-node-pools-for-hcp.adoc rename to modules/hcp-update-node-pools.adoc index b2f3cf0882..51cd8d577e 100644 --- a/modules/updating-node-pools-for-hcp.adoc +++ b/modules/hcp-update-node-pools.adoc @@ -4,10 +4,12 @@ // * hosted_control_planes/hcp-updating.adoc :_mod-docs-content-type: PROCEDURE -[id="updating-node-pools-for-hcp_{context}"] -= Updating node pools for {hcp} +[id="hcp-update-node-pools_{context}"] += Updating node pools in a hosted cluster -On {hcp}, you can update your version of {product-title} by updating the node pools. The node pool version must not surpass the hosted control plane version. +You can update your version of {product-title} by updating the node pools in your hosted cluster. The node pool version must not surpass the hosted control plane version. + +The `.spec.release` field in the `NodePool` custom resource (CR) shows the version of a node pool. .Procedure diff --git a/modules/updating-hosted-cluster.adoc b/modules/hcp-update-ocp-hc.adoc similarity index 64% rename from modules/updating-hosted-cluster.adoc rename to modules/hcp-update-ocp-hc.adoc index e4bac1ba7b..2a01fb3c2c 100644 --- a/modules/updating-hosted-cluster.adoc +++ b/modules/hcp-update-ocp-hc.adoc @@ -4,10 +4,22 @@ // * hosted_control_planes/hcp-updating.adoc :_mod-docs-content-type: PROCEDURE -[id="updating-hosted-cluster_{context}"] -= Updating the hosted cluster for {hcp} +[id="hcp-update-ocp-hc_{context}"] += Updating a control plane in a hosted cluster -On {hcp}, you can upgrade your version of {product-title} by updating the hosted cluster. +On {hcp}, you can upgrade your version of {product-title} by updating the hosted cluster. The `.spec.release` in the `HostedCluster` custom resource (CR) shows the version of the control plane. The `HostedCluster` updates the `.spec.release` field to the `HostedControlPlane.spec.release` and runs the appropriate Control Plane Operator version. + +The `HostedControlPlane` resource orchestrates the rollout of the new version of the control plane components along with the {product-title} component in the data plane through the new version of the Cluster Version Operator (CVO). The `HostedControlPlane` includes the following artifacts: + +* CVO +* Cluster Network Operator (CNO) +* Cluster Ingress Operator +* Manifests for the Kube API server, scheduler, and manager +* Machine approver +* Autoscaler +* Infrastructure resources to enable ingress for control plane endpoints such as the Kube API server, ignition, and konnectivity + +You can set the `.spec.release` field in the `HostedCluster` CR to update the control plane by using the information from the `status.version.availableUpdates` and `status.version.conditionalUpdates` fields. .Procedure diff --git a/modules/hcp-update-using-mce-console.adoc b/modules/hcp-update-using-mce-console.adoc new file mode 100644 index 0000000000..e4e6c0f522 --- /dev/null +++ b/modules/hcp-update-using-mce-console.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-updating.adoc + +:_mod-docs-content-type: PROCEDURE +[id="hcp-update-using-mce-console_{context}"] += Updating a hosted cluster by using the {mce-short} console + +You can update your hosted cluster by using the {mce-short} console. + +[IMPORTANT] +==== +Before updating a hosted cluster, you must refer to the available and conditional updates of a hosted cluster. Choosing a wrong release version might break the hosted cluster. +==== + +.Procedure + +. Select *All clusters*. + +. Navigate to *Infrastructure* -> *Clusters* to view managed hosted clusters. + +. Click the *Upgrade available* link to update the control plane and node pools. diff --git a/modules/hcp-updating-requirements.adoc b/modules/hcp-updating-requirements.adoc index c784acbbca..4b63c4131f 100644 --- a/modules/hcp-updating-requirements.adoc +++ b/modules/hcp-updating-requirements.adoc @@ -18,4 +18,4 @@ You must upgrade the {product-title} cluster, {mce-short}, hosted cluster, and n . Upgrade an {product-title} cluster to the latest version. For more information, see "Updating a cluster using the web console" or "Updating a cluster using the CLI". . Upgrade the {mce-short} to the latest version. For more information, see "Updating installed Operators". -. Upgrade the hosted cluster and node pools from the previous {product-title} version to the latest version. For more information, see "Updating the hosted cluster for {hcp}" and "Updating node pools for {hcp}". +. Upgrade the hosted cluster and node pools from the previous {product-title} version to the latest version. For more information, see "Updating a control plane in a hosted cluster" and "Updating node pools in a hosted cluster".