openshift · xenolinux · Jul 1, 2025
diff --git 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
@@ -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 <hosted_cluster_namespace> get -o jsonpath='{.status.version.desired.channels}' hostedcluster <hosted_cluster_name>
+----
 
-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 <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> --type=merge -p '{"spec":{"channel":"<channel>"}}' <1>
+----
+<1> Replace `<channel>` 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 <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> --type=merge -p '{"spec":{"release":{"image":"<release_payload>"}}}' <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 `<release_payload>` 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 <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> -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 <hosted_cluster_namespace> hostedcluster <hosted_cluster_name> -o yaml
+$ oc get hostedcluster <hosted_cluster_name> -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 <hosted_cluster_name> -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 <hosted_cluster_name> -o jsonpath-as-json='{.status.version.history}'
 ----
diff --git a/modules/hcp-update-service-troubleshooting.adoc 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 <hosted_cluster_namespace> get -o jsonpath-as-json='{.status.conditions[?(@.type == "ClusterVersionRetrievedUpdates")]}' hostedcluster <hosted_cluster_name>
+----
diff --git a/modules/hcp-update-service.adoc 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 <hosted_cluster_name> --type=merge -p '{"spec":{"updateService":<update_server_url>"}}' <1>
+----
+<1> Replace `<update_service_url>` 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 <hosted_cluster_name> -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 <hosted_cluster_name> -o jsonpath='{.spec.updateService}'
+----
++
+.Example output
+[source,terminal]
+----
+https://custom-update-service.example.com/api/upgrades_info/v1/graph
+----