[OSDOCS-19522]: Setting up workload identities for HCP on Azure by lahinson · Pull Request #111958 · openshift/openshift-docs

lahinson · 2026-05-19T19:32:57Z

Version(s): 4.22+

Issue: https://redhat.atlassian.net/browse/OSDOCS-19522

Link to docs preview: https://111958--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-azure.html#hcp-azure-workload-id-oidc_hcp-deploy-azure

QE review:

QE has approved this change

Additional information:

ocpdocs-previewbot · 2026-05-19T19:39:06Z

🤖 Fri May 29 16:05:14 - Prow CI generated the docs preview:

https://111958--ocpdocs-pr.netlify.app/
https://111958--ocpdocs-pr.netlify.app/openshift-enterprise/latest/hosted_control_planes/hcp-deploy/hcp-deploy-azure.html

lahinson · 2026-05-20T12:59:07Z

/retest

Nirshal · 2026-05-28T13:18:36Z

Thanks for writing this up, Laura! A few things I noticed:

Missing variable: SUBSCRIPTION_ID

In hcp-azure-oidc.adoc, the ccoctl azure create-oidc-issuer command uses ${SUBSCRIPTION_ID}, but this variable is never set. The environment variables block defines PERSISTENT_RG_NAME, LOCATION, CLUSTER_NAME, INFRA_ID, AZURE_CREDS, OIDC_STORAGE_ACCOUNT_NAME, and TENANT_ID — but not SUBSCRIPTION_ID. It should be added to the setup step.

Variable placement across modules

CLUSTER_NAME and INFRA_ID are defined in the OIDC module (hcp-azure-oidc.adoc) but aren't used there — they're only needed in the workload identities module (hcp-azure-workload-id.adoc). Meanwhile, the workload identities module doesn't define them, so users following just that page would be missing them. Suggest moving these two variables to hcp-azure-workload-id.adoc.

Flag alignment with upstream docs

Bryan's upstream docs PR (hypershift#8566) updates the required/optional flag classification for hcp create iam azure. A few things to align:

--resource-group-name is listed both in the main command and as optional (with default <name>-<infra-id>) — it should be one or the other. Upstream now treats it as required.
--location is in the main command (implying required), but upstream now lists it as optional with default eastus.
--output-file is listed as optional, but upstream now treats it as required.

Nirshal · 2026-05-28T13:20:25Z

@bryan-cox the --enable-kms flag for hcp create iam azure is not in scope for 4.22, correct? Just making sure we don't need to include it in this doc.

bryan-cox · 2026-05-28T16:41:40Z

+
+[IMPORTANT]
+====
+The first time that you set up an OIDC issuer, create it in a persistent resource group that will not be deleted when individual hosted clusters are deleted. By using a persistent resource group, you can reuse the same OIDC issuer across hosted clusters, reducing setup time. 


IMO, this whole section can be dropped. This comes from instructions for how we do things on the Red Hat side since we have a reaper on Azure that deletes everything every 12h.

bryan-cox · 2026-05-28T16:42:19Z

+
+* The {azure-short} command-line interface (CLI) is installed and configured.
+* The `jq` command-line JSON processor is installed.
+* The Cloud Credential Operator tool is installed.


Do we need to point them to where to get this?

Yes, that would be helpful. I actually don't see a procedure in the official docs about how to get the ccoctl utility, but I found a Knowledgebase article I can link to.

bryan-cox · 2026-05-28T16:45:09Z

+= Deleting {azure-short} Workload Identities
+
+[role="_abstract"]
+If you need to delete a hosted cluster on {azure-short}, first delete the hosted cluster and infrastructure, and then delete the Workload Identities.


I think this could be reworded to improve the intent behind the sentence. It currently reads to me like " To delete a hosted cluster on azure, first delete the hosted cluster..."

Good point -- will revise

bryan-cox · 2026-05-28T16:47:52Z

+
+* If you created infrastructure by using the Workload Identities, delete the infrastructure before you delete the identities.
+
+.Procedure


Shouldn't there be a procedure before this step to delete the infra before deleting the iam?

Yep. I haven't written the infra docs yet, though, because I was waiting to find out which upstream docs to use:

These: https://hypershift.pages.dev/how-to/azure/create-infra-separately/
Or these: https://hypershift.pages.dev/how-to/azure/create-self-managed-azure-cluster/#infrastructure-setup

After I have the infra docs written, I'll be sure to add the procedure about deleting infrastructure before this one.

bryan-cox

/lgtm

skopacz1

A few comments, otherwise LGTM!

skopacz1 · 2026-05-29T14:09:33Z

+----
+$ hcp destroy iam azure \
+    --azure-creds <azure_credentials_file> \
+    --workload-identities-file <workload-identities.json> \


I see why this is formatted this way, but it still technically goes against the way user-replaced values are typically formatted. I would suggest an alternative with underscores:

Suggested change

--workload-identities-file <workload-identities.json> \

--workload-identities-file <workload_identities_json> \

skopacz1 · 2026-05-29T14:12:27Z

+`<azure_credentials_file>`:: Specifies the {azure-short} credentials file with permission to create managed identities and federated credentials.
+`<resource_group>`:: Specifies the name of the resource group where you intend to create identities.
+`<oidc_issuer_url>`:: Specifies the URL of the OIDC identity provider for Workload Identity federation.
+`<workload-identities.json>`:: Specifies the output file path, such as `<name>-iam-output.json`.


Same suggestion here about the underscores, except in this case the description list item doesn't match what's in the code block above either way. I would make sure all mentions of this value in the assembly are consistently formatted

Good catch. I'll take a look to make sure everything is consistent.

skopacz1 · 2026-05-29T14:13:13Z

+`--location`:: Specifies the {azure-short} region for the managed identities. The default value is `eastus`.
+`--cloud`:: Specifies the {azure-short} cloud environment. The default value is `AzurePublicCloud`.


These don't seem to appear in the code block above

skopacz1 · 2026-05-29T14:14:30Z

+`--location`:: Specifies the {azure-short} region for the managed identities. The default value is `eastus`.
+`--cloud`:: Specifies the {azure-short} cloud environment. The default value is `AzurePublicCloud`.
+
+. Review the output file, which looks like the following example:


Not really a big deal either way, but maybe this is more of a verification step? I'm not sure since I'm not familiar with this content

Moved to a "Verification" section

skopacz1 · 2026-05-29T14:16:42Z

+[role="_additional-resources"]
+.Additional resources
+
+* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4]


I'm not sure about this, but technically if this is pointing out of the OCP docs, should it have a parenthetical about the destination?

Suggested change

* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4]

* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4 (Red{nbsp}Hat Knowledgebase article)]

Or is that only for like truly external docs such as from another company?

I think we use a parenthetical whenever we point out of the OCP docs, not just for truly external docs. Will fix.

openshift-ci · 2026-05-29T15:26:23Z

New changes are detected. LGTM label has been removed.

openshift-ci · 2026-05-29T16:06:06Z

@lahinson: 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.

lahinson · 2026-05-29T16:20:08Z

/retest

lahinson · 2026-05-29T17:07:15Z

/cherrypick enterprise-4.22

openshift-cherrypick-robot · 2026-05-29T17:08:08Z

@lahinson: new pull request created: #112516

Details

In response to this:

/cherrypick enterprise-4.22

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.

openshift-ci Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 19, 2026

lahinson added the branch/enterprise-4.22 label May 19, 2026

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch 6 times, most recently from 6b67ee4 to 2b04abc Compare May 19, 2026 20:57

lahinson added this to the Planned for 4.22 GA milestone May 19, 2026

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch 2 times, most recently from c82ca21 to dc82417 Compare May 20, 2026 17:06

ocpdocs-vale-bot reviewed May 20, 2026

View reviewed changes

Comment thread modules/hcp-azure-workload-id.adoc

ocpdocs-vale-bot reviewed May 20, 2026

View reviewed changes

Comment thread modules/hcp-azure-infra-sep.adoc

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch 4 times, most recently from be2b5b6 to 221cd3f Compare May 21, 2026 20:23

lahinson changed the title ~~[OSDOCS-19522]: Preparing to deploy HCP on Azure~~ [OSDOCS-19522]: Setting up workload identities for HCP on Azure May 27, 2026

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch from 221cd3f to 96481e7 Compare May 27, 2026 18:36

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch from 96481e7 to eb3bfbe Compare May 28, 2026 16:45

bryan-cox reviewed May 28, 2026

View reviewed changes

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch from eb3bfbe to bf0d386 Compare May 28, 2026 17:32

bryan-cox approved these changes May 28, 2026

View reviewed changes

openshift-ci Bot assigned bryan-cox May 28, 2026

openshift-ci Bot added the lgtm Indicates that a PR is ready to be merged. label May 28, 2026

lahinson added the merge-review-needed Signifies that the merge review team needs to review this PR label May 28, 2026

skopacz1 added the merge-review-in-progress Signifies that the merge review team is reviewing this PR label May 29, 2026

skopacz1 approved these changes May 29, 2026

View reviewed changes

skopacz1 added ok-to-merge and removed merge-review-in-progress Signifies that the merge review team is reviewing this PR merge-review-needed Signifies that the merge review team needs to review this PR labels May 29, 2026

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch from bf0d386 to 02dbbb5 Compare May 29, 2026 15:26

openshift-ci Bot removed the lgtm Indicates that a PR is ready to be merged. label May 29, 2026

[OSDOCS-19572]: Preparing to deploy HCP on Azure

76a33d8

lahinson force-pushed the osdocs-19522-hcp-azure-prep branch from 02dbbb5 to 76a33d8 Compare May 29, 2026 15:55

lahinson merged commit 5305f53 into openshift:main May 29, 2026
2 checks passed

openshift-cherrypick-robot mentioned this pull request May 29, 2026

[enterprise-4.22] [OSDOCS-19522]: Setting up workload identities for HCP on Azure #112516

Merged


		* If you created infrastructure by using the Workload Identities, delete the infrastructure before you delete the identities.

		.Procedure

	--workload-identities-file <workload-identities.json> \
	--workload-identities-file <workload_identities_json> \

		`--location`:: Specifies the {azure-short} region for the managed identities. The default value is `eastus`.
		`--cloud`:: Specifies the {azure-short} cloud environment. The default value is `AzurePublicCloud`.

	* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4]
	* link:https://access.redhat.com/solutions/7001811[How to obtain the ccoctl tool for OpenShift 4 (Red{nbsp}Hat Knowledgebase article)]

Conversation

lahinson commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

lahinson commented May 20, 2026

Uh oh!

Uh oh!

Uh oh!

Nirshal commented May 28, 2026

Uh oh!

Nirshal commented May 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bryan-cox left a comment

Choose a reason for hiding this comment

Uh oh!

skopacz1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

openshift-ci Bot commented May 29, 2026

Uh oh!

openshift-ci Bot commented May 29, 2026

Uh oh!

lahinson commented May 29, 2026

Uh oh!

Uh oh!

lahinson commented May 29, 2026

Uh oh!

openshift-cherrypick-robot commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

lahinson commented May 19, 2026 •

edited

Loading

ocpdocs-previewbot commented May 19, 2026 •

edited

Loading