From a7772d27ff48af747b4981ce884802947925e089 Mon Sep 17 00:00:00 2001 From: xenolinux Date: Tue, 1 Jul 2025 16:23:52 +0530 Subject: [PATCH] OSDOCS#14808: HCP updates additions and update --- hosted_control_planes/hcp-updating.adoc | 12 ++ modules/hcp-get-ocp-channel.adoc | 168 ++++++------------ .../hcp-update-service-troubleshooting.adoc | 22 +++ modules/hcp-update-service.adoc | 48 +++++ 4 files changed, 136 insertions(+), 114 deletions(-) create mode 100644 modules/hcp-update-service-troubleshooting.adoc create mode 100644 modules/hcp-update-service.adoc diff --git a/hosted_control_planes/hcp-updating.adoc b/hosted_control_planes/hcp-updating.adoc index 8222fc7bea34..dc339502f80a 100644 --- a/hosted_control_planes/hcp-updating.adoc +++ b/hosted_control_planes/hcp-updating.adoc @@ -21,11 +21,23 @@ include::modules/hcp-updating-requirements.adoc[leveloffset=+1] include::modules/hcp-get-ocp-channel.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources + +* xref:../updating/understanding_updates/understanding-update-channels-release.adoc#understanding-update-channels-releases[Understanding update channels and releases] +* xref:../updating/updating_a_cluster/updating-cluster-cli.adoc#update-upgrading-oc-adm-upgrade-status_updating-cluster-cli[Gathering cluster update status using oc adm upgrade status (Technology Preview)] + include::modules/hcp-get-upgrade-versions.adoc[leveloffset=+1] // Updates for the hosted cluster include::modules/hcp-updates-hosted-cluster.adoc[leveloffset=+1] +// Setting UpdateService field in a hosted cluster +include::modules/hcp-update-service.adoc[leveloffset=+1] + +// Troubleshooting: Setting UpdateService field in a hosted cluster +include::modules/hcp-update-service-troubleshooting.adoc[leveloffset=+2] + // Updates for node pools include::modules/hcp-updates-node-pools.adoc[leveloffset=+1] diff --git a/modules/hcp-get-ocp-channel.adoc b/modules/hcp-get-ocp-channel.adoc index e98fae7ea7e3..3917566c33b2 100644 --- a/modules/hcp-get-ocp-channel.adoc +++ b/modules/hcp-get-ocp-channel.adoc @@ -2,134 +2,74 @@ // // * hosted_control_planes/hcp-updating.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: PROCEDURE [id="hcp-get-ocp-channel_{context}"] -= Setting channels in a hosted cluster += Updating your hosted cluster -You can see available updates in the `HostedCluster.Status` field of the `HostedCluster` custom resource (CR). +You can update your hosted cluster by setting a channel that matches with your desired channel semantics. -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): +The initial `HostedCluster` resource does not have any information in the `status.version.availableUpdates` and `status.version.conditionalUpdates` fields. After you set the `spec.release` field to the {product-title} release version, the HyperShift Operator updates the `status.version` field with the available and conditional updates. -* `status.version.availableUpdates` -* `status.version.conditionalUpdates` +.Procedure -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. +. Check recommended {product-title} channels by running the following command: ++ +[source,terminal] +---- +$ oc -n get -o jsonpath='{.status.version.desired.channels}' hostedcluster +---- -See the following example of the `HostedCluster` CR that contains the channel configuration: +. Set a channel in your hosted cluster that matches with your desired channel semantics. For more information about channels and releases, see "Understanding update channels and releases". Run the following command: ++ +[source,terminal] +---- +$ oc patch -n hostedcluster --type=merge -p '{"spec":{"channel":""}}' <1> +---- +<1> Replace `` with the {product-title} release version that you specified in `spec.release`. For example, if you set the `spec.release` to `ocp-release:4.18.4-multi`, you can set `spec.channel` to candidate-4.18, fast-4.19, candidate-4.20, and so on. For more information about channels, see "Understanding update channels and releases". -[source,yaml] +. Update the `spec.release` field of the `HostedCluster` to trigger the control plane rollout by running the following command: ++ +[source,terminal] ---- -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 +$ oc patch -n hostedcluster --type=merge -p '{"spec":{"release":{"image":""}}}' <1> ---- -<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`. +<1> Replace `` with the {product-title} release payload that you can find in the `availableUpdates` or `conditionalUpdates` fields. -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: +. Check the list of available updates for your hosted cluster by running the following command: ++ +[source,terminal] +---- +$ oc get -n hostedcluster -o jsonpath='{.status.version.availableUpdates}' +---- +. Monitor the progress of your ongoing update, the update rollout status, timestamps, and issues by using the information retrieved by the Cluster Version Operator (CVO): + +.. Check the status of the `ClusterVersionProgressing` and `ClusterVersionSucceeding` conditions in your `HostedCluster` resource by running the following command: ++ [source,terminal] ---- -$ oc get -n hostedcluster -o yaml +$ oc get hostedcluster -o jsonpath-as-json='{.status.conditions}' ---- -.Example output -[source,yaml] +.. Optional: To retrieve more detailed information about the status of your update, see "Gathering cluster update status using oc adm upgrade status (Technology Preview)". + +.. Run the following command to check the status of conditions: ++ +[source,terminal] +---- +$ oc get hostedcluster -o jsonpath='{.status.conditions}' +---- ++ +See the following update rollout status conditions: + +* `ClusterVersionSucceeding`: Indicates if the cluster is successfully updating. +* `ClusterVersionProgressing`: Indicates if the update is actively progressing. + +.Verification + +* Verify that the `history` field in the `HostedCluster` resource indicates a status as `Completed`. Run the following command: ++ +[source,terminal] ---- -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 +$ oc get hostedcluster -o jsonpath-as-json='{.status.version.history}' ---- diff --git a/modules/hcp-update-service-troubleshooting.adoc b/modules/hcp-update-service-troubleshooting.adoc new file mode 100644 index 000000000000..53ef7775d594 --- /dev/null +++ b/modules/hcp-update-service-troubleshooting.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-updating.adoc + +:_mod-docs-content-type: CONCEPT +[id="hcp-update-service-troubleshooting_{context}"] += Troubleshooting the updateService field setting + +If you face issues when configuring the update service in your hosted cluster, consider the following troubleshooting factors: + +* Connection issues: If the cluster is unable to reach the specified update service, confirm that the service URL is accessible from the cluster network. + +* Update service compatibility: Ensure that an update information provided by the specified update service is compatible with the {product-title} versions used by the hosted cluster. + +* Fallback behavior: If the update service is incorrectly configured or unreachable, update recommendations might not be available. Verify the configuration and network connectivity as necessary. + +* `ClusterVersionRetrievedUpdates`: Ensure that the Cluster Version Operator (CVO) retrieved your desired updates by checking the status of the `ClusterVersionRetrievedUpdates` field. Run the following command: ++ +[source,terminal] +---- +$ oc -n get -o jsonpath-as-json='{.status.conditions[?(@.type == "ClusterVersionRetrievedUpdates")]}' hostedcluster +---- diff --git a/modules/hcp-update-service.adoc b/modules/hcp-update-service.adoc new file mode 100644 index 000000000000..8000183353f3 --- /dev/null +++ b/modules/hcp-update-service.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * hosted_control_planes/hcp-updating.adoc + +:_mod-docs-content-type: PROCEDURE +[id="hcp-update-service_{context}"] += Setting the updateService field in HostedCluster + +You can configure the update service by using a specific update service URL in the `updateService` field of the `HostedCluster` custom resource (CR). By default, the hosted cluster uses the OpenShift Update Service (OSUS) based on its region and configuration. + +Consider the following environments where you can use the update service: + +* Private or disconnected: To update your cluster in an environment without access to the public OSUS. +* Regional: To direct the update service to a specific regional server for compliance or performance optimization. +* Custom: For environments that host their own OSUS and need updates to be sourced internally rather than from the default Red{nbsp}Hat services. + +.Procedure + +* To set a custom update service, add the update service URL to the `updateService` field in the `HostedCluster` CR. Run the following command: ++ +[source,terminal] +---- +$ oc patch hostedcluster --type=merge -p '{"spec":{"updateService":"}}' <1> +---- +<1> Replace `` with the URL of your desired update service. + + +.Verification + +. Verify that the `channel` field shows the target release information retrieved by the CVO by running the following command: ++ +[source,terminal] +---- +$ oc get hostedcluster -o jsonpath='{.status.version.desired}' +---- + +. Verify that the update service URL is successfully set in the `updateService` field by running the following command: ++ +[source,terminal] +---- +$ oc get hostedcluster -o jsonpath='{.spec.updateService}' +---- ++ +.Example output +[source,terminal] +---- +https://custom-update-service.example.com/api/upgrades_info/v1/graph +----