Skip to content

Commit ba36b2e

Browse files
schaffererinschaffererin
committed
Editing pass
1 parent 18fb4c5 commit ba36b2e

File tree

1 file changed

+62
-85
lines changed

1 file changed

+62
-85
lines changed

‎articles/aks/use-managed-identity.md

Lines changed: 62 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,102 @@
11
---
2-
title: Use a managed identity in Azure Kubernetes Service
3-
description: Learn how to use a system-assigned or user-assigned managed identity in Azure Kubernetes Service (AKS)
2+
title: Use a managed identity in Azure Kubernetes Service (AKS)
3+
description: Learn how to use a system-assigned or user-assigned managed identity in Azure Kubernetes Service (AKS).
44
ms.topic: article
55
ms.custom: devx-track-azurecli
6-
ms.date: 11/08/2022
6+
ms.date: 04/25/2023
77
---
88

9-
# Use a managed identity in Azure Kubernetes Service
9+
# Use a managed identity in Azure Kubernetes Service (AKS)
1010

11-
An Azure Kubernetes Service (AKS) cluster requires an identity to access Azure resources like load balancers and managed disks. This identity can be either a managed identity or a service principal. By default, when you create an AKS cluster a system-assigned managed identity is automatically created. The identity is managed by the Azure platform and doesn't require you to provision or rotate any secrets. For more information about managed identities in Azure AD, see [Managed identities for Azure resources][managed-identity-resources-overview].
11+
Azure Kubernetes Service (AKS) clusters require an identity to access Azure resources like load balancers and managed disks. This identity can be a *managed identity* or *service principal*. A system-assigned managed identity is automatically created when you create an AKS cluster. This identity is managed by the Azure platform and doesn't require you to provision or rotate any secrets. For more information about managed identities in Azure AD, see [Managed identities for Azure resources][managed-identity-resources-overview].
1212

13-
To use a [service principal](kubernetes-service-principal.md), you have to create one, as AKS does not create one automatically. Clusters using a service principal eventually expire and the service principal must be renewed to keep the cluster working. Managing service principals adds complexity, thus it's easier to use managed identities instead. The same permission requirements apply for both service principals and managed identities.
13+
AKS doesn't automatically create a [service principal](kubernetes-service-principal.md), so you have to create one. Clusters that use a service principal eventually expire, and the service principal must be renewed to keep the cluster working. Managing service principals adds complexity, so it's easier to use managed identities instead. The same permission requirements apply for both service principals and managed identities. Managed identities use certificate-based authentication. Each managed identity's credentials have an expiration of *90 days* and are rolled after *45 days*. AKS uses both system-assigned and user-assigned managed identity types, and these identities are immutable.
1414

15-
Managed identities are essentially a wrapper around service principals, and make their management simpler. Managed identities use certificate-based authentication, and each managed identities credential has an expiration of 90 days and it's rolled after 45 days. AKS uses both system-assigned and user-assigned managed identity types, and these identities are immutable.
15+
> [!NOTE]
16+
> If you're considering implementing [Azure AD pod-managed identity][aad-pod-identity] on your AKS cluster, we recommend you first review the [Azure AD workload identity overview][workload-identity-overview]. This authentication method replaces Azure AD pod-managed identity (preview) and is the recommended method.
1617
17-
## Prerequisites
18+
## Before you begin
1819

19-
Azure CLI version 2.23.0 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
20+
Make sure you have Azure CLI version 2.23.0 or later installed. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
2021

2122
## Limitations
2223

23-
* Tenants move or migrate a managed identity-enabled cluster isn't supported.
24-
* If the cluster has Azure AD pod-managed identity (`aad-pod-identity`) enabled, Node-Managed Identity (NMI) pods modify the nodes'
25-
iptables to intercept calls to the Azure Instance Metadata (IMDS) endpoint. This configuration means any
26-
request made to the Metadata endpoint is intercepted by NMI even if the pod doesn't use
27-
`aad-pod-identity`. AzurePodIdentityException CRD can be configured to inform `aad-pod-identity`
28-
that any requests to the Metadata endpoint originating from a pod that matches labels defined in
29-
CRD should be proxied without any processing in NMI. The system pods with
30-
`kubernetes.azure.com/managedby: aks` label in _kube-system_ namespace should be excluded in
31-
`aad-pod-identity` by configuring the AzurePodIdentityException CRD. For more information, see
32-
[Disable aad-pod-identity for a specific pod or application](https://azure.github.io/aad-pod-identity/docs/configure/application_exception).
33-
To configure an exception, install the
34-
[mic-exception YAML](https://github.com/Azure/aad-pod-identity/blob/master/deploy/infra/mic-exception.yaml).
35-
36-
> [!NOTE]
37-
> If you are considering implementing [Azure AD pod-managed identity][aad-pod-identity] on your AKS cluster,
38-
> we recommend you first review the [workload identity overview][workload-identity-overview] article to understand our
39-
> recommendations and options to set up your cluster to use an Azure AD workload identity (preview).
40-
> This authentication method replaces pod-managed identity (preview), which integrates with the Kubernetes native capabilities
41-
> to federate with any external identity providers.
24+
* Tenants moving or migrating a managed identity-enabled cluster isn't supported.
25+
* If the cluster has Azure AD pod-managed identity (`aad-pod-identity`) enabled, Node-Managed Identity (NMI) pods modify the iptables of the nodes to intercept calls to the Azure Instance Metadata (IMDS) 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` of 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.
26+
* For more information, see [Disable aad-pod-identity for a specific pod or application](https://azure.github.io/aad-pod-identity/docs/configure/application_exception).
27+
* To configure an exception, install the [mic-exception YAML](https://github.com/Azure/aad-pod-identity/blob/master/deploy/infra/mic-exception.yaml).
28+
* AKS doesn't support the use of a system-assigned managed identity if using a custom private DNS zone.
4229

4330
## Summary of managed identities
4431

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

4734
| Identity | Name | Use case | Default permissions | Bring your own identity
4835
|----------------------------|-----------|----------|
49-
| Control plane | AKS Cluster Name | Used by AKS control plane components to manage cluster resources including ingress load balancers and AKS managed public IPs, Cluster Autoscaler, Azure Disk & File CSI drivers | Contributor role for Node resource group | Supported
50-
| Kubelet | AKS Cluster Name-agentpool | Authentication with Azure Container Registry (ACR) | NA (for kubernetes v1.15+) | Supported
51-
| Add-on | AzureNPM | No identity required | NA | No
52-
| Add-on | AzureCNI network monitoring | No identity required | NA | No
53-
| Add-on | azure-policy (gatekeeper) | No identity required | NA | No
54-
| Add-on | azure-policy | No identity required | NA | No
55-
| Add-on | Calico | No identity required | NA | No
56-
| Add-on | Dashboard | No identity required | NA | No
57-
| Add-on | HTTPApplicationRouting | Manages required network resources | Reader role for node resource group, contributor role for DNS zone | No
58-
| Add-on | Ingress application gateway | Manages required network resources| Contributor role for node resource group | No
59-
| Add-on | omsagent | Used to send AKS metrics to Azure Monitor | Monitoring Metrics Publisher role | No
60-
| Add-on | Virtual-Node (ACIConnector) | Manages required network resources for Azure Container Instances (ACI) | Contributor role for node resource group | No
61-
| OSS project | aad-pod-identity | Enables applications to access cloud resources securely with Microsoft Azure Active Directory (Azure AD) | NA | Steps to grant permission at [Azure AD Pod Identity Role Assignment configuration](https://azure.github.io/aad-pod-identity/docs/getting-started/role-assignment/).
62-
63-
## Create an AKS cluster using a managed identity
36+
| Control plane | AKS Cluster Name | Used by AKS control plane components to manage cluster resources including ingress load balancers and AKS-managed public IPs, Cluster Autoscaler, Azure Disk & File CSI drivers. | Contributor role for Node resource group | Supported
37+
| Kubelet | AKS Cluster Name-agentpool | Authentication with Azure Container Registry (ACR). | N/A (for kubernetes v1.15+) | Supported
38+
| Add-on | AzureNPM | No identity required. | N/A | No
39+
| Add-on | AzureCNI network monitoring | No identity required. | N/A | No
40+
| Add-on | azure-policy (gatekeeper) | No identity required. | N/A | No
41+
| Add-on | azure-policy | No identity required. | N/A | No
42+
| Add-on | Calico | No identity required. | N/A | No
43+
| Add-on | Dashboard | No identity required. | N/A | No
44+
| Add-on | HTTPApplicationRouting | Manages required network resources. | Reader role for node resource group, contributor role for DNS zone | No
45+
| Add-on | Ingress application gateway | Manages required network resources. | Contributor role for node resource group | No
46+
| Add-on | omsagent | Used to send AKS metrics to Azure Monitor. | Monitoring Metrics Publisher role | No
47+
| Add-on | Virtual-Node (ACIConnector) | Manages required network resources for Azure Container Instances (ACI). | Contributor role for node resource group | No
48+
| OSS project | aad-pod-identity | Enables applications to access cloud resources securely with Microsoft Azure Active Directory (Azure AD). | N/A | Steps to grant permission at [Azure AD Pod Identity Role Assignment configuration](https://azure.github.io/aad-pod-identity/docs/getting-started/role-assignment/).
49+
50+
## Enable managed identities on a new AKS cluster
6451

6552
> [!NOTE]
66-
> AKS will create a system-assigned kubelet identity in the Node resource group if you do not [specify your own kubelet managed identity][Use a pre-created kubelet managed identity].
53+
> AKS creates a system-assigned kubelet identity in the node resource group if you don't [specify your own kubelet managed identity][Use a pre-created kubelet managed identity].
6754
68-
You can create an AKS cluster using a system-assigned managed identity by running the following CLI command.
55+
1. Create an Azure resource group using the [`az group create`][az-group-create] command.
6956

70-
First, create an Azure resource group:
57+
```azurecli-interactive
58+
az group create --name myResourceGroup --location westus2
59+
```
7160
72-
```azurecli-interactive
73-
# Create an Azure resource group
74-
az group create --name myResourceGroup --location westus2
75-
```
61+
2. Create an AKS cluster using the [`az aks create`][az-aks-create] command.
7662
77-
Then, create an AKS cluster:
63+
```azurecli-interactive
64+
az aks create -g myResourceGroup -n myManagedCluster --enable-managed-identity
65+
```
7866
79-
```azurecli-interactive
80-
az aks create -g myResourceGroup -n myManagedCluster --enable-managed-identity
81-
```
67+
3. Get credentials to access the cluster using the [`az aks get-credentials`][az-aks-get-credentials] command.
8268
83-
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.
69+
```azurecli-interactive
70+
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
71+
```
8472
85-
Finally, get credentials to access the cluster:
73+
## Enable managed identities on an existing AKS cluster
8674
87-
```azurecli-interactive
88-
az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
89-
```
75+
* Update an existing AKS cluster currently using a service principal to work with a system-assigned managed identity using the [`az aks update`][az-aks-update] command.
9076
91-
## Update an AKS cluster to use a managed identity
77+
```azurecli-interactive
78+
az aks update -g myResourceGroup -n myManagedCluster --enable-managed-identity
79+
```
9280
93-
> [!NOTE]
94-
> If AKS has custom private DNS zone, AKS does not support to use system-assigned managed identity.
95-
96-
To update an AKS cluster currently using a service principal to work with a system-assigned managed identity, run the following CLI command.
97-
98-
```azurecli-interactive
99-
az aks update -g <RGName> -n <AKSName> --enable-managed-identity
100-
```
81+
After updating your cluster, the control plane and pods use the managed identity. kubelet continues using a service principal until you upgrade your agentpool. You can use the `az aks nodepool upgrade --node-image-only` command on your nodes to update to a managed identity. A nodepool upgrade causes downtime for your AKS cluster as the nodes in the nodepools are cordoned/drained and then reimaged.
10182
10283
> [!NOTE]
103-
> An update will only work if there is an actual VHD update to consume. If you are running the latest VHD, you'll need to wait until the next VHD is available in order to perform the update.
10484
>
105-
106-
> [!NOTE]
107-
> After updating, your cluster's control plane and addon pods, they use the managed identity, but kubelet will continue using a service principal until you upgrade your agentpool. Perform an `az aks nodepool upgrade --node-image-only` on your nodes to complete the update to a managed identity.
85+
> * Keep the following information in mind when updating your cluster:
10886
>
109-
> If your cluster was using `--attach-acr` to pull from image from Azure Container Registry, after updating your cluster to a managed identity, you need to rerun `az aks update --attach-acr <ACR Resource ID>` to let the newly created kubelet used for managed identity get the permission to pull from ACR. Otherwise, you won't be able to pull from ACR after the upgrade.
87+
> * An update only works if there's a VHD update to consume. If you're running the latest VHD, you need to wait until the next VHD is available in order to perform the update.
11088
>
111-
> The Azure CLI will ensure your addon's permission is correctly set after migrating, if you're not using the Azure CLI to perform the migrating operation, you'll need to handle the addon identity's permission by yourself. Here is one example using an [Azure Resource Manager](../role-based-access-control/role-assignments-template.md) template.
112-
113-
> [!WARNING]
114-
> A nodepool upgrade will cause downtime for your AKS cluster as the nodes in the nodepools will be cordoned/drained and then reimaged.
89+
> * The Azure CLI ensures your addon's permission is correctly set after migrating. If you're not using the Azure CLI to perform the migrating operation, you need to handle the addon identity's permission by yourself. For an example using an Azure Resource Manager (ARM) template, see [Assign Azure roles using ARM templates](../role-based-access-control/role-assignments-template.md).
90+
>
91+
> * If your cluster was using `--attach-acr` to pull from images from Azure Container Registry, you need to run the `az aks update --attach-acr <ACR resource ID>` command to let the newly-created kubelet used for managed identity get the permission to pull from ACR. Otherwise, you won't be able to pull from ACR after the update.
11592
11693
## Add role assignment for control plane identity
11794
118-
When creating and using your own VNet, attached Azure disk, static IP address, route table or user-assigned kubelet identity where the resources are outside of the worker node resource group, the Azure CLI adds the role assignment automatically. If you are using an ARM template or other method, you need to use the Principal ID of the cluster managed identity to perform a role assignment.
95+
When you create and use your own VNet, attached Azure disk, static IP address, route table, or user-assigned kubelet identity where the resources are outside of the worker node resource group, the Azure CLI adds the role assignment automatically. If you're using an ARM template or another method, you need to use the Principal ID of the cluster managed identity to perform a role assignment.
11996
120-
> [!NOTE]
121-
> If you are not using the Azure CLI but using your own VNet, attached Azure disk, static IP address, route table or user-assigned kubelet identity that are outside of the worker node resource group, it's recommended to use [user-assigned control plane identity][Bring your own control plane managed identity]. For system-assigned control plane identity, we cannot get the identity ID before creating cluster, which delays role assignment from taking effect.
97+
If you're not using the Azure CLI, but you're using your own VNet, attached Azure disk, static IP address, route table, or user-assigned kubelet identity that's outside of the worker node resource group, we recommend using [user-assigned control plane identity][Bring your own control plane managed identity]. For system-assigned control plane identity, we can't get the identity ID before creating cluster, which delays the role assignment from taking effect.
12298
123-
### Get the Principal ID of control plane identity
99+
### Get the principal ID of control plane identity
124100
125101
You can find existing identity's Principal ID by running the following command:
126102
@@ -456,20 +432,21 @@ A successful cluster update using your own kubelet managed identity contains the
456432

457433
## Next steps
458434

459-
Use [Azure Resource Manager templates ][aks-arm-template] to create a managed identity-enabled cluster.
435+
Use [Azure Resource Manager templates][aks-arm-template] to create a managed identity-enabled cluster.
460436

461437
<!-- LINKS - external -->
462438
[aks-arm-template]: /azure/templates/microsoft.containerservice/managedclusters
463439

464440
<!-- LINKS - internal -->
465441
[install-azure-cli]: /cli/azure/install-azure-cli
466442
[az-identity-create]: /cli/azure/identity#az_identity_create
467-
[az-identity-list]: /cli/azure/identity#az_identity_list
468-
[az-feature-list]: /cli/azure/feature#az_feature_list
469-
[az-provider-register]: /cli/azure/provider#az_provider_register
470443
[managed-identity-resources-overview]: ../active-directory/managed-identities-azure-resources/overview.md
471444
[Bring your own control plane managed identity]: use-managed-identity.md#bring-your-own-control-plane-managed-identity
472445
[Use a pre-created kubelet managed identity]: use-managed-identity.md#use-a-pre-created-kubelet-managed-identity
473446
[workload-identity-overview]: workload-identity-overview.md
474447
[aad-pod-identity]: use-azure-ad-pod-identity.md
475448
[add role assignment for control plane identity]: use-managed-identity.md#add-role-assignment-for-control-plane-identity
449+
[az-group-create]: /cli/azure/group#az_group_create
450+
[az-aks-create]: /cli/azure/aks#az_aks_create
451+
[az-aks-get-credentials]: /cli/azure/aks#az_aks_get_credentials
452+
[az-aks-update]: /cli/azure/aks#az_aks_update

0 commit comments

Comments
 (0)