ARO HCP Quickstart
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.22. Operator CRD names, API versions, and console paths may differ on other versions.
A quickstart guide to deploying an Azure Red Hat OpenShift cluster with hosted control planes using Azure CLI (az).
Prefer infrastructure as code
For production environments and repeatable deployments, we recommend infrastructure as code (IaC). Keeping infrastructure definitions in version control makes changes reviewable and helps keep environments consistent. Follow Deploying ARO HCP with Terraform for a Terraform deployment workflow covering cluster infrastructure, managed identities, networking, and Microsoft Entra integration.
The deployment steps follow the Microsoft Azure CLI quickstart .
Prerequisites
Azure CLI
Use Azure CLI 2.93.0 or later, which includes the az aro hcp commands used in this guide. Check the installed version and confirm that HCP commands are available:
macOS
See Install Azure CLI on macOS for alternative install options.
-
Install Azure CLI using Homebrew
Linux (RHEL 8, 9, or 10, using dnf)
For other distributions, follow Install the Azure CLI on Linux for your operating system and package manager.
-
Import the Microsoft signing key and add the repository for your RHEL major version
Run only the commands for your release. See Microsoft’s RPM installation instructions for supported distributions.
RHEL 8
RHEL 9
RHEL 10
-
Install Azure CLI
OpenShift CLI
Install the OpenShift CLI (oc) for your operating system from the
Red Hat downloads page
, extract the archive, and place oc in a directory on your PATH. The deployment test environment used client version 5.0.1.
Check your installed client version:
The client version line from the test environment was:
Prepare your Azure account
-
Log into the Azure CLI by running the following and then authorizing through your Web Browser. If you have more than one subscription, list them and select the one where you will deploy the cluster.
-
Confirm your permissions at each required scope
- Subscription preparation: Contributor, or Owner, at subscription scope permits resource provider registration and creation of a new resource group.
- Cluster deployment: Contributor and User Access Administrator, or Owner, on the target resource group permits resource creation and role assignments. Roles inherited from the subscription also apply.
If you only have resource group permissions, ask a subscription administrator to register the resource providers and create the resource group first. Then use that existing group and skip the registration and resource group creation commands in this guide. Resource group permissions do not grant subscription-level access. See Azure role assignment scopes .
-
Check compute quota in your chosen supported region . ARO HCP requires at least 20 cores. This guide uses
eastus2; change both the quota query andAZR_RESOURCE_LOCATIONif needed.Check quota for the worker VM family you plan to use. Request increases through Azure quota management .
-
Register resource providers, unless a subscription administrator has already registered them
Deploy ARO with hosted control planes
Define variables
Set the deployment location, resource group name, cluster name, and Key Vault name.
Change the values to suit your environment. Resource names must comply with Azure naming rules and length limits. Choose the Key Vault name independently of the cluster name so it fits the shorter Key Vault naming limits .
Run all following commands in the same shell so the exported variables apply.
Print the exported values to confirm your settings:
The Azure CLI requires explicit
cluster versions
and
node pool versions
. Use
az aro hcp get-versions
to list the available stable control plane versions in your selected region:
Choose a control plane minor version from the results. Replace <major.minor> with that version:
Look up the highest available stable node pool patch version in the same minor stream. The numeric sort ensures that patch versions with multiple digits are ordered correctly:
Print the selected versions:
Confirm that neither value is empty before continuing. If no node pool version is returned, check that the version query succeeded, then select an available control plane minor version and repeat the lookup.
Create the resource group
An Azure resource group is a logical container for related Azure resources. This guide creates the cluster resource, VNet, NSG, managed identities, and Key Vault in $AZR_RESOURCE_GROUP so you can manage and clean up these resources together. ARO HCP creates a separate managed resource group for its managed infrastructure.
Create the resource group before continuing with the networking and identity steps. If a subscription administrator has already created it, set AZR_RESOURCE_GROUP to that group’s name and skip this command.
Networking
Create a network security group, a virtual network, and subnets for the cluster.
-
Create a network security group
-
Create the virtual network and worker subnet with the network security group
-
Create the VNet integration subnet with the required delegation
-
Get the resource IDs for the networking resources
-
Print the exported networking resource IDs and confirm that none are empty
Managed identities
The cluster needs 13 user-assigned identities. See Microsoft’s identity reference for their responsibilities.
-
Create the operator and service identities
-
Export the identity resource IDs and principal IDs
-
Print the exported identity values and confirm that none are empty
Role assignments
-
Export the Azure role definition IDs
-
Print the exported role definition IDs
-
Assign roles to the control plane operator identities
-
Grant the service identity access to networking and control plane identities
-
Assign the data plane and federated credential roles
Key Vault and etcd encryption
Key Vault naming
These commands use AZR_KEYVAULT_NAME from
Define variables
. If the name is invalid or already taken, update that variable before retrying. All later vault references use the same variable; the cluster and resource group names can stay as they are.
-
Create a Key Vault using Azure RBAC
-
Grant your signed-in account permission to create keys
-
Check Key Vault access while the new role assignment propagates
Role assignments can take several minutes to become effective. Check access to the Key Vault data plane:
An empty result is expected for a new vault. If the command returns
ForbiddenorForbiddenByRbac, wait a few minutes and retry. A successful list confirms key-list access; the next command checks permission to create a key. See Key Vault RBAC guidance . -
Create the RSA encryption key
If key creation returns an RBAC authorization error, wait a few minutes and retry this command before continuing.
-
Export the key version
-
Print the exported key version and confirm that it is not empty
-
Grant the KMS identity permission to use the key
Allow several minutes for this role assignment to propagate before creating the cluster.
Create the hosted cluster
-
Create the cluster with the networking, identities, and encryption key
The
az aro hcp cluster createcommand takes approximately 10 to 15 minutes to complete. Wait for it to finish before continuing. -
Check cluster provisioning; wait for
Succeededbefore creating the node pool
Create the worker node pool
-
Create two
Standard_D8s_v6worker nodes -
Check node pool provisioning; successful deployment reports
Succeeded
Set up CLI access
Use the same shell and exported cluster variables from the deployment steps, with the OpenShift CLI installed. If your cluster has a private API server, run CLI commands from a host with network connectivity to the cluster’s virtual network.
-
Confirm the active subscription matches the one used for deployment
Show the active subscription and tenant. If the subscription is incorrect, select the deployment subscription using
az account set --subscription "<id-or-name>"before continuing. -
Request an administrative credential and save it to a kubeconfig file
Administrative credentials expire after 24 hours. Request a new credential when needed.
-
Set the kubeconfig file for CLI commands and print the configured path
-
Verify access by listing the worker nodes
Expected output (node names, ages, and versions will vary):
After node pool provisioning completes, the two worker nodes should report
Ready.
Configure OIDC authentication for console access
Unlike ARO Classic, ARO HCP does not include the built-in OpenShift OAuth server. There is no built-in kubeadmin user or support for an htpasswd identity provider. Console sign-in requires an external identity provider; the temporary administrative kubeconfig from the previous section provides initial CLI access. See the
ARO HCP authentication model
.
Integrating external OpenID Connect (OIDC) providers directly with ARO HCP supports machine-to-machine workflows, such as automated CLI access, and offers authentication capabilities unavailable through the built-in OAuth server. This guide configures Microsoft Entra ID for console and CLI sign-in, following Configure an external authentication provider .
Continue in the same shell, using AZR_CLUSTER, AZR_RESOURCE_GROUP, and the temporary administrative kubeconfig from
Set up CLI access
. You also need permission to register applications in your Microsoft Entra tenant. If users cannot register applications, ask your tenant administrator for the Application Developer or Application Administrator role.
Prepare authentication variables
Set the provider name and derive the application name and issuer URL from your existing cluster and Azure account:
Print the exported values:
Register the Microsoft Entra application
-
Get the console URL and construct its authentication callback URL
-
Print the exported URLs and confirm that neither is empty
-
Register an application with redirects for the console and CLI
The console uses its authentication callback URL. CLI sign-in uses
http://localhost:8000. -
Print the application ID and confirm that it is not empty
-
Create a client secret and retain it in the shell for the remaining steps
The Azure CLI displays a notice that the output contains credentials. The assignment stores the secret without printing it.
Create the external authentication provider
-
Configure the issuer, claim mappings, and console and CLI clients
The username mapping uses
preferred_usernamewithout a prefix. The group mapping uses thegroupsclaim when present. -
Verify the provider configuration
Configure the console secret and user permissions
Use the temporary administrative kubeconfig from the CLI access section for these commands. If that credential has expired, request it again before continuing.
-
Create the console client secret in OpenShift
-
Look up the user principal name for the user who will administer the cluster
Replace
<user-email>with that user’s Microsoft Entra email address. -
Print the user principal name and confirm that it identifies the intended user
-
Grant the user the
cluster-adminroleSigning in establishes identity; RBAC determines permissions. This binding grants the selected user full administrative access to the cluster.
Optionally, restrict the Entra application to selected users or groups . Application access and OpenShift RBAC permissions are configured separately.
Validate console access
Print the console URL obtained earlier:
Open that URL in your browser and sign in with the Microsoft Entra user granted access above.
Validate OIDC access with the OpenShift CLI
Use the
OpenShift CLI
installed in the prerequisites. This workflow requires its built-in oc-oidc credential plugin.
-
Get the cluster API URL
-
Print the API URL and confirm that it is not empty
-
Sign in through Microsoft Entra ID
Open the URL printed by the command and complete sign-in in your browser.
-
Verify the authenticated identity
Example output (the username and groups will vary):
-
Clear the client secret from the shell after validating access
Next steps
See Connect to an ARO HCP cluster for more connection details.
Optional: additional registry credentials
The Microsoft HCP quickstart does not require a customer-provided Red Hat pull secret for cluster creation.
After connecting, add credentials if your workloads or Operators need authenticated access to registry.redhat.io or another private registry. Follow
Add pull secrets to access private registries
, which uses a Secret named additional-pull-secret in the kube-system namespace.
Clean up
Use the same shell and exported variables from this guide. If you opened a new shell, set AZR_CLUSTER, AZR_RESOURCE_GROUP, AZR_KEYVAULT_NAME, and AZR_RESOURCE_LOCATION to the values used during deployment.
If you completed the OIDC setup, also retain or restore EXTERNAL_AUTH_NAME (entra in this guide) and CLIENT_ID (the application ID returned by az ad app create). The Microsoft Entra application registration exists outside the Azure resource group and must be deleted separately.
-
Delete the external authentication provider, if configured
Run this before deleting the cluster:
Confirm the deletion when prompted and wait for the command to finish. Console and OIDC CLI sign-in will stop working; the remaining cleanup commands use Azure CLI authentication. See
az aro hcp cluster external-auth delete. -
Delete the cluster
Confirm the deletion when prompted. This also removes the node pools and managed resource group, but leaves the resources in your customer resource group. See Delete an ARO HCP cluster .
The console client secret in
openshift-configand thearo-adminClusterRoleBinding are removed with the cluster. -
Verify that cluster deletion has completed before deleting its encryption key
Continue only when the command reports that the cluster resource was not found. If it still reports a provisioning state, wait and check again. Resolve authentication or permission errors before proceeding.
-
Delete the Microsoft Entra application registration, if created
Confirm that
CLIENT_IDidentifies the application created for this guide:Delete that application registration and its client credentials:
This requires permission to delete the application in Microsoft Entra ID. Deleting the cluster or resource group does not remove this registration. See
az ad app delete. -
Delete the customer-managed KMS key
Show the key ID and confirm that it contains the intended vault and key name:
Delete the confirmed key:
This deletes all versions of the key. The Key Vault Crypto Officer role assigned earlier permits this operation. Keep the key until cluster deletion is complete. See
az keyvault key delete. -
Delete the customer resource group and its remaining resources
Review the resources before deleting the group:
Delete the group only if you no longer need any of its resources. This removes the virtual network, subnets, NSG, managed identities, and Key Vault created in this guide.
Confirm the deletion when prompted and wait for the command to finish. Verify that the group is gone:
The expected result is
false. -
Optional: permanently remove the deleted Key Vault
Key Vault soft delete retains the deleted vault and keys for the configured retention period (90 days by default). The vault name remains reserved during that period.
If you need to reuse the vault name immediately, have permission to purge the vault, and no longer need to recover it or its keys, run:
Purging is irreversible and requires subscription-level permission, such as Key Vault Purge Operator. If purge protection is enabled, you must wait until the retention period expires. See
az keyvault purge.