Creating an AKS Cluster

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

Prerequisites in Microsoft Azure

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:

Subscription ID
Client ID (also known as app ID)
Client secret

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.

Go to the Microsoft Azure Portal home page.
Click Azure Active Directory.
Click App registrations.
Click New registration.
Enter a name for your service principal.
Optional: Choose which accounts can use the service principal.
Click Register.
You should now see the name of your service principal under Azure Active Directory App registrations.
Click the name of your service principal. Take note of the application ID (also called app ID or client ID) so that you can use it when provisioning your AKS cluster. Then click Certificates & secrets.
Click New client secret.
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,

Click All Services in the left navigation bar. Then click Subscriptions.
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.
Click Access Control (IAM).
In the Add role assignment section, click Add.
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.
In the Assign access to field, select Azure AD user, group, or service principal.
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 Cloud Credentials

In the Rancher UI, click ☰ > Cluster Management.
Click Cloud Credentials.
Click Create.
Click Azure.
Fill out the form. For help with filling out the form, see the configuration reference.
Click Create.

Create the AKS Cluster

Use Rancher to set up and configure your Kubernetes cluster.

Click ☰ > Cluster Management.
In the Clusters section, click Create.
Click Azure AKS.
Fill out the form. For help with filling out the form, see the configuration reference.
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.

Configure Role-based Access Control

When provisioning an AKS cluster in the Rancher UI, RBAC is not configurable because it is required to be enabled.

RBAC is required for AKS clusters that are registered or imported into Rancher.

Setting Up the Role Assignment to Service Principal with the Azure Command Line Tool

Assign the Rancher AKSv2 role to the service principal with the Azure Command Line Tool:

az role assignment create \
--assignee <client-id> \
--scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>" \
--role "Rancher AKSv2"

AKS Cluster Configuration Reference

For more information about how to configure AKS clusters from the Rancher UI, see the configuration reference.

Private Clusters

Typically, AKS worker nodes do not get public IPs, regardless of whether the cluster is private. In a private cluster, the control plane does not have a public endpoint.

Rancher can connect to a private AKS cluster in one of two ways.

The first way to ensure that Rancher is running on the same NAT as the AKS nodes.

The second way is to run a command to register the cluster with Rancher. Once the cluster is provisioned, you can run the displayed command anywhere you can connect to the cluster’s Kubernetes API. This command is displayed in a pop-up when you provision an AKS cluster with a private API endpoint enabled.

Please be aware that when registering an existing AKS cluster, the cluster might take some time, possibly hours, to appear in the Cluster To register dropdown list. This outcome will be based on region.

For more information about connecting to an AKS private cluster, see the AKS documentation.

Setting Up the Minimum Permission Role with the Azure Command Line Tool

Create the Minimum Rancher AKSv2 Permission Role by running this command:

  cat >> rancher-azure.json << EOF

  {
      "Name": "Rancher AKSv2",
      "IsCustom": true,
      "Description": "Everything needed by Rancher AKSv2 operator",
      "Actions": [
          "Microsoft.Compute/disks/delete",
          "Microsoft.Compute/disks/read",
          "Microsoft.Compute/disks/write",
          "Microsoft.Compute/diskEncryptionSets/read",
          "Microsoft.Compute/locations/DiskOperations/read",
          "Microsoft.Compute/locations/vmSizes/read",
          "Microsoft.Compute/locations/operations/read",
          "Microsoft.Compute/proximityPlacementGroups/write",
          "Microsoft.Compute/snapshots/delete",
          "Microsoft.Compute/snapshots/read",
          "Microsoft.Compute/snapshots/write",
          "Microsoft.Compute/virtualMachineScaleSets/manualUpgrade/action",
          "Microsoft.Compute/virtualMachineScaleSets/delete",
          "Microsoft.Compute/virtualMachineScaleSets/read",
          "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/networkInterfaces/read",
          "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/networkInterfaces/ipconfigurations/publicipaddresses/read",
          "Microsoft.Compute/virtualMachineScaleSets/virtualmachines/instanceView/read",
          "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/read",
          "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/write",
          "Microsoft.Compute/virtualMachineScaleSets/write",
          "Microsoft.Compute/virtualMachines/read",
          "Microsoft.Compute/virtualMachines/write",
          "Microsoft.ContainerService/managedClusters/read",
          "Microsoft.ContainerService/managedClusters/write",
          "Microsoft.ContainerService/managedClusters/delete",
          "Microsoft.ContainerService/managedClusters/accessProfiles/listCredential/action",
          "Microsoft.ContainerService/managedClusters/agentPools/read",
          "Microsoft.ContainerService/managedClusters/agentPools/write",
          "Microsoft.ContainerService/managedClusters/agentPools/delete",
          "Microsoft.ManagedIdentity/userAssignedIdentities/assign/action",
          "Microsoft.Network/applicationGateways/read",
          "Microsoft.Network/applicationGateways/write",
          "Microsoft.Network/loadBalancers/write",
          "Microsoft.Network/loadBalancers/backendAddressPools/join/action",
          "Microsoft.Network/loadBalancers/delete",
          "Microsoft.Network/loadBalancers/read",
          "Microsoft.Network/networkInterfaces/join/action",
          "Microsoft.Network/networkInterfaces/read",
          "Microsoft.Network/networkInterfaces/write",
          "Microsoft.Network/networkSecurityGroups/read",
          "Microsoft.Network/networkSecurityGroups/write",
          "Microsoft.Network/publicIPAddresses/delete",
          "Microsoft.Network/publicIPAddresses/join/action",
          "Microsoft.Network/publicIPAddresses/read",
          "Microsoft.Network/publicIPAddresses/write",
          "Microsoft.Network/publicIPPrefixes/join/action",
          "Microsoft.Network/privatednszones/*",
          "Microsoft.Network/routeTables/read",
          "Microsoft.Network/routeTables/routes/delete",
          "Microsoft.Network/routeTables/routes/read",
          "Microsoft.Network/routeTables/routes/write",
          "Microsoft.Network/routeTables/write",
          "Microsoft.Network/virtualNetworks/read",
          "Microsoft.Network/virtualNetworks/subnets/join/action",
          "Microsoft.Network/virtualNetworks/subnets/read",
          "Microsoft.Network/virtualNetworks/joinLoadBalancer/action",
          "Microsoft.OperationalInsights/workspaces/sharedkeys/read",
          "Microsoft.OperationalInsights/workspaces/read",
          "Microsoft.OperationsManagement/solutions/write",
          "Microsoft.OperationsManagement/solutions/read",
          "Microsoft.Resources/subscriptions/resourcegroups/read",
          "Microsoft.Resources/subscriptions/resourcegroups/write",
          "Microsoft.Storage/operations/read",
          "Microsoft.Storage/storageAccounts/listKeys/action",
          "Microsoft.Storage/storageAccounts/delete",
          "Microsoft.Storage/storageAccounts/read",
          "Microsoft.Storage/storageAccounts/write"
      ],
      "NotActions": [],
      "DataActions": [],
      "NotDataActions": [],
      "AssignableScopes": [
          "/subscriptions/SUBSCRIPTION_ID"
      ]
  }
  EOF

Apply the Rancher AKSv2 Role:

  az role definition create --role-definition rancher-azure.json

Verify if the Rancher AKSv2 Role was created:

  az role definition list | grep "Rancher AKSv2"

Syncing

The AKS provisioner can synchronize the state of an AKS cluster between Rancher and the provider. For an in-depth technical explanation of how this works, see Syncing.

For information on configuring the refresh interval, see this section.

Programmatically Creating AKS Clusters

The most common way to programmatically deploy AKS clusters through Rancher is by using the Rancher2 Terraform provider. The documentation for creating clusters with Terraform is here.