Connect to an Azure Red Hat OpenShift with hosted control planes cluster (preview)

In this quickstart, you connect to an Azure Red Hat OpenShift with hosted control planes (HCP) cluster by requesting a temporary administrative credential. The credential generates a kubeconfig file that you use with the OpenShift CLI (oc) to access the cluster.

Prerequisites

Important

If your cluster has a private API server, you must run all commands in this article from a host that has private network connectivity to the cluster's virtual network. You can establish connectivity through Azure VNet peering, Azure VPN Gateway, or Azure ExpressRoute. To quickly test connectivity, see Connect from a jump box VM.

Create a jump box VM (private clusters only)

If your cluster has a private API server and you don't have an existing private network connection, you can create a jump box virtual machine in a dedicated subnet with its own NSG. Use a jump box VM for initial cluster setup, testing, or one-time administrative tasks. For ongoing production access from on-premises networks or CI/CD pipelines, use Azure VPN Gateway or Azure ExpressRoute instead.

Prepare your environment

  1. Set the environment variables. Replace the placeholder values with your own values.

    LOCATION="<location>"
CUSTOMER_RG_NAME="<resource-group-name>"
JUMPBOX_SUBNET_NAME="<subnet-name>"
JUMPBOX_NSG_NAME="<nsg-name>"
JUMPBOX_NAME="<jumpbox-vm-name>"

  2. Create a dedicated NSG for the jump box VM.

    az network nsg create \
 --name "${JUMPBOX_NSG_NAME}" \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --location "${LOCATION}"

  3. Add an inbound SSH rule restricted to your desired IP or CIDR range.

    az network nsg rule create \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --nsg-name "${JUMPBOX_NSG_NAME}" \
 --name "AllowSSH" \
 --priority 1000 \
 --protocol Tcp \
 --destination-port-ranges 22 \
 --source-address-prefixes "<source-ip-address>" \
 --access Allow \
 --direction Inbound

    Replace <source-ip-address> with your desired source.

  4. Create a dedicated jump box VM subnet.

    az network vnet subnet create \
 --name "${JUMPBOX_SUBNET_NAME}" \
 --vnet-name "${CUSTOMER_VNET_NAME}" \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --address-prefixes 10.0.2.0/28 \
 --network-security-group "${JUMPBOX_NSG_NAME}"

Create the jump box VM

  1. Create the jump box VM.

    az vm create \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --name "${JUMPBOX_NAME}" \
 --image Ubuntu2204 \
 --admin-username azureuser \
 --vnet-name "${CUSTOMER_VNET_NAME}" \
 --subnet "${JUMPBOX_SUBNET_NAME}" \
 --size Standard_B2s \
 --generate-ssh-keys

  2. Get the jump box VM public IP address.

    JUMPBOX_IP=$(az vm show \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --name "${JUMPBOX_NAME}" \
 --show-details \
 --query publicIps \
 --output tsv)

echo "Jump box VM IP: ${JUMPBOX_IP}"

  3. Connect to the jump box VM over SSH.

    ssh azureuser@"${JUMPBOX_IP}"

Set up the jump box VM environment

Because the private cluster's API server has no public endpoint, you must run oc commands from within the virtual network.

  1. Download and install the Azure CLI in the jump box VM.

    This example downloads and installs the Azure CLI for Ubuntu. If you created the jump box with a different operating system, follow the Azure CLI Azure CLI installation instructions for your OS.

    curl -fsSL 'https://azurecliprod.blob.core.windows.net/$root/deb_install.sh' | sudo bash

  2. Verify that the Azure CLI is installed.

    az version

  3. Sign in to Azure.

    az login

    This command returns a device code and URL.

  4. Open the URL in a browser on your local machine, enter the code, and authenticate.

  5. Download the ARO HCP CLI extension.

    curl -sL https://aka.ms/aro-hcp-cli -o aro_hcp-1.0.0b3-py3-none-any.whl

  6. Add the ARO HCP CLI extension.

    az extension add --source aro_hcp-1.0.0b3-py3-none-any.whl

  7. Verify that the ARO HCP CLI extension is installed.

    az aro hcp -h

  8. Install the OpenShift CLI.

    curl -sL https://mirror.openshift.com/pub/openshift-v4/clients/ocp/stable/openshift-client-linux.tar.gz \
  | sudo tar -C /usr/local/bin -xz oc kubectl

  9. Verify that the OpenShift CLI is installed.

    oc version --client

Connect to the cluster

Administrative credentials expire after 24 hours.

  1. Set the following environment variables if you didn't already set them. Replace the placeholder values with the values for your cluster.

    CUSTOMER_RG_NAME="<resource-group-name>"
CLUSTER_NAME="<cluster-name>"

  2. Request a temporary administrative credential for the cluster and save the kubeconfig to a file.

    az aro hcp cluster request-credential --admin \
 --name "${CLUSTER_NAME}" \
 --resource-group "${CUSTOMER_RG_NAME}" \
 --file kubeconfig

  3. Set the KUBECONFIG environment variable to the path of the kubeconfig file you saved.

    export KUBECONFIG=kubeconfig

  4. Verify that you can connect to the cluster.

    oc auth whoami

    The following example output shows a successful connection.

    ATTRIBUTE    VALUE
Username     system:customer-break-glass:<user-id>
Groups       [system:masters system:authenticated]
Extra: authentication.kubernetes.io/credential-id   <credential-id>

Clean up

Revoke administrative credentials

If you want to revoke all administrative credentials for the cluster, run the following command.

az aro hcp cluster revoke-credential \
  --name "${CLUSTER_NAME}" \
  --resource-group "${CUSTOMER_RG_NAME}"

Delete the jump box VM

If you created a jump box VM to connect to a private cluster, delete the VM to avoid ongoing charges.

az vm delete \
  --resource-group "${CUSTOMER_RG_NAME}" \
  --name "${JUMPBOX_NAME}" \
  --yes

Next steps

Configure an external authentication provider

  • Last updated on