Cloud Experts Documentation

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 quickstartexternal link (opens in new tab) .

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 macOSexternal link (opens in new tab) for alternative install options.

  1. Install Azure CLI using Homebrew

Linux (RHEL 8, 9, or 10, using dnf)

For other distributions, follow Install the Azure CLI on Linuxexternal link (opens in new tab) for your operating system and package manager.

  1. 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 instructionsexternal link (opens in new tab) for supported distributions.

    RHEL 8
    RHEL 9
    RHEL 10
  2. 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

  1. 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.

  2. 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 scopesexternal link (opens in new tab) .

  3. Check compute quota in your chosen supported regionexternal link (opens in new tab) . ARO HCP requires at least 20 cores. This guide uses eastus2; change both the quota query and AZR_RESOURCE_LOCATION if needed.

    Check quota for the worker VM family you plan to use. Request increases through Azure quota managementexternal link (opens in new tab) .

  4. 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 rulesexternal link (opens in new tab) and length limits. Choose the Key Vault name independently of the cluster name so it fits the shorter Key Vault naming limitsexternal link (opens in new tab) .

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 versionsexternal link (opens in new tab) and node pool versionsexternal link (opens in new tab) . Use az aro hcp get-versionsexternal link (opens in new tab) 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.

  1. Create a network security group

  2. Create the virtual network and worker subnet with the network security group

  3. Create the VNet integration subnet with the required delegation

  4. Get the resource IDs for the networking resources

  5. 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 referenceexternal link (opens in new tab) for their responsibilities.

The commands in each block run one after another. Allow a moment for each block to finish before continuing to the next step.
  1. Create the operator and service identities

  2. Export the identity resource IDs and principal IDs

  3. Print the exported identity values and confirm that none are empty

Role assignments

  1. Export the Azure role definition IDs

  2. Print the exported role definition IDs

  3. Assign roles to the control plane operator identities

  4. Grant the service identity access to networking and control plane identities

  5. 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.

  1. Create a Key Vault using Azure RBAC

  2. Grant your signed-in account permission to create keys

  3. 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 Forbidden or ForbiddenByRbac, 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 guidanceexternal link (opens in new tab) .

  4. Create the RSA encryption key

    If key creation returns an RBAC authorization error, wait a few minutes and retry this command before continuing.

  5. Export the key version

  6. Print the exported key version and confirm that it is not empty

  7. 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

  1. Create the cluster with the networking, identities, and encryption key

    The az aro hcp cluster create command takes approximately 10 to 15 minutes to complete. Wait for it to finish before continuing.

  2. Check cluster provisioning; wait for Succeeded before creating the node pool

Create the worker node pool

  1. Create two Standard_D8s_v6 worker nodes

  2. 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.

  1. 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.

  2. Request an administrative credential and save it to a kubeconfig file

    Administrative credentials expire after 24 hours. Request a new credential when needed.

  3. Set the kubeconfig file for CLI commands and print the configured path

  4. 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 providerexternal link (opens in new tab) .

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

  1. Get the console URL and construct its authentication callback URL

  2. Print the exported URLs and confirm that neither is empty

  3. Register an application with redirects for the console and CLI

    The console uses its authentication callback URL. CLI sign-in uses http://localhost:8000.

  4. Print the application ID and confirm that it is not empty

  5. 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

  1. Configure the issuer, claim mappings, and console and CLI clients

    The username mapping uses preferred_username without a prefix. The group mapping uses the groups claim when present.

  2. 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.

  1. Create the console client secret in OpenShift

  2. 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.

  3. Print the user principal name and confirm that it identifies the intended user

  4. Grant the user the cluster-admin role

    Signing 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 groupsexternal link (opens in new tab) . 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.

  1. Get the cluster API URL

  2. Print the API URL and confirm that it is not empty

  3. Sign in through Microsoft Entra ID

    Open the URL printed by the command and complete sign-in in your browser.

  4. Verify the authenticated identity

    Example output (the username and groups will vary):

  5. Clear the client secret from the shell after validating access

Next steps

See Connect to an ARO HCP clusterexternal link (opens in new tab) for more connection details.

Optional: additional registry credentials

The Microsoft HCP quickstartexternal link (opens in new tab) 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 registriesexternal link (opens in new tab) , 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.

  1. 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 deleteexternal link (opens in new tab) .

  2. 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 clusterexternal link (opens in new tab) .

    The console client secret in openshift-config and the aro-admin ClusterRoleBinding are removed with the cluster.

  3. 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.

  4. Delete the Microsoft Entra application registration, if created

    Confirm that CLIENT_ID identifies 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 deleteexternal link (opens in new tab) .

  5. 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 deleteexternal link (opens in new tab) .

  6. 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.

  7. Optional: permanently remove the deleted Key Vault

    Key Vault soft deleteexternal link (opens in new tab) 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 purgeexternal link (opens in new tab) .

Back to top

Interested in contributing to these docs?

Collaboration drives progress. Help improve our documentation The Red Hat Way.

Red Hat logo LinkedIn YouTube Facebook Twitter

Products

Tools

Try, buy & sell

Communicate

About Red Hat

We’re the world’s leading provider of enterprise open source solutions—including Linux, cloud, container, and Kubernetes. We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Subscribe to our newsletter, Red Hat Shares

Sign up now
© 2026 Red Hat