Use managed identities in Azure Kubernetes Service

Currently, an Azure Kubernetes Service (AKS) cluster (specifically, the Kubernetes cloud provider) requires an identity to create additional resources like load balancers and managed disks in Azure. This identity can be either a managed identity or a service principal. If you use a service principal, you must either provide one or AKS creates one on your behalf. If you use managed identity, this will be created for you by AKS automatically. Clusters using service principals eventually reach a state in which the service principal must be renewed to keep the cluster working. Managing service principals adds complexity, which is why it's easier to use managed identities instead. The same permission requirements apply for both service principals and managed identities.

Managed identities are essentially a wrapper around service principals, and make their management simpler. Credential rotation for MI happens automatically every 46 days according to Azure Active Directory default. AKS uses both system-assigned and user-assigned managed identity types. These identities are currently immutable. To learn more, read about managed identities for Azure resources.

Before you begin

You must have the following resource installed:

  • The Azure CLI, version 2.8.0 or later

Limitations

  • AKS clusters with managed identities can be enabled only during creation of the cluster.
  • During cluster upgrade operations, the managed identity is temporarily unavailable.
  • Tenants move / migrate of managed identity enabled clusters isn't supported.
  • If the cluster has aad-pod-identity enabled, Node Managed Identity (NMI) pods modify the nodes' iptables to intercept calls to the Azure Instance Metadata endpoint. This configuration means any request made to the Metadata endpoint is intercepted by NMI even if the pod doesn't use aad-pod-identity. AzurePodIdentityException CRD can be configured to inform aad-pod-identity that any requests to the Metadata endpoint originating from a pod that matches labels defined in CRD should be proxied without any processing in NMI. The system pods with kubernetes.azure.com/managedby: aks label in kube-system namespace should be excluded in aad-pod-identity by configuring the AzurePodIdentityException CRD. For more information, see Disable aad-pod-identity for a specific pod or application. To configure an exception, install the mic-exception YAML.

Summary of managed identities

AKS uses several managed identities for built-in services and add-ons.

Identity Name Use case Default permissions Bring your own identity
Control plane not visible Used by AKS for managed networking resources including ingress load balancers and AKS managed public IPs Contributor role for Node resource group Preview
Kubelet AKS Cluster Name-agentpool Authentication with Azure Container Registry (ACR) NA (for kubernetes v1.15+) Not currently supported
Add-on AzureNPM No identity required NA No
Add-on AzureCNI network monitoring No identity required NA No
Add-on azurepolicy (gatekeeper) No identity required NA No
Add-on azurepolicy No identity required NA No
Add-on Calico No identity required NA No
Add-on Dashboard No identity required NA No
Add-on HTTPApplicationRouting Manages required network resources Reader role for node resource group, contributor role for DNS zone No
Add-on Ingress application gateway Manages required network resources Contributor role for node resource group No
Add-on omsagent Used to send AKS metrics to Azure Monitor Monitoring Metrics Publisher role No
Add-on Virtual-Node (ACIConnector) Manages required network resources for Azure Container Instances (ACI) Contributor role for node resource group No
OSS project aad-pod-identity Enables applications to access cloud resources securely with Azure Active Directory (AAD) NA Steps to grant permission at https://github.com/Azure/aad-pod-identity#role-assignment.

Create an AKS cluster with managed identities

You can now create an AKS cluster with managed identities by using the following CLI commands.

First, create an Azure resource group:

# Create an Azure resource group
az group create --name myResourceGroup --location westus2

Then, create an AKS cluster:

az aks create -g myResourceGroup -n myManagedCluster --enable-managed-identity

A successful cluster creation using managed identities contains this service principal profile information:

"servicePrincipalProfile": {
    "clientId": "msi"
  }

Use the following command to query objectid of your control plane managed identity:

az aks show -g myResourceGroup -n myManagedCluster --query "identity"

The result should look like:

{
  "principalId": "<object_id>",   
  "tenantId": "<tenant_id>",      
  "type": "SystemAssigned"                                 
}

Once the cluster is created, you can then deploy your application workloads to the new cluster and interact with it just as you've done with service-principal-based AKS clusters.

Note

For creating and using your own VNet, static IP address, or attached Azure disk where the resources are outside of the worker node resource group, use the PrincipalID of the cluster System Assigned Managed Identity to perform a role assignment. For more information on role assignment, see Delegate access to other Azure resources.

Permission grants to cluster Managed Identity used by Azure Cloud provider may take up 60 minutes to populate.

Finally, get credentials to access the cluster:

az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

Update an existing service principal based AKS cluster to managed identities

You can now update an AKS cluster with managed identities by using the following CLI commands.

First, update the System Assigned Identity:

az aks update -g <RGName> -n <AKSName> --enable-managed-identity

Then, update the User Assigned Identity:

az aks update -g <RGName> -n <AKSName> --enable-managed-identity --assign-identity <UserAssignedIdentityResourceID> 

Note

Once the System Assigned or User Assigned identities have been updated to managed identity, perform an az nodepool upgrade --node-image-only on your nodes to complete the update to managed identity.

Bring your own control plane MI (Preview)

A custom control plane identity enables access to be granted to the existing identity prior to cluster creation. This enables scenarios such as using an custom VNET or outboundType of UDR with a managed identity.

Important

AKS preview features are available on a self-service, opt-in basis. Previews are provided "as is" and "as available," and they're excluded from the service-level agreements and limited warranty. AKS previews are partially covered by customer support on a best-effort basis. As such, these features aren't meant for production use. AKS preview features aren't available in Azure Government or Azure China 21Vianet clouds. For more information, see the following support articles:

You must have the following resources installed:

  • The Azure CLI, version 2.9.0 or later
  • The aks-preview 0.4.57 extension

Limitations for bring your own control plane MI (Preview):

  • Azure Government isn't currently supported.
  • Azure China 21Vianet isn't currently supported.
az extension add --name aks-preview
az extension list
az extension update --name aks-preview
az extension list
az feature register --name UserAssignedIdentityPreview --namespace Microsoft.ContainerService

It might take several minutes for the status to show as Registered. You can check the registration status by using the az feature list command:

az feature list -o table --query "[?contains(name, 'Microsoft.ContainerService/UserAssignedIdentityPreview')].{Name:name,State:properties.state}"

When the status shows as registered, refresh the registration of the Microsoft.ContainerService resource provider by using the az provider register command:

az provider register --namespace Microsoft.ContainerService

If you don't have a managed identity yet, you should go ahead and create one for example by using az identity CLI.

az identity create --name myIdentity --resource-group myResourceGroup

The result should look like:

{                                                                                                                                                                                 
  "clientId": "<client-id>",
  "clientSecretUrl": "<clientSecretUrl>",
  "id": "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity", 
  "location": "westus2",
  "name": "myIdentity",
  "principalId": "<principalId>",
  "resourceGroup": "myResourceGroup",                       
  "tags": {},
  "tenantId": "<tenant-id>>",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

If your managed identity is part of your subscription, you can use az identity CLI command to query it.

az identity list --query "[].{Name:name, Id:id, Location:location}" -o table

Now you can use the following command to create your cluster with your existing identity:

az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --network-plugin azure \
    --vnet-subnet-id <subnet-id> \
    --docker-bridge-address 172.17.0.1/16 \
    --dns-service-ip 10.2.0.10 \
    --service-cidr 10.2.0.0/24 \
    --enable-managed-identity \
    --assign-identity <identity-id> \

A successful cluster creation using your own managed identities contains this userAssignedIdentities profile information:

 "identity": {
   "principalId": null,
   "tenantId": null,
   "type": "UserAssigned",
   "userAssignedIdentities": {
     "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity": {
       "clientId": "<client-id>",
       "principalId": "<principal-id>"
     }
   }
 },

Next steps