In-Depth Guide to AKS Workload Identity and Managed Identity: Practical Implementation and Best Practices

Managing identities securely and efficiently is a critical aspect of running containerized workloads in Azure Kubernetes Service (AKS). Leveraging Azure Managed Identities allows you to authenticate to Azure resources without the overhead of managing credentials manually. This comprehensive guide dives deep into AKS workload identity and managed identities, offering practical examples, best practices, and advanced techniques for intermediate to advanced users.

Introduction to AKS Managed Identities

Azure Managed Identities offer an elegant solution to securely access Azure resources from AKS without embedding credentials in your applications or cluster.

System-assigned managed identity: Tied directly to the AKS cluster lifecycle.
User-assigned managed identity: A standalone Azure resource that can be shared across multiple clusters or resources.

Using managed identities enhances security by eliminating secrets management and leveraging Azure Active Directory (Azure AD) for fine-grained access control.

Types of Managed Identities in AKS

1. System-assigned Managed Identity

Automatically created and enabled by default during AKS cluster creation.
Lifecycle tied to the AKS cluster.
Suitable for clusters with simple identity requirements.

2. User-assigned Managed Identity

Created independently and assigned to the cluster.
Can be shared across multiple clusters or resources.
Offers flexibility and easier management in multi-cluster environments.

3. Kubelet Managed Identity

A specialized user-assigned managed identity used specifically by kubelets.
Allows granular permissions for node-level operations, such as pulling images from Azure Container Registry (ACR).

Understanding these types helps architects choose the right approach for their security and operational needs.

Prerequisites and Environment Setup

Before diving into AKS managed identities, ensure the following:

Azure CLI version 2.23.0 or later is installed. Use az --version to check.
Set the appropriate Azure subscription context:

az account set --subscription "<your-subscription-id>"

Create a resource group if not existing:

az group create --name "<resource-group-name>" --location "<region>"

Have a virtual network and subnet ready if you want to use advanced networking.

Implementing System-Assigned Managed Identity

Creating a New AKS Cluster with System-Assigned Identity

By default, AKS creates a system-assigned managed identity during cluster creation. You can explicitly enable it:

az aks create \
  --resource-group "<resource-group-name>" \
  --name "<aks-cluster-name>" \
  --enable-managed-identity \
  --generate-ssh-keys

Updating an Existing AKS Cluster to Use System-Assigned Managed Identity

If your cluster uses a service principal, migrate it by:

az aks update \
  --resource-group "<resource-group-name>" \
  --name "<aks-cluster-name>" \
  --enable-managed-identity

Note: After migration, node pools still use service principals until upgraded:

az aks nodepool upgrade \
  --resource-group "<resource-group-name>" \
  --cluster-name "<aks-cluster-name>" \
  --name "<nodepool-name>" \
  --node-image-only

Assigning Roles to System-Assigned Managed Identity

To grant access to Azure resources (e.g., virtual networks), assign the appropriate role:

CLIENT_ID=$(az aks show \
  --name "<aks-cluster-name>" \
  --resource-group "<resource-group-name>" \
  --query identity.principalId \
  --output tsv)

az role assignment create \
  --assignee $CLIENT_ID \
  --role "Network Contributor" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<vnet-resource-group>"

Permissions may take up to 60 minutes to propagate.

Working with User-Assigned Managed Identity

User-assigned managed identities provide reusability and better lifecycle management.

Creating a User-Assigned Managed Identity

az identity create \
  --name "<identity-name>" \
  --resource-group "<resource-group-name>"

Record the clientId, principalId, and id (resource ID) from the output.

Assigning Roles to User-Assigned Managed Identity

For example, to enable secret access in Key Vault:

az role assignment create \
  --assignee "<client-id>" \
  --role "Key Vault Secrets User" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<keyvault-resource-group>/providers/Microsoft.KeyVault/vaults/<keyvault-name>"

Creating or Updating AKS Cluster with User-Assigned Identity

New cluster:

az aks create \
  --resource-group "<resource-group-name>" \
  --name "<cluster-name>" \
  --network-plugin azure \
  --vnet-subnet-id "/subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/<subnet>" \
  --dns-service-ip 10.2.0.10 \
  --service-cidr 10.2.0.0/24 \
  --assign-identity "<user-assigned-identity-resource-id>" \
  --generate-ssh-keys

Update existing cluster:

az aks update \
  --resource-group "<resource-group-name>" \
  --name "<cluster-name>" \
  --enable-managed-identity \
  --assign-identity "<user-assigned-identity-resource-id>"

Migrating from system-assigned to user-assigned managed identity does not cause downtime but token refresh can take several hours.

Kubelet Managed Identity Explained

In AKS, kubelets (node agents) require permissions to interact with Azure resources, such as pulling images from Azure Container Registry (ACR). Using a dedicated kubelet managed identity improves security by limiting privileges.

Creating a Kubelet Managed Identity

az identity create \
  --name "<kubelet-identity-name>" \
  --resource-group "<resource-group-name>"

Assigning Roles to Kubelet Managed Identity

Assign the acrpull role to allow image pulls from ACR:

az role assignment create \
  --assignee "<kubelet-client-id>" \
  --role "acrpull" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<acr-resource-group>/providers/Microsoft.ContainerRegistry/registries/<acr-name>"

Creating a New AKS Cluster with Kubelet Managed Identity

az aks create \
  --resource-group "<resource-group-name>" \
  --name "<aks-cluster-name>" \
  --network-plugin azure \
  --vnet-subnet-id "/subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/<subnet>" \
  --dns-service-ip 10.2.0.10 \
  --service-cidr 10.2.0.0/24 \
  --assign-identity "<control-plane-identity-resource-id>" \
  --assign-kubelet-identity "<kubelet-identity-resource-id>" \
  --generate-ssh-keys

Updating an Existing AKS Cluster to Use Kubelet Managed Identity

Warning: This operation upgrades node pools and can cause downtime. Use Pod Disruption Budgets and maintenance windows.

az aks update \
  --resource-group "<resource-group-name>" \
  --name "<aks-cluster-name>" \
  --enable-managed-identity \
  --assign-identity "<control-plane-identity-resource-id>" \
  --assign-kubelet-identity "<kubelet-identity-resource-id>"

Retrieving Kubelet Identity Information

az aks show \
  --name "<aks-cluster-name>" \
  --resource-group "<resource-group-name>" \
  --query "identityProfile.kubeletidentity"

Best Practices and Real-World Scenarios

Secure Access to Azure Resources

Use managed identities instead of service principals to reduce credential management overhead.
Assign least privilege roles to identities to follow the principle of least privilege.

Multi-Cluster Identity Management

Use user-assigned managed identities when managing multiple clusters to simplify role assignments and identity lifecycle.

Kubelet Identity Management

Separate kubelet identity from control plane identity to tightly scope permissions.
Always assign acrpull to kubelet identity to enable secure image retrieval.

Cluster Upgrades and Maintenance

When updating identities, expect node pool upgrades which can cause downtime.
Use Pod Disruption Budgets and schedule updates during maintenance windows.

Azure DevOps and CI/CD Integration

Use managed identities in pipelines to authenticate securely to AKS for deployments.
Avoid embedding connection strings or secrets in pipeline variables.

Troubleshooting and Limitations

Common Issues

Permission propagation delay: Role assignments can take up to 60 minutes to propagate.
Interference with pod-managed identity: When using aad-pod-identity, Node-Managed Identity (NMI) pods intercept IMDS calls which may require configuring AzurePodIdentityException CRD.

Known Limitations

Cannot migrate or move managed identity-enabled clusters across tenants.
System-assigned identities are not supported with custom private DNS zones.
Certain Azure Government regions do not support user-assigned managed identities.

Conclusion and Next Steps

Leveraging managed identities in AKS is a security best practice, simplifying credential management and improving access control. This guide provided an in-depth look at types of managed identities, how to implement them, and practical advice for real-world use cases.

Suggested Next Steps

Explore Azure Resource Manager (ARM) templates to automate managed identity-enabled cluster deployments.
Learn to use kubelogin for Microsoft Entra authentication integration.
Experiment with pod-managed identities (aad-pod-identity) for workload-level identity management.

Implementing managed identities correctly can significantly enhance your AKS cluster security posture and operational efficiency. Start integrating managed identities today and embrace Azure-native security features.

Author: Joseph Perez