OSDOCS#14808: HCP updates additions and updates

[xenolinux]

Version(s): 4.14+

Issue: https://issues.redhat.com/browse/OSDOCS-14808

Link to docs preview: https://94496--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-updating.html#hcp-get-ocp-channel_hcp-updating

QE review:

• QE has approved this change.

Additional information:

[ocpdocs-previewbot]

🤖 Thu Jul 24 11:20:02 - Prow CI generated the docs preview:

https://94496--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-updating.html

[jiezhao16]

/lgtm

[wking]

Are there placeholder conventions in openshift-docs? xxxxx seems like a surprising choice. I see you using ... a few lines above; maybe you could use sha256:... here?

[xenolinux]

... is reserved for the YAML file to show continuous code flow before and after. Using <id> placeholder instead of xxxxx

[wking]

I'm not sure who's QE for HyperShift-update docs, but jsonpath output is single-line JSON. You can get multi-line JSON output with kubernetes/kubernetes#89660 (kubernetes/kubernetes@ba386ab)'s jsonpath-as-json, but I'm not aware of a jsonpath-as-yaml. So you either need to stick with -o yaml in the command to match your output-syntax claim here, or otherwise adjust your output-syntax claim and/or the query to be internally consistent.

[xenolinux]

Makes sense. Sticking with -o yaml

[wking]

nit: do we say "CR" in docs? I'd have expected "resource" here, to avoid the acronym (and hopefully make this more accessible for new readers) and drop the C/custom (because "is this resource custom?" doesn't seem relevant to this procedure).

[xenolinux]

Agree. Addressed; removed the acronym CR

[wking]

nit: If we know what we want to replace, I prefer oc patch ... to oc edit .... It gives you a conveniently copy/paste-able log in your terminal for "this is what I changed", and it avoids having to hunt out your particular property from the other information edit would show you.

[xenolinux]

Thanks. That's a good point. Sticking with oc patch

[wking]

You should set channel before requesting an update (by bumping release). channel tells the cluster what kind of updates you're interested in, and setting channel and then waiting some time (minutes or less?) will give you the cluster and OpenShift Update Service (or a custom updateService) opinions of your update options. You can chose your target release from among those options, or strike out on your own (although personally, striking out on your own seems like it involves taking on more responsibility than I'd want for my own clusters). But your current position here bumping channel after setting release doesn't make sense to me.

[xenolinux]

I see. Changed the current position of the setting channel instruction

[wking]

The section heading here is currently Setting channels in a hosted cluster. For that, you want to:

1. Check the channels currently available for your current release. Something like oc -n <hosted_cluster_namespace> get -o jsonpath='{.status.version.desired.channels}' hostedcluster<hosted_cluster_name>.
2. Of those channels, select the one that matches your intended semantics, and set it with oc -n <hosted_cluster_namespace> patch hostedcluster <hosted_cluster_name> --type=json -p '[{"op": "add", "path": "/spec/channel", "value": "stable-<4.y>"}]' or whatever.

You don't need to look at availableUpdates (that's something you'd do pre-update to consume the information setting a channel helped you configure). And you don't need to bump spec.release (that's something you'd do once you wanted to launch an update). And you don't need to run oc adm upgrade status (that's something you can optionally do to keep an eye on an in-progress update).

[xenolinux]

@wking So do i need to include the following steps in a different section as these are not part of setting channel?

• Checking availableUpdates
• Bumping spec.release
• Checking in-progress status with oc adm upgrade status

[wking]

• Checking availableUpdates
• Bumping spec.release
• Checking in-progress status with oc adm upgrade status

Yeah, those are all part of Updating a cluster by using the CLI. The standalone/ClusterVersion-update docs currently include setting your desired channel as an early step in the update process, and while I see channel-setting and update-launching as distinct, I don't see many issues with combining in a single section like that. But if they're combined, the name of the combined section should focus on the fact that an update is being launched, because that has a much larger cluster impact (bug fixes, new functionality, etc.) compared to changing the channel (which just gets you different update advice).

[xenolinux]

Thanks. Updated the PR

[openshift-ci]

New changes are detected. LGTM label has been removed.

[wking]

history will tell you about whether the update is in-progress or completed, but won't tell you anything about how your update is going. For that, you probably want the ClusterVersionProgressing and ClusterVersionSucceeding conditions, to hear about how the CVO thinks its portion of the update is going. The HostedControlPlane controller also has its own portions of the update outside of the CVO's portion, and I'm not sure what the HyperShift maintainers want you to look at to see how those are going.

[xenolinux]

Addressed

[wking]

That just shows you "your spec patch worked". You can check that, but it seems likely that the patch command would exit non-zero with an error message if it didn't work, so I dunno if checking the spec after a successful patch adds much protection. For the troubleshooting factors listed above, you probably want to look at the ClusterVersionRetrievedUpdates condition, and also check status.version.desired for metadata like channels to show that the CVO is able to reach the configured Update Service and retrieve information about the current target release.

[xenolinux]

Addressed

[wking]

nit: sometimes folks get stressed about changing their channel, so I think it's worth crisping up the language here. Changing the channel only changes the update advice that the cluster collects from the OpenShift Update Service, evaluates, and pushes through and up the chain to HostedCluster's status.version.*. It doesn't cause any new code to roll out anywhere. If you're about to use HostedCluster status.version.* information to select a new target release and launch an update, you want to be using a channel that matches your desired semantics. But things only start updating when you patch spec.release.

[xenolinux]

Addressed - Rephrased the language.

[wking]

you have options beyond stable, and also beyond strictly matching your current 4.y. For example, stable-4.18 doesn't include any 4.19 or later releases, and some of the folks currently running 4.18.z releases will eventually want to update to 4.19 releases. Right now, 4.18.4 is in:

$ curl -s 'https://api.openshift.com/api/upgrades_info/graph?channel=stable-4.18' | jq -r '.nodes[] | select(.version == "4.18.4").metadata["io.openshift.upgrades.graph.release.channels"]'
candidate-4.18,eus-4.18,fast-4.18,stable-4.18,candidate-4.19,fast-4.19,candidate-4.20

[wking]

jsonpath will dump these all out as one line, which can be hard reading. You may want to use jsonpath-as-json to get multiple lines for easier reading. I don't have a HostedCluster I can access at the moment, but just showing that rendering difference on a ClusterVersion in a standalone cluster:

$ oc get clusterversion version -o jsonpath='{.status.conditions}'
[{"lastTransitionTime":"2025-07-07T14:38:59Z","status":"True","type":"RetrievedUpdates"},{"lastTransitionTime":"2025-04-28T19:50:01Z","message":"Capabilities match configured spec","reason":"AsExpected","status":"False","type":"ImplicitlyEnabledCapabilities"},{...
$ oc get clusterversion version -o jsonpath-as-json='{.status.conditions}'
[
    [
        {
            "lastTransitionTime": "2025-07-07T14:38:59Z",
            "status": "True",
            "type": "RetrievedUpdates"
        },
        {
            "lastTransitionTime": "2025-04-28T19:50:01Z",
            "message": "Capabilities match configured spec",
            "reason": "AsExpected",
            "status": "False",
            "type": "ImplicitlyEnabledCapabilities"
        },
        ...

[wking]

while it's tech-preview, you'll also need to set environment variables to get status to work. If you want to inline the oc adm upgrade status, you may also want to inline that environment variable advice. Alternatively, you can probably drop the inline oc adm upgrade status and just link over to that section of the standalone update docs, and folks can find both the environment variable information and the subsequent oc adm upgrade status invocation over there.

[wking]

Up above, you said:

Check the status of the ClusterVersionProgressing and ClusterVersionSucceeding conditions...

but here you're also mentioning ClusterVersionAvailable. At the moment, ClusterVersionAvailable is a pretty boring condition, and it mostly (always?) True for all clusters that have finished installing. Official Available docs (which by the time they get up to HostedCluster has become ClusterVersionAvailable), if you want to lift any of that wording. But I think you want to be consistent about which condition types you point to during this step, regardless of whether you include ClusterVersionAvailable` in that set.

[xenolinux]

To eliminate the conflict - removed ClusterVersionAvailable : Confirms the availability of the updated version.

[wking]

This is another place where I think you probably want the multi-line jsonpath-as-json instead of the single-line jsonpath.

[wking]

You can exclude the other conditions here to make it easier to find the one you're asking for with something like:

$ oc -n <hosted_cluster_namespace> get -o jsonpath-as-json='{.status.conditions[?(@.type == "ClusterVersionRetrievedUpdates")]}' hostedcluster <hosted_cluster_name>

[wking]

troubleshooting sounds like its own section or something for the Verification section, and not part of the happy-path Procedure section

[xenolinux]

Addressed - created a separate section/module to cover troubleshooting factors.

[wking]

Why did you change spec.channel here to spec.release? spec.release is for requesting updates, but spec.channel is for configuring update advice.

[xenolinux]

Reverted to spec.channel

[wking]

While you certainly can set candidate-4.18, etc., they can be unsupported, early-access releases. I'd rather use fast-{product-version} and stable-{product-version} as examples here, to reduce the chances that someone reads this section, but does not read the referenced Understanding update channels and releases section, and sets candidate-* without realizing that channel's semantics.

[wking]

I don't understand this entry. Your previous two list entries are ${UNDERLYING_ISSUE}: ${SUGGESTED_STEPS}. But Fallback behavior doesn't sound like an issue. And you cover at least a slice of "network connectivity" under the Connection issues list entry. Which leaves only "incorrectly configured" here? But that's pretty vague. Maybe we can just drop this entry?

[xenolinux]

sounds good to drop it

[wking]

This sounds like it should be its own step at the top of this troubleshooting section. Then you can add possible categories of issues and suggested troubleshooting/recovery steps for the various issues it complains about? Although "if ClusterVersionRetrievedUpdates complains about connecting to the upstream Update Service URI, check to see if that URI is accessible from the cluster network" seems like it might be straightforward enough to not need an explicit listing? Maybe you can point out how to access the ClusterVersionRetrievedUpdates message, and then leave it up to the admin to take it from there, without trying to list off specific failure modes?

[xenolinux]

you can point out how to access the ClusterVersionRetrievedUpdates message, and then leave it up to the admin to take it from there, without trying to list off specific failure modes

In this case, I will move this command[1] in the main section (modules/hcp-update-service.adoc) as a part of TIP. And then when we are going to restructure this content, I can revisit everything related to HCP updates content.

[1] $ oc -n <hosted_cluster_namespace> get -o jsonpath-as-json='{.status.conditions[?(@.type == "ClusterVersionRetrievedUpdates")]}' hostedcluster <hosted_cluster_name>

Do we also need this sentence
Ensure that an update information provided by the specified update service is compatible with the {product-title} versions used by the hosted cluster.

[wking]

I think you want to use {.status.version.desired.channels} here (API refs).

With that change, I think this is a useful way to confirm Update Service retrieval is working, and that depends on the spec.channel configuration. But it also depends on spec.updateService, proxy config, etc. I think you want wording broader than your current "Verify that the channel field shows the target release information...". Maybe "Verify Update Service retrival..." or something?

[openshift-ci]

@xenolinux: all tests passed!

Full PR test history. Your PR dashboard.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[bergerhoffer]

The branch/enterprise-4.21 label has been added to this PR.

This is because your PR targets the main branch and is labeled for enterprise-4.20. And any PR going into main must also target the latest version branch (enterprise-4.21).

If the update in your PR does NOT apply to version 4.21 onward, please re-target this PR to go directly into the appropriate version branch or branches (enterprise-4.x) instead of main.