OSDOCS-13798 Adding user-specified identities to Azure #93377

bscott-rh · 2025-05-14T17:17:10Z

Version(s):
4.19

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

Link to docs preview:
Required permissions for IPI
Additional Azure configuration parameters

QE review:

QE has approved this change.

ocpdocs-previewbot · 2025-05-14T17:28:46Z

🤖 Wed May 21 19:42:34 - Prow CI generated the docs preview:
https://93377--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

patrickdillon

In addition to the fine-grained permissions updates, we should update the docs to remove the mentions of User Access Administrator, which is no longer required by default. This permission (or perhaps the less powerful RBAC Access Admin) is only required when users specify a User-Assigned Identity in the install config.

In the docs in 2.4.1 it says:

The Azure account that you use to create the identity is assigned the User Access Administrator and Contributor roles. These roles are required when:

Creating a service principal or user-assigned managed identity.
Enabling a system-assigned managed identity on a virtual machine.

We could probably change that to just.

The Azure account that you use to create the identity is assigned the Contributor role.

And then in 2.4.3 where we document how to create the service principal we can remove step 2 which adds the User Access Admin role.

Or, instead of removing it, we can add a note saying this is only necessary when users supply the values in the install config... I hope this makes sense, but I'm sure it's confusing so please LMK if you have questions.

modules/installation-configuration-parameters.adoc

jinyunma

Looks like that two parts are missed.

The permission of service principal or managed identity (attached to azure virtual machine and installer run in that VM) for IPI installation with user-assigned identity configured in install-config (attached to cluster nodes), which you added into installation-configuration-parameters.adoc.

Without minimal permission installation, both 'Contributor' role and 'User Access Administrator' are required.
With minimal permission installation, following optional permissions are required.
"Microsoft.ManagedIdentity/userAssignedIdentities/assign/action"
"Microsoft.ManagedIdentity/userAssignedIdentities/read"

UPI doc:

Remove the identity creation and role assignment steps (procedure 2 & 3) from Creating the Azure resource group , because user-assigned identity is also removed from UPI ARM template (openshift/installer#9625)
Same permissions you removed from IPI doc also need to be removed from minimal permission list in UPI doc

modules/installation-azure-permissions.adoc

modules/installation-azure-create-resource-group-and-identity.adoc

bscott-rh · 2025-05-20T14:51:49Z

Thanks @jinyunma I have incorporated your feedback, PTAL

jinyunma · 2025-05-21T00:42:24Z

@bscott-rh thanks for your update.

Following parts need to be updated in UPI installation doc.

Remove "User Access Administrator" role and following permissions in the section Required Azure permissions for user-provisioned infrastructure in UPI doc.
"Microsoft.ManagedIdentity/userAssignedIdentities/assign/action"
"Microsoft.ManagedIdentity/userAssignedIdentities/read"
"Microsoft.ManagedIdentity/userAssignedIdentities/write"
"Microsoft.ManagedIdentity/userAssignedIdentities/delete"
"Microsoft.Authorization/roleAssignments/read"
"Microsoft.Authorization/roleAssignments/write"
"Microsoft.Authorization/roleAssignments/delete"
Prerequisites about identity in the section Creating the bootstrap machine in Azure of UPI doc should be removed.
How do ARM templates in the UPI installation doc sync with templates in the installer repo? If it is manually maintained, templates "04_bootstrap.json", "05_masters.json" and "06_workers.json" should update to remove identity related parts, see CORS-3883: Remove user-assigned identity from ARM template installer#9625

modules/minimum-required-permissions-ipi-azure.adoc

jinyunma · 2025-05-21T01:21:26Z

modules/installation-configuration-parameters.adoc

+          subscription:
+|The subscription that contains the user-assigned identity.
+|String.
+


@patrickdillon Field "identity" is also under compute and defaultMachinePlatform, and specified single user-assigned identity can also be attached to worker nodes.
Do we need to add them into doc? Or anything I missed?

Yes I think so. @bscott-rh jinyun is correct, we do indeed support setting this on compute nodes (and default machine platform.) so I assume these fields need to be added to those machine pools?

bscott-rh · 2025-05-21T19:29:17Z

@bscott-rh thanks for your update.

Following parts need to be updated in UPI installation doc.

1. Remove "User Access Administrator" role and following permissions in the section [Required Azure permissions for user-provisioned infrastructure](https://93377--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_azure/upi/installing-azure-user-infra#minimum-required-permissions-upi-azure_installing-azure-user-infra) in UPI doc.
   "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action"
   "Microsoft.ManagedIdentity/userAssignedIdentities/read"
   "Microsoft.ManagedIdentity/userAssignedIdentities/write"
   "Microsoft.ManagedIdentity/userAssignedIdentities/delete"
   "Microsoft.Authorization/roleAssignments/read"
   "Microsoft.Authorization/roleAssignments/write"
   "Microsoft.Authorization/roleAssignments/delete"

2. Prerequisites about identity in the section [Creating the bootstrap machine in Azure](https://93377--ocpdocs-pr.netlify.app/openshift-enterprise/latest/installing/installing_azure/upi/installing-azure-user-infra#installation-creating-azure-bootstrap_installing-azure-user-infra) of UPI doc should be removed.

3. How do ARM templates in the UPI installation doc sync with templates in the installer repo? If it is manually maintained, templates "04_bootstrap.json", "05_masters.json" and "06_workers.json" should update to remove identity related parts, see [CORS-3883: Remove user-assigned identity from ARM template installer#9625](https://github.com/openshift/installer/pull/9625)

Thanks, I have incorporated these changes. On point 3, the ARM templates are imported from the repo like this:
https://raw.githubusercontent.com/openshift/installer/release-4.19/upi/azure/04_bootstrap.json so when the file is changed in the repo, the docs will be up to date automatically.

patrickdillon · 2025-05-21T19:31:54Z

modules/installation-configuration-parameters.adoc

+        type:
+|The type of identity used for control plane virtual machine.
+The `UserAssigned` identity is a standalone Azure resource provided by the user and assigned to control plane virtual machines.
+Identity can only be set for control plane nodes.


We can remove this line. It is inaccurate (out of date). I have updated openshift/installer#9717 to remove it from the installer code.

patrickdillon · 2025-05-21T19:34:25Z

modules/installation-creating-azure-service-principal.adoc

 * You have installed or updated the link:https://docs.microsoft.com/en-us/cli/azure/install-azure-cli-yum?view=azure-cli-latest[{azure-short} CLI].
 * You have an {azure-short} subscription ID.
-* If you are not assigning the `Contributor` and `User Administrator Access` roles to the service principal, you have created a custom role with the required {azure-short} permissions.
+* If you are not assigning the `Contributor` role to the service principal, you have created a custom role with the required {azure-short} permissions.


So now by default the installer creds need User Admin Access. Perhaps we want to stet this change? I'm not sure how to best handle the credentials as now the requirements are conditional.

openshift-ci · 2025-05-21T19:43:36Z

@bscott-rh: 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.

patrickdillon

@bscott-rh @jinyunma Once the future upstream changes land, the installer will no longer create an identity and the docs should look like they are currently (which is simpler), but until then it seems like the docs will get a bit more complex due to the various configurations.

patrickdillon · 2025-05-21T19:49:51Z

modules/minimum-required-permissions-ipi-azure.adoc

-.Required permissions for creating identity management resources
-[%collapsible]
-====
-* `Microsoft.ManagedIdentity/userAssignedIdentities/assign/action`
-* `Microsoft.ManagedIdentity/userAssignedIdentities/read`
-* `Microsoft.ManagedIdentity/userAssignedIdentities/write`
-====


With openshift/installer#9735, the permissions are required with the default configuration, but unnecessary if identity is set to None... So would we want to call them optional? Optional (Required with default config)? I'm also fine leaving this as is (not deleting it) and then adding a separate note saying they are not required when Identity: none...

patrickdillon · 2025-05-21T19:50:37Z

modules/minimum-required-permissions-upi-azure.adoc

 The following options are available to you:

-* You can assign the identity the `Contributor` and `User Access Administrator` roles. Assigning these roles is the quickest way to grant all of the required permissions.
+* You can assign the identity the `Contributor` role. Assigning this roles is the quickest way to grant all of the required permissions.


Probably want to stet this, especially as this is suppoed to be the "quickest" way... We could also add something to the effect of "If defaultMachinePool.platform.azure.identity.type is set to None only the Contributor role is needed."

patrickdillon · 2025-05-21T20:01:21Z

modules/minimum-required-permissions-ipi-azure.adoc

-* `Microsoft.Authorization/roleAssignments/read`
-* `Microsoft.Authorization/roleAssignments/write`


So now these two perms are technically "optional" but are required with the default install config settings...

patrickdillon · 2025-05-21T20:02:43Z

modules/minimum-required-permissions-ipi-azure.adoc

 * `Microsoft.Resources/subscriptions/resourcegroups/write`
 ====

+.Optional permissions for using a user-assigned identity


Perhaps

Suggested change

.Optional permissions for using a user-assigned identity

.Optional permissions for attaching an existing user-assigned identity to a node

patrickdillon · 2025-05-21T20:03:32Z

modules/minimum-required-permissions-ipi-azure.adoc

-.Required permissions for deleting authorization resources
-[%collapsible]
-====
-* `Microsoft.Authorization/roleAssignments/delete`
-====


Similar to other comments, this is now needed when the installer creates an identity (default)

patrickdillon · 2025-05-21T20:09:57Z

Perhaps we should add a Known Issue release note for OCPBUGS-56008 that ACR image pulls will not work (without workarounds) when identity is set to none?

bscott-rh · 2025-05-29T20:26:08Z

Closing in favor of #93959

bscott-rh added this to the Planned for 4.19 GA milestone May 14, 2025

bscott-rh added the branch/enterprise-4.19 label May 14, 2025

openshift-ci bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label May 14, 2025

bscott-rh force-pushed the OSDOCS-13798 branch from 8bc8d14 to 49061f2 Compare May 14, 2025 17:46

patrickdillon reviewed May 15, 2025

View reviewed changes

modules/installation-configuration-parameters.adoc Outdated Show resolved Hide resolved

modules/installation-configuration-parameters.adoc Outdated Show resolved Hide resolved

bscott-rh force-pushed the OSDOCS-13798 branch from 49061f2 to 3eea299 Compare May 15, 2025 18:54

jinyunma reviewed May 16, 2025

View reviewed changes

modules/installation-azure-permissions.adoc Show resolved Hide resolved

bscott-rh force-pushed the OSDOCS-13798 branch from 3eea299 to 282b5d6 Compare May 20, 2025 13:13

openshift-ci bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 20, 2025

bscott-rh force-pushed the OSDOCS-13798 branch from 282b5d6 to 43a9bba Compare May 20, 2025 13:36

ocpdocs-vale-bot reviewed May 20, 2025

View reviewed changes

modules/installation-azure-create-resource-group-and-identity.adoc Outdated Show resolved Hide resolved

bscott-rh force-pushed the OSDOCS-13798 branch from 43a9bba to 76e8809 Compare May 20, 2025 14:28

jinyunma reviewed May 21, 2025

View reviewed changes

OSDOCS-13798 Adding user-specified identities to Azure

5b4504a

bscott-rh force-pushed the OSDOCS-13798 branch from 76e8809 to 5b4504a Compare May 21, 2025 19:29

patrickdillon reviewed May 21, 2025

View reviewed changes

bscott-rh closed this May 29, 2025

		* `Microsoft.Authorization/roleAssignments/read`
		* `Microsoft.Authorization/roleAssignments/write`

	.Optional permissions for using a user-assigned identity
	.Optional permissions for attaching an existing user-assigned identity to a node

OSDOCS-13798 Adding user-specified identities to Azure #93377

OSDOCS-13798 Adding user-specified identities to Azure #93377

Uh oh!

Conversation

bscott-rh commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

patrickdillon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jinyunma left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bscott-rh commented May 20, 2025

Uh oh!

jinyunma commented May 21, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bscott-rh commented May 21, 2025

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 21, 2025

Uh oh!

patrickdillon 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!

patrickdillon commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bscott-rh commented May 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

bscott-rh commented May 14, 2025 •

edited

Loading

ocpdocs-previewbot commented May 14, 2025 •

edited

Loading

jinyunma left a comment •

edited

Loading

patrickdillon commented May 21, 2025 •

edited

Loading