Skip to content

Quick Start

Deploy the example public cluster (clusters/public/).

Prerequisites

Complete Account prerequisites first:

  • ARO HCP preview allow-list on your subscription
  • Contributor + User Access Administrator (or Owner) on the target resource group or subscription
  • Microsoft.RedHatOpenShift provider registered
  • Compute quota for default workers (8 vCPU of Standard_D4s_v6 in your region)

Install tools:

make setup    # az aro hcp extension

1. Configure cluster

cp -r clusters/public clusters/my-cluster
# Edit clusters/my-cluster/terraform.tfvars — location, cluster_name, versions
mkdir -p tmp
cp /path/to/pull-secret.txt tmp/pull-secret.txt   # required by example pull_secret_path

Check for conflicting environment overrides:

env | grep '^TF_VAR_' || true

Unset or align any TF_VAR_* with your tfvars before apply. See AGENTS.md.

2. Plan and apply

make cluster.my-cluster.init
make cluster.my-cluster.plan      # fails fast if cluster_version not enabled in location
make cluster.my-cluster.apply     # ~30–60 minutes

Optional — list enabled OpenShift versions:

make cluster.my-cluster.versions

3. Credentials and console

make cluster.my-cluster.kubeconfig       # admin creds, 24h TTL → .kube/config
make cluster.my-cluster.external-auth    # Entra + console; cluster-admin for you unless SKIP_RBAC_USER=1
make cluster.my-cluster.bootstrap        # OpenShift GitOps + Web Terminal + Compliance + ESO

External-auth requires Entra rights separate from Azure Owner — see External auth with Entra ID. Extra OpenShift admins: a group ClusterRoleBinding in a cluster-config repo. Create also binds you as cluster-admin (break-glass); skip with SKIP_RBAC_USER=1 make cluster.my-cluster.external-auth.

4. Verify

az aro hcp cluster show -g <resource_group> -n <cluster_name> --query provisioningState
oc get co console
oc get clusterversion

Console URL (from cluster show) should return HTTP 200 after external-auth.

Optional GitOps (after kubeconfig; sshuttle first if the API is private): GitOps bootstrap.

Private cluster profile

Use clusters/private/:

cp -r clusters/private clusters/my-private
make cluster.my-private.jump-key
# Set jump_ssh_source_prefix to your public /32 in terraform.tfvars (or export TF_VAR_jump_ssh_source_prefix)
make cluster.my-private.apply
make cluster.my-private.sshuttle.connect   # background tunnel — before oc / browser
# Or: make cluster.my-private.jump          # print foreground sshuttle command
make cluster.my-private.kubeconfig
make cluster.my-private.private-dns   # customer Private DNS for api.*.aroapp-hcp.io (+ apps when router IP is known)
# Merge clusters/my-private/operator-hosts.snippet into /etc/hosts if public DNS still resolves console/apps
make cluster.my-private.external-auth
# If console secret apply times out: make cluster.my-private.console-secret (with sshuttle running)

Teardown for private also removes the customer Private DNS zone (private-dns-delete runs automatically from destroy).

OpenShift Virtualization (validated full stack)

Two GitHub checkouts, one cluster: this installer (clusters/aro-virt) plus sibling validated-pattern-openshift-virt (ANF, Trident, CNV, Azure Route Server, CUDN BGP). The sibling is a second IaC run after make cluster.aro-virt.platform. Extra quota: +18 vCPU Dsv6 (+16 for np-virt, +2 for the jump box) and ANF capacity. Jump needs make cluster.aro-virt.jump-key and jump_ssh_source_prefix in tfvars before apply.

Option A — AI-assisted (Cursor, Claude Code, …)

git clone https://github.com/rh-mobb/validated-pattern-aro-hcp.git
cd validated-pattern-aro-hcp
git clone https://github.com/rh-mobb/validated-pattern-openshift-virt.git references/validated-pattern-openshift-virt
mkdir -p tmp && cp /path/to/pull-secret.txt tmp/pull-secret.txt
# Edit clusters/aro-virt/terraform.tfvars — location, jump_ssh_source_prefix (/32)

Open the repo in your editor and ask the local agent to deploy the aro-virt E2E validated virt stack end to end. It should follow AGENTS.md and clusters/aro-virt/AGENTS.md: preflight (TF_VAR_*, subscription, plan), tmux for long apply/destroy, installer apply → kubeconfig → external-auth → bootstrap → platform → sibling apply/bootstrap → extra-hop verify from the jump.

You still need account prerequisites (allow-list, RBAC, quota) and Entra rights for external-auth. The agent should stop and ask before mutating Azure or when an ARM operation is stuck.

Option B — Operator guide

Step-by-step make commands, verify, and troubleshooting: Virt stack.

Teardown

make cluster.my-cluster.external-auth-delete
make cluster.my-cluster.destroy

If a sibling ANF/Trident stack is attached, destroy it first.

For private clusters, run make cluster.<name>.sshuttle.connect before external-auth-delete if oc cannot reach the API. Run make cluster.<name>.sshuttle.disconnect when finished.