In this section, you’ll learn how to set up a Kubernetes cluster in Azure through Rancher. During this process, Rancher will provision new nodes in Azure.

Creating an Azure Cluster

Prerequisite: Before Rancher can create a cluster in Azure, a node template needs to be created using your Azure credentials and configuration. For details, see this section.

Use Rancher to create a Kubernetes cluster in Azure.

  1. From the Clusters page, click Add Cluster.

  2. Choose Azure.

  3. Enter a Cluster Name.

  4. Use Member Roles to configure user authorization for the cluster.

    • Click Add Member to add users that can access the cluster.
    • Use the Role drop-down to set permissions for each user.

  5. Use Cluster Options to choose the version of Kubernetes, what network provider will be used and if you want to enable project network isolation. To see more cluster options, click on Show advanced options. For more information, see the cluster configuration reference.

  6. Add one or more node pools to your cluster.

    A node pool is a collection of nodes based on a node template. A node template defines the configuration of a node, like what operating system to use, number of CPUs and amount of memory. Each node pool must have one or more nodes roles assigned.


    • Each node role (i.e. etcd, Control Plane, and Worker) should be assigned to a distinct node pool. Although it is possible to assign multiple node roles to a node pool, this should not be done for production clusters.
    • The recommended setup is to have a node pool with the etcd node role and a count of three, a node pool with the Control Plane node role and a count of at least two, and a node pool with the Worker node role and a count of at least two. Regarding the etcd node role, refer to the etcd Admin Guide.
  7. Optional: Add additional node pools.

  8. Review your options to confirm they’re correct. Then click Create.


  • Your cluster is created and assigned a state of Provisioning. Rancher is standing up your cluster.
  • You can access your cluster after its state is updated to Active.
  • Active clusters are assigned two Projects, Default (containing the namespace default) and System (containing the namespaces cattle-system,ingress-nginx,kube-public and kube-system, if present).

Optional Next Steps

After creating your cluster, you can access it through the Rancher UI. As a best practice, we recommend setting up these alternate ways of accessing your cluster:

  • Access your cluster with the kubectl CLI: Follow these steps to access clusters with kubectl on your workstation. In this case, you will be authenticated through the Rancher server’s authentication proxy, then Rancher will connect you to the downstream cluster. This method lets you manage the cluster without the Rancher UI.
  • Access your cluster with the kubectl CLI, using the authorized cluster endpoint: Follow these steps to access your cluster with kubectl directly, without authenticating through Rancher. We recommend setting up this alternative method to access your cluster so that in case you can’t connect to Rancher, you can still access the cluster.

Creating an Azure Node Template

Creating a node template for Azure will allow Rancher to provision new nodes when it sets up a Kubernetes cluster in Azure.

Preparation in Azure

Before creating a node template in Rancher using a cloud infrastructure such as Azure, we must configure Rancher to allow the manipulation of resources in an Azure subscription.

To do this, we will first create a new Azure service principal (SP) in Azure Active Directory (AD), which, in Azure, is an application user who has permission to manage Azure resources.

The following is a template az cli script that you have to run for creating an service principal, where you have to enter your SP name, role, and scope:

az ad sp create-for-rbac --name="<Rancher ServicePrincipal name>" --role="Contributor" --scopes="/subscriptions/<subscription Id>"

The creation of this service principal returns three pieces of identification information, The application ID, also called the client ID, The client secret, and The tenant ID. This information will be used in the following section adding the node template.

Creating the Template

  1. Click Add Node Template.

  2. Complete the Azure Options form. For help filling out the form, refer to Configuration below.

  3. Click Create.

Result: The node template can be used during the cluster creation process.

Template Configuration

  • Account Access stores your account information for authenticating with Azure. Note: As of v2.2.0, account access information is stored as a cloud credentials. Cloud credentials are stored as Kubernetes secrets. Multiple node templates can use the same cloud credential. You can use an existing cloud credential or create a new one. To create a new cloud credential, enter Name and Account Access data, then click Create.

  • Placement sets the geographical region where your cluster is hosted and other location metadata.

  • Network configures the networking used in your cluster.

  • Instance customizes your VM configuration.

The Docker daemon configuration options include:

  • Labels: For information on labels, refer to the Docker object label documentation.

  • Docker Engine Install URL: Determines what Docker version will be installed on the instance. Note: If you are using RancherOS, please check what Docker versions are available using sudo ros engine list on the RancherOS version you want to use, as the default Docker version configured might not be available. If you experience issues installing Docker on other operating systems, please try to install Docker manually using the configured Docker Engine Install URL to troubleshoot.

  • Registry mirrors: Docker Registry mirror to be used by the Docker daemon

  • Other advanced options: Refer to the Docker daemon option reference