OCPBUGS-122257: Discover OAuth route before generating cert in HCP OAuth procedure by Patrickdsa00 · Pull Request #119713 · openshift/openshift-docs

Patrickdsa00 · 2026-09-10T23:01:26Z

Rework the "Configuring OAuth server certificates for a hosted cluster" procedure so it no longer relies on a misleading placeholder hostname:

Remove the api-custom-cert-sample-hosted.sample-hosted.example.com placeholder, which implied the OAuth route lives on the API endpoint domain. The route is served on the management cluster's apps wildcard domain, consistent with the HyperShift documentation.
Reorder the steps so the OAuth route is discovered and stored in OAUTH_HOST before the test certificate is generated, so the certificate SAN uses the correct hostname and no certificate regeneration is needed.
Normalize placeholder names to the module's convention (<management_cluster_name>, <base_domain>).
Export OAUTH_HOST, add the missing shell prompt, fix the "kubconfig" typo, and clean up trailing whitespace.

Version(s):
4.20, 4.21, and 4.22

Issue:
https://redhat.atlassian.net/browse/OCPBUGS-122257

Link to docs preview: https://119713--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-certificates.html#hcp-oauth-server-cert_hcp-certificates

QE review:

QE has approved this change.

openshift-ci-robot · 2026-09-10T23:01:32Z

@Patrickdsa00: This pull request references Jira Issue OCPBUGS-122257, which is invalid:

expected the bug to target the "5.1.0" version, but no target version was set

Comment /jira refresh to re-evaluate validity if changes to the Jira bug are made, or edit the title of this pull request to link to a different bug.

The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Rework the "Configuring OAuth server certificates for a hosted cluster" procedure so it no longer relies on a misleading placeholder hostname:

Remove the api-custom-cert-sample-hosted.sample-hosted.example.com placeholder, which implied the OAuth route lives on the API endpoint domain. The route is served on the management cluster's apps wildcard domain, consistent with the HyperShift documentation.

Reorder the steps so the OAuth route is discovered and stored in OAUTH_HOST before the test certificate is generated, so the certificate SAN uses the correct hostname and no certificate regeneration is needed.

Normalize placeholder names to the module's convention (<management_cluster_name>, <base_domain>).

Export OAUTH_HOST, add the missing shell prompt, fix the "kubconfig" typo, and clean up trailing whitespace.

Version(s):
4.20, 4.21, and 4.22

Issue:
https://redhat.atlassian.net/browse/OCPBUGS-122257

Link to docs preview:

QE review:

QE has approved this change.

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 openshift-eng/jira-lifecycle-plugin repository.

openshift-ci · 2026-09-10T23:02:50Z

Hi @Patrickdsa00. Thanks for your PR.

I'm waiting for a openshift member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

Patrickdsa00 · 2026-09-11T00:32:22Z

/jira refresh

openshift-ci-robot · 2026-09-11T00:32:28Z

@Patrickdsa00: This pull request references Jira Issue OCPBUGS-122257, which is valid. The bug has been moved to the POST state.

3 validation(s) were run on this bug

bug is open, matching expected state (open)
bug target version (5.1.0) matches configured target version for branch (5.1.0)
bug is in the state New, which is one of the valid states (NEW, ASSIGNED, POST)

Details

In response to this:

/jira refresh

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 openshift-eng/jira-lifecycle-plugin repository.

lahinson · 2026-09-15T13:27:30Z

/ok-to-test

ocpdocs-previewbot · 2026-09-15T13:38:14Z

🤖 Fri Sep 18 19:26:38 - Prow CI generated the docs preview:

https://119713--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-certificates.html

openshift-ci-robot · 2026-09-15T13:48:13Z

@Patrickdsa00: This pull request references Jira Issue OCPBUGS-122257, which is valid.

3 validation(s) were run on this bug

bug is open, matching expected state (open)
bug target version (5.1.0) matches configured target version for branch (5.1.0)
bug is in the state POST, which is one of the valid states (NEW, ASSIGNED, POST)

Details

In response to this:

Rework the "Configuring OAuth server certificates for a hosted cluster" procedure so it no longer relies on a misleading placeholder hostname:

Remove the api-custom-cert-sample-hosted.sample-hosted.example.com placeholder, which implied the OAuth route lives on the API endpoint domain. The route is served on the management cluster's apps wildcard domain, consistent with the HyperShift documentation.

Reorder the steps so the OAuth route is discovered and stored in OAUTH_HOST before the test certificate is generated, so the certificate SAN uses the correct hostname and no certificate regeneration is needed.

Normalize placeholder names to the module's convention (<management_cluster_name>, <base_domain>).

Export OAUTH_HOST, add the missing shell prompt, fix the "kubconfig" typo, and clean up trailing whitespace.

Version(s):
4.20, 4.21, and 4.22

Issue:
https://redhat.atlassian.net/browse/OCPBUGS-122257

Link to docs preview: https://119713--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-certificates.html#hcp-oauth-server-cert_hcp-certificates

QE review:

QE has approved this change.

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 openshift-eng/jira-lifecycle-plugin repository.

jiezhao16 · 2026-09-15T14:37:51Z

-====

-. Confirm that the file exists by entering the following command:
+.. If the route name is `oauth`, confirm it by entering the following command:


The HyperShift always creates this route as 'oauth'.

jiezhao16 · 2026-09-15T14:39:56Z

 [source,terminal]
 ----
-$ ls tls.crt tls.key
+$ oc get route oauth -n ${HC_NAMESPACE}-${CLUSTER_NAME} -o yaml


To confirm the route exists and route name is 'oauth', a check like '$ oc get route oauth -n ${HC_NAMESPACE}-${CLUSTER_NAME}' is cleaner

jiezhao16 · 2026-09-15T14:44:32Z

 [source,terminal]
 ----
-$ oc get routes -n ${HC_NAMESPACE}-${CLUSTER_NAME}
+oauth-<hosted_cluster_namespace>-<hosted_cluster_name>.apps.<management_cluster_name>.<base_domain>


Here is the test log when I tested oauth, in my test setup, the hostedcluster name is 'jie-test', base domain is 'jiezhao-hypershift.qe.devcluster.openshift.com', it shows:
$ oc get route -n clusters-jie-test | grep oauth
oauth oauth-jie-test.jiezhao-hypershift.qe.devcluster.openshift.com oauth-openshift passthrough/None None
oauth-internal oauth.apps.jie-test.hypershift.local oauth-openshift passthrough/None None

so correct format should be:
oauth-<hosted_cluster_name>.<hosted_cluster_baseDomain>

Thanks for testing this! I think both of us are seeing correct but different behavior...

When deploying it I get the oauth-<hosted_cluster_namespace>-<hosted_cluster_name>.apps.<management_cluster_name>.<base_domain> format.

I guess it's because my cluster was deployed without external DNS set at creation (--external-dns-domain) while yours had it set. Below would return empty output here.
$ ./oc get hostedcluster <hc> -n <hc ns> -o jsonpath='{range .spec.services[?(@.service=="OAuthServer")]}{.servicePublishingStrategy.route.hostname}{"\n"}{end}'

Can you check that?

`oc explain hostedcluster.spec.services.servicePublishingStrategy.route.hostname
GROUP: hypershift.openshift.io
KIND: HostedCluster
VERSION: v1beta1

FIELD: hostname

DESCRIPTION:
hostname is the name of the DNS record that will be created pointing to the
Route and passed through to consumers of the service.
If omitted, the value will be inferred from management ingress.Spec.Domain.`

jiezhao16 · 2026-09-15T14:46:24Z

+$ oc create secret tls my-oauth-cert-secret \
+  --cert=path/to/tls.crt \
+  --key=path/to/tls.key \
+  -n $HC_NAMESPACE


path to cert and key should be same as line 86 and 87:
--cert=tls.crt
--key=tls.key \

…uth procedure Rework the "Configuring OAuth server certificates for a hosted cluster" procedure so it no longer relies on a misleading placeholder hostname: - Remove the api-custom-cert-sample-hosted.sample-hosted.example.com placeholder, which implied the OAuth route lives on the API endpoint domain. The route is served on the management cluster's `apps` wildcard domain, consistent with the HyperShift documentation. - Reorder the steps so the OAuth route is discovered and stored in OAUTH_HOST before the test certificate is generated, so the certificate SAN uses the correct hostname and no certificate regeneration is needed. - Normalize placeholder names to the module's convention (<management_cluster_name>, <base_domain>). - Export OAUTH_HOST, add the missing shell prompt, fix the "kubconfig" typo, and clean up trailing whitespace.

openshift-ci · 2026-09-18T19:28:14Z

@Patrickdsa00: all tests passed!

Full PR test history. Your PR dashboard.

Details

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.

openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Sep 10, 2026

openshift-ci-robot added the jira/invalid-bug Indicates that a referenced Jira bug is invalid for the branch this PR is targeting. label Sep 10, 2026

openshift-ci Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 10, 2026

openshift-ci-robot added jira/valid-bug Indicates that a referenced Jira bug is valid for the branch this PR is targeting. and removed jira/invalid-bug Indicates that a referenced Jira bug is invalid for the branch this PR is targeting. labels Sep 11, 2026

lahinson self-assigned this Sep 15, 2026

openshift-ci Bot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 15, 2026

lahinson added branch/enterprise-4.20 branch/enterprise-4.21 branch/enterprise-4.22 branch/enterprise-5.0 labels Sep 15, 2026

lahinson added this to the Continuous Release milestone Sep 15, 2026

jiezhao16 reviewed Sep 15, 2026

View reviewed changes

Patrickdsa00 force-pushed the hcp-oauth-cert-fix branch from 47272fa to d599d6b Compare September 18, 2026 19:11

openshift-ci Bot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Sep 18, 2026

Patrickdsa00 force-pushed the hcp-oauth-cert-fix branch from d599d6b to 498dbd3 Compare September 18, 2026 19:16

openshift-ci Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Sep 18, 2026

Conversation

Patrickdsa00 commented Sep 10, 2026 • edited by lahinson Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Sep 10, 2026

Uh oh!

openshift-ci Bot commented Sep 10, 2026

Uh oh!

Patrickdsa00 commented Sep 11, 2026

Uh oh!

openshift-ci-robot commented Sep 11, 2026

Uh oh!

lahinson commented Sep 15, 2026

Uh oh!

ocpdocs-previewbot commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openshift-ci-robot commented Sep 15, 2026

Uh oh!

jiezhao16 Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

jiezhao16 Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

jiezhao16 Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

Patrickdsa00 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

Patrickdsa00 Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

jiezhao16 Sep 15, 2026

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented Sep 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Patrickdsa00 commented Sep 10, 2026 •

edited by lahinson

Loading

ocpdocs-previewbot commented Sep 15, 2026 •

edited

Loading