In OpenShift Container Platform version 4.11, you can install a cluster on Microsoft Azure Stack Hub by using infrastructure that you provide.

Several Azure Resource Manager (ARM) templates are provided to assist in completing these steps or to help model your own.

The steps for performing a user-provisioned infrastructure installation are provided as an example only. Installing a cluster with infrastructure you provide requires knowledge of the cloud provider and the installation process of OpenShift Container Platform. Several ARM templates are provided to assist in completing these steps or to help model your own. You are also free to create the required resources through other methods; the templates are just an example.


Internet access for OpenShift Container Platform

In OpenShift Container Platform 4.11, you require access to the internet to install your cluster.

You must have internet access to:

  • Access OpenShift Cluster Manager Hybrid Cloud Console to download the installation program and perform subscription management. If the cluster has internet access and you do not disable Telemetry, that service automatically entitles your cluster.

  • Access Quay.io to obtain the packages that are required to install your cluster.

  • Obtain the packages that are required to perform cluster updates.

If your cluster cannot have direct internet access, you can perform a restricted network installation on some types of infrastructure that you provision. During that process, you download the required content and use it to populate a mirror registry with the installation packages. With some installation types, the environment that you install your cluster in will not require internet access. Before you update the cluster, you update the content of the mirror registry.

Configuring your Azure Stack Hub project

Before you can install OpenShift Container Platform, you must configure an Azure project to host it.

All Azure Stack Hub resources that are available through public endpoints are subject to resource name restrictions, and you cannot create resources that use certain terms. For a list of terms that Azure Stack Hub restricts, see Resolve reserved resource name errors in the Azure documentation.

Azure Stack Hub account limits

The OpenShift Container Platform cluster uses a number of Microsoft Azure Stack Hub components, and the default Quota types in Azure Stack Hub affect your ability to install OpenShift Container Platform clusters.

The following table summarizes the Azure Stack Hub components whose limits can impact your ability to install and run OpenShift Container Platform clusters.

Component Number of components required by default Description



A default cluster requires 56 vCPUs, so you must increase the account limit.

By default, each cluster creates the following instances:

  • One bootstrap machine, which is removed after installation

  • Three control plane machines

  • Three compute machines

Because the bootstrap, control plane, and worker machines use Standard_DS4_v2 virtual machines, which use 8 vCPUs, a default cluster requires 56 vCPUs. The bootstrap node VM is used only during installation.

To deploy more worker nodes, enable autoscaling, deploy large workloads, or use a different instance type, you must further increase the vCPU limit for your account to ensure that your cluster can deploy the machines that you require.



Each default cluster requires one Virtual Network (VNet), which contains two subnets.

Network interfaces


Each default cluster requires seven network interfaces. If you create more machines or your deployed workloads create load balancers, your cluster uses more network interfaces.

Network security groups


Each cluster creates network security groups for each subnet in the VNet. The default cluster creates network security groups for the control plane and for the compute node subnets:


Allows the control plane machines to be reached on port 6443 from anywhere


Allows worker nodes to be reached from the internet on ports 80 and 443

Network load balancers


Each cluster creates the following load balancers:


Public IP address that load balances requests to ports 80 and 443 across worker machines


Private IP address that load balances requests to ports 6443 and 22623 across control plane machines


Public IP address that load balances requests to port 6443 across control plane machines

If your applications create more Kubernetes LoadBalancer service objects, your cluster uses more load balancers.

Public IP addresses


The public load balancer uses a public IP address. The bootstrap machine also uses a public IP address so that you can SSH into the machine to troubleshoot issues during installation. The IP address for the bootstrap node is used only during installation.

Private IP addresses


The internal load balancer, each of the three control plane machines, and each of the three worker machines each use a private IP address.

Configuring a DNS zone in Azure Stack Hub

To successfully install OpenShift Container Platform on Azure Stack Hub, you must create DNS records in an Azure Stack Hub DNS zone. The DNS zone must be authoritative for the domain. To delegate a registrar’s DNS zone to Azure Stack Hub, see Microsoft’s documentation for Azure Stack Hub datacenter DNS integration.

You can view Azure’s DNS solution by visiting this example for creating DNS zones.

Certificate signing requests management

Because your cluster has limited access to automatic machine management when you use infrastructure that you provision, you must provide a mechanism for approving cluster certificate signing requests (CSRs) after installation. The kube-controller-manager only approves the kubelet client CSRs. The machine-approver cannot guarantee the validity of a serving certificate that is requested by using kubelet credentials because it cannot confirm that the correct machine issued the request. You must determine and implement a method of verifying the validity of the kubelet serving certificate requests and approving them.

Required Azure Stack Hub roles

Your Microsoft Azure Stack Hub account must have the following roles for the subscription that you use:

  • Owner

To set roles on the Azure portal, see the Manage access to resources in Azure Stack Hub with role-based access control in the Microsoft documentation.

Creating a service principal

Because OpenShift Container Platform and its installation program create Microsoft Azure resources by using the Azure Resource Manager, you must create a service principal to represent it.

  • Install or update the Azure CLI.

  • Your Azure account has the required roles for the subscription that you use.

  1. Register your environment:

    $ az cloud register -n AzureStackCloud --endpoint-resource-manager <endpoint> (1)
    1 Specify the Azure Resource Manager endpoint, `https://management.<region>.<fqdn>/`.

    See the Microsoft documentation for details.

  2. Set the active environment:

    $ az cloud set -n AzureStackCloud
  3. Update your environment configuration to use the specific API version for Azure Stack Hub:

    $ az cloud update --profile 2019-03-01-hybrid
  4. Log in to the Azure CLI:

    $ az login

    If you are in a multitenant environment, you must also supply the tenant ID.

  5. If your Azure account uses subscriptions, ensure that you are using the right subscription:

    1. View the list of available accounts and record the tenantId value for the subscription you want to use for your cluster:

      $ az account list --refresh
      Example output
          "cloudName": AzureStackCloud",
          "id": "9bab1460-96d5-40b3-a78e-17b15e978a80",
          "isDefault": true,
          "name": "Subscription Name",
          "state": "Enabled",
          "tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee",
          "user": {
            "name": "you@example.com",
            "type": "user"
    2. View your active account details and confirm that the tenantId value matches the subscription you want to use:

      $ az account show
      Example output
        "environmentName": AzureStackCloud",
        "id": "9bab1460-96d5-40b3-a78e-17b15e978a80",
        "isDefault": true,
        "name": "Subscription Name",
        "state": "Enabled",
        "tenantId": "6057c7e9-b3ae-489d-a54e-de3f6bf6a8ee", (1)
        "user": {
          "name": "you@example.com",
          "type": "user"
      1 Ensure that the value of the tenantId parameter is the correct subscription ID.
    3. If you are not using the right subscription, change the active subscription:

      $ az account set -s <subscription_id> (1)
      1 Specify the subscription ID.
    4. Verify the subscription ID update: