Skip to main content
Version: v2.5

Creating an AKS Cluster

You can use Rancher to create a cluster hosted in Microsoft Azure Kubernetes Service (AKS).

Prerequisites in Microsoft Azure​

Note Deploying to AKS will incur charges.

To interact with Azure APIs, an AKS cluster requires an Azure Active Directory (AD) service principal. The service principal is needed to dynamically create and manage other Azure resources, and it provides credentials for your cluster to communicate with AKS. For more information about the service principal, refer to the AKS documentation.

Before creating the service principal, you need to obtain the following information from the Microsoft Azure Portal:

  • Your subscription ID
  • Your tenant ID
  • Client ID (also known as app ID)
  • Client secret
  • A resource group

The below sections describe how to set up these prerequisites using either the Azure command line tool or the Azure portal.

Setting Up the Service Principal with the Azure Command Line Tool​

You must assign roles to the service principal so that it has communication privileges with the AKS API. It also needs access to create and list virtual networks.

In the following example, the command creates the service principal and gives it the Contributor role. The Contributor role can manage anything on AKS but cannot give access to others. Note that you must provide scopes a full path to at least one Azure resource: 

az ad sp create-for-rbac --role Contributor --scopes /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>

The result should show information about the new service principal:

{
  "appId": "xxxx--xxx",
  "displayName": "<service-principal-name>",
  "name": "http://<service-principal-name>",
  "password": "<secret>",
  "tenant": "<tenant-name>"
}

The following creates a Resource Group to contain your Azure resources:

az group create --location <azure-location-name> --resource-group <resource-group-name>

Setting Up the Service Principal from the Azure Portal​

Follow these instructions to set up a service principal and give it role-based access from the Azure Portal.

  1. Go to the Microsoft Azure Portal home page.

  2. Click Azure Active Directory.

  3. Click App registrations.

  4. Click New registration.

  5. Enter a name for your service principal.

  6. Optional: Choose which accounts can use the service principal.

  7. Click Register.

  8. You should now see the name of your service principal under Azure Active Directory > App registrations.

  9. Click the name of your service principal. Take note of the tenant ID and application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click Certificates & secrets.

  10. Click New client secret.

  11. Enter a short description, pick an expiration time, and click Add. Take note of the client secret so that you can use it when provisioning the AKS cluster.

Result: You have created a service principal and you should be able to see it listed in the Azure Active Directory section under App registrations. You still need to give the service principal access to AKS.

To give role-based access to your service principal,

  1. Click All Services in the left navigation bar. Then click Subscriptions.

  2. Click the name of the subscription that you want to associate with your Kubernetes cluster. Take note of the subscription ID so that you can use it when provisioning your AKS cluster.

  3. Click Access Control (IAM).

  4. In the Add role assignment section, click Add.

  5. In the Role field, select a role that will have access to AKS. For example, you can use the Contributor role, which has permission to manage everything except for giving access to other users.

  6. In the Assign access to field, select Azure AD user, group, or service principal.

  7. In the Select field, select the name of your service principal and click Save.

Result: Your service principal now has access to AKS.

Create the AKS Cluster​

Use Rancher to set up and configure your Kubernetes cluster.

  1. From the Clusters page, click Add Cluster.

  2. Choose Azure AKS.

  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 your subscription ID, tenant ID, client ID, and client secret to give your cluster access to AKS. If you don't have all of that information, you can retrieve it using these instructions:

  • Tenant ID: To get the Tenant ID, you can go to the Azure Portal, then click Azure Active Directory, then click Properties and find the Tenant ID field.
  • Client ID: To get the Client ID, you can go to the Azure Portal, then click Azure Active Directory, then click Enterprise applications. Click All applications. Select your application, click Properties, and copy the application ID.
  • Client secret: If you didn't copy the client secret when creating the service principal, you can get a new one if you go to the app registration detail page, then click Certificates & secrets, then click New client secret.
  • Subscription ID: You can get the subscription ID is available in the portal from All services > Subscriptions.

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

  2. Complete the Account Access form using the output from your Service Principal. This information is used to authenticate with Azure.

  3. Use Nodes to provision each node in your cluster and choose a geographical region.

    [Microsoft Documentation: How to create and use an SSH public and private key pair](https://docs.microsoft.com/en-us/azure/virtual-machines/linux/mac-create-ssh-keys)

  4. Click Create.


  5. Review your options to confirm they're correct. Then click Create.

Result:

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 default namespace
  • System, containing the cattle-system, ingress-nginx, kube-public, and kube-system namespaces