Deploy ARO with Managed Identities (Workload Identity Federation) via Azure CLI
This content is authored by Red Hat experts, but has not yet been tested on every supported configuration. This guide has been validated on OpenShift 4.20. Operator CRD names, API versions, and console paths may differ on other versions.
Overview
This guide creates an Azure Red Hat OpenShift (ARO) cluster that uses:
- one user-assigned managed identity for the cluster;
- eight platform workload identities for ARO and OpenShift operators;
- Azure role assignments scoped to the required identities, virtual network, and subnets.
Important
- Use Azure CLI 2.84.0 or later.
- Existing service-principal-based ARO clusters cannot be converted to managed-identity clusters; create a new cluster instead.
- The networking and role assignments below assume there is no pre-attached NSG, route table, or NAT gateway. Additional network resources require additional role assignments.
- Run the commands from the same shell session, or save the variables in a local script that is excluded from source control.
This guide was originally adapted from Ken Moini’s HackMD deployment guide and has since been updated and validated against the current Azure CLI managed identity workflow.
Prerequisites
You need:
- an Azure subscription with sufficient ARO quota;
- permission to create resource groups, networks, managed identities, and role assignments;
- a Red Hat pull secret saved locally;
- Azure CLI 2.84.0 or later.
Check the CLI version:
Confirm the managed-identity flags are available:
Sign in and select the intended subscription:
Choose the intended subscription name or ID from the output, then set it:
1. Set variables
Adjust these values for your environment:
Review the values before creating resources:
Stop and correct the variable values before continuing if anything is unexpected.
2. Automated deployment
The included script performs the same deployment described in this guide.
Export any variables you want to override, then download and run the script:
Review the script before running it, especially resource-group names, network ranges, and VM sizes.
3. Register required Azure resource providers
Verify registration:
All five providers should report Registered.
4. Create the resource groups and network
This example creates one /22 VNet with two empty /23 subnets:
5. Create the nine user-assigned managed identities
Verify the identities:
The result should contain nine identities.
6. Capture resource IDs, scopes, and principal IDs
Verify that the values are populated:
7. Create the required role assignments
The commands below use the built-in role definition IDs documented for ARO managed-identity clusters.
7.1 Allow the cluster identity to manage federated credentials
The cluster identity requires this assignment on each of the eight platform identities:
7.2 Assign subnet-scoped operator roles
Cloud Controller Manager:
Ingress:
Machine API:
ARO Operator:
7.3 Assign VNet-scoped operator roles
Cloud Network Config:
File CSI Driver:
Image Registry:
7.4 Assign the Azure Red Hat OpenShift resource provider role
8. Verify role-assignment counts
Expected minimums for this basic network layout:
The Disk CSI Driver identity having zero direct Azure RBAC assignments at this stage is expected. The cluster identity still has its assignment over the Disk CSI Driver identity so that the required federated credential can be created.
9. Check VM SKU availability and quota
List the intended VM sizes and restrictions:
An empty Restrictions array means the VM size is available in the selected region. Any entries in Restrictions indicate that the SKU cannot be used under the shown conditions.
Check DSv5-family usage:
ARO needs sufficient quota for the bootstrap, control-plane, and worker nodes during installation.
10. Optionally select an OpenShift version
List installable versions:
Set a version only when a specific release is required:
Otherwise, omit --version and allow ARO to select its default supported version.
11. Validate the configuration
Run ARO validation before cluster creation:
az aro validate produces no output when validation succeeds. Any validation failure is returned as an error.
12. Create the cluster
Explicitly set VM sizes. This avoids an Azure CLI validation error where the worker VM size may be passed as an empty value:
The command above uses --no-wait so that cluster creation runs asynchronously. Monitor the deployment in the next section.
If you set ARO_VERSION, add --version "$ARO_VERSION" to the create command.
13. Monitor deployment
Check the current deployment status:
To block until cluster creation finishes, run:
List the cluster:
14. Retrieve credentials and log in
After deployment succeeds:
Retrieve the API and console URLs:
Troubleshooting
Azure CLI emits a Python SyntaxWarning
A warning similar to the following is not an Azure deployment failure:
Verify the command result and resource state rather than editing files under the Homebrew or Azure CLI installation directory.
Worker VM size is empty
Symptom:
Resolution: specify both VM sizes explicitly:
Confirm the SKUs are unrestricted in the target region before retrying.
Cluster creation needs more detail
Add --debug to the az aro create command when you need verbose Azure CLI request and response details for troubleshooting.
The shell closes or variables are lost
Opening a new terminal creates a new shell, so all unexported variables are lost. Rerun the variable block and recapture IDs before retrying.
Check whether the cluster was created before issuing another create command:
Creating: do not rerun creation; monitor the existing deployment.Succeeded: creation completed.Failed: inspect the returned error and deployment activity.ResourceNotFound: no cluster resource exists, so it is normally safe to retry after correcting the cause.
Role assignment creation returns an authorization error
The account running these commands must be able to create role assignments at all required scopes. Having only resource creation permissions may not be sufficient.
Existing NSG, route table, or NAT gateway
The required role assignments in this guide already cover the ARO virtual network and control plane and worker subnets.
If you attach additional network resources, such as network security groups, route tables, NAT gateways, or additional subnets, assign the required operator roles to those resources before cluster creation.
Cleanup
Delete the ARO cluster:
The --delete-identities true option deletes the managed identities associated with the cluster. It does not delete resource groups or network resources.
For a disposable lab where the resource groups contain nothing else, deleting both resource groups is the simplest complete cleanup:
Do not delete shared resource groups.
