You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how update or reset the service principal or Azure AD Application credentials for an Azure Kubernetes Service (AKS) cluster.
2
+
title: Update or rotate the credentials for an Azure Kubernetes Service (AKS) cluster
3
+
description: Learn how update or rotate the service principal or Azure AD Application credentials for an Azure Kubernetes Service (AKS) cluster.
5
4
ms.topic: article
6
-
ms.date: 03/11/2019
7
-
5
+
ms.date: 02/28/2023
8
6
---
9
7
10
-
# Update or rotate the credentials for Azure Kubernetes Service (AKS)
11
-
12
-
AKS clusters created with a service principal have a one-year expiration time. As you near the expiration date, you can reset the credentials to extend the service principal for an additional period of time. You may also want to update, or rotate, the credentials as part of a defined security policy. This article details how to update these credentials for an AKS cluster.
8
+
# Update or rotate the credentials for an Azure Kubernetes Service (AKS) cluster
13
9
14
-
You may also have [integrated your AKS cluster with Azure Active Directory (Azure AD)][aad-integration], and use it as an authentication provider for your cluster. In that case you will have 2 more identities created for your cluster, the Azure AD Server App and the Azure AD Client App, you may also reset those credentials.
15
-
16
-
Alternatively, you can use a managed identity for permissions instead of a service principal. Managed identities are easier to manage than service principals and do not require updates or rotations. For more information, see [Use managed identities](use-managed-identity.md).
10
+
AKS clusters created with a service principal have a one-year expiration time. As you near the expiration date, you can reset the credentials to extend the service principal for an additional period of time. You may also want to update, or rotate, the credentials as part of a defined security policy. AKS clusters [integrated with Azure Active Directory (Azure AD)][aad-integration] as an authentication provider have two more identities: the Azure AD Server App and the Azure AD Client App. This article details how to update the service principal and Azure AD credentials for an AKS cluster.
17
11
18
12
> [!NOTE]
19
-
> - When you use the `az aks create` command to generate the service principal automatically, the service principal credentials are written to the file `~/.azure/aksServicePrincipal.json` on the machine used to run the command
20
-
> - If you don't specify a service principal with Azure CLI commands, the default service principal located at `~/.azure/aksServicePrincipal.json` is used
13
+
> Alternatively, you can use a managed identity for permissions instead of a service principal. Managed identities don't require updates or rotations. For more information, see [Use managed identities](use-managed-identity.md).
21
14
22
15
## Before you begin
23
16
@@ -28,24 +21,24 @@ You need the Azure CLI version 2.0.65 or later installed and configured. Run `a
28
21
When you want to update the credentials for an AKS cluster, you can choose to either:
29
22
30
23
* Update the credentials for the existing service principal.
31
-
* Create a new service principal and update the cluster to use these new credentials.
24
+
* Create a new service principal and update the cluster to use these new credentials.
32
25
33
26
> [!WARNING]
34
27
> If you choose to create a *new* service principal, wait around 30 minutes for the service principal permission to propagate across all regions. Updating a large AKS cluster to use these credentials may take a long time to complete.
35
28
36
29
### Check the expiration date of your service principal
37
30
38
-
To check the expiration date of your service principal, use the [az ad sp credential list][az-ad-sp-credential-list] command. The following example gets the service principal ID for the cluster named *myAKSCluster* in the *myResourceGroup* resource group using the [az aks show][az-aks-show] command. The service principal ID is set as a variable named *SP_ID* for use with the [az ad sp credential list][az-ad-sp-credential-list] command.
31
+
To check the expiration date of your service principal, use the [`az ad app credential list`][az-ad-app-credential-list] command. The following example gets the service principal ID for the cluster named *myAKSCluster* in the *myResourceGroup* resource group using the [`az aks show`][az-aks-show] command. The service principal ID is set as a variable named *SP_ID*.
39
32
40
33
```azurecli
41
34
SP_ID=$(az aks show --resource-group myResourceGroup --name myAKSCluster \
42
35
--query servicePrincipalProfile.clientId -o tsv)
43
36
az ad app credential list --id "$SP_ID" --query "[].endDateTime" -o tsv
44
37
```
45
38
46
-
### Reset the existing service principal credential
39
+
### Reset the existing service principal credentials
47
40
48
-
To update the credentials for the existing service principal, get the service principal ID of your cluster using the [az aks show][az-aks-show] command. The following example gets the ID for the cluster named *myAKSCluster* in the *myResourceGroup* resource group. The service principal ID is set as a variable named *SP_ID*for use in additional command. These commands use Bash syntax.
41
+
To update the credentials for the existing service principal, get the service principal ID of your cluster using the [`az aks show`][az-aks-show] command. The following example gets the ID for the cluster named *myAKSCluster* in the *myResourceGroup* resource group. The service principal ID is set as a variable named *SP_ID*to use in additional command. These commands use Bash syntax.
49
42
50
43
> [!WARNING]
51
44
> When you reset your cluster credentials on an AKS cluster that uses Azure Virtual Machine Scale Sets, a [node image upgrade][node-image-upgrade] is performed to update your nodes with the new credential information.
@@ -55,25 +48,26 @@ SP_ID=$(az aks show --resource-group myResourceGroup --name myAKSCluster \
55
48
--query servicePrincipalProfile.clientId -o tsv)
56
49
```
57
50
58
-
With a variable set that contains the service principal ID, now reset the credentials using [az ad sp credential reset][az-ad-sp-credential-reset]. The following example lets the Azure platform generate a new secure secret for the service principal. This new secure secret is also stored as a variable.
51
+
Use the variable containing the service principal ID to reset the credentials using the [`az ad app credential reset`][az-ad-app-credential-reset] command. The following example enables the Azure platform to generate a new secure secret for the service principal and stores it as a variable named *SP_SECRET*.
Now continue on to[update AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials). This step is necessary for the Service Principal changes to reflect on the AKS cluster.
57
+
Next, you can[update AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials). This step is necessary for the Service Principal changes to reflect on the AKS cluster.
65
58
66
59
### Create a new service principal
67
60
68
-
If you chose to update the existing service principal credentials in the previous section, skip this step. Continue to [update AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials).
61
+
> [!NOTE]
62
+
> If you updated the existing service principal credentials in the previous section, skip this section and instead [update the AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials).
69
63
70
-
To create a service principal and then update the AKS cluster to use these new credentials, use the [az ad sp create-for-rbac][az-ad-sp-create] command.
64
+
To create a service principal and update the AKS cluster to use the new credentials, use the [`az ad sp create-for-rbac`][az-ad-sp-create] command.
71
65
72
66
```azurecli-interactive
73
67
az ad sp create-for-rbac --role Contributor --scopes /subscriptions/mySubscriptionID
74
68
```
75
69
76
-
The output is similar to the following example. Make a note of your own `appId` and `password`. These values are used in the next step.
70
+
The output is similar to the following example output. Make a note of your own `appId` and `password` to use in the next step.
77
71
78
72
```json
79
73
{
@@ -84,39 +78,34 @@ The output is similar to the following example. Make a note of your own `appId`
84
78
}
85
79
```
86
80
87
-
Now define variables for the service principal ID and client secret using the output from your own [az ad sp create-for-rbac][az-ad-sp-create] command, as shown in the following example. The *SP_ID* is your *appId*, and the *SP_SECRET* is your *password*:
81
+
Define variables for the service principal ID and client secret using your output from running the [`az ad sp create-for-rbac`][az-ad-sp-create] command. The *SP_ID* is your *appId*, and the *SP_SECRET* is your *password*.
88
82
89
83
```console
90
84
SP_ID=7d837646-b1f3-443d-874c-fd83c7c739c5
91
85
SP_SECRET=a5ce83c9-9186-426d-9183-614597c7f2f7
92
86
```
93
87
94
-
Now continue on to[update AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials). This step is necessary for the Service Principal changes to reflect on the AKS cluster.
88
+
Next, you can[update AKS cluster with new service principal credentials](#update-aks-cluster-with-new-service-principal-credentials). This step is necessary for the Service Principal changes to reflect on the AKS cluster.
95
89
96
90
## Update AKS cluster with new service principal credentials
97
91
98
92
> [!IMPORTANT]
99
-
> For large clusters, updating the AKS cluster with a new service principal may take a long time to complete. Consider reviewing and customizing the [node surge upgrade settings][node-surge-upgrade] to minimize disruption during cluster updates and upgrades.
93
+
> For large clusters, updating the AKS cluster with a new service principal may take a long time to complete. Consider reviewing and customizing the [node surge upgrade settings][node-surge-upgrade] to minimize disruption during cluster updates and upgrades. For small and midsize clusters, it takes a few moments for the new credentials to update in the cluster.
100
94
101
-
Regardless of whether you chose to update the credentials for the existing service principal or create a service principal, you now update the AKS cluster with your new credentials using the [az aks update-credentials][az-aks-update-credentials] command. The variables for the *--service-principal* and *--client-secret* are used:
95
+
Update the AKS cluster with your new credentials using the [`az aks update-credentials`][az-aks-update-credentials] command.
102
96
103
97
```azurecli-interactive
104
98
az aks update-credentials \
105
99
--resource-group myResourceGroup \
106
100
--name myAKSCluster \
107
101
--reset-service-principal \
108
102
--service-principal "$SP_ID" \
109
-
--client-secret "${SP_SECRET:Q}"
103
+
--client-secret "${SP_SECRET}"
110
104
```
111
105
112
-
> [!NOTE]
113
-
> `${SP_SECRET:Q}` escapes any special characters in `SP_SECRET`, which can cause the command to fail. The above example works for Azure Cloud Shell and zsh terminals. For BASH terminals, use `${SP_SECRET@Q}`.
114
-
115
-
For small and midsize clusters, it takes a few moments for the service principal credentials to be updated in the AKS.
106
+
## Update AKS cluster with new Azure AD application credentials
116
107
117
-
## Update AKS Cluster with new Azure AD Application credentials
118
-
119
-
You may create new Azure AD Server and Client applications by following the [Azure AD integration steps][create-aad-app]. Or reset your existing Azure AD Applications following the [same method as for service principal reset](#reset-the-existing-service-principal-credential). After that you just need to update your cluster Azure AD Application credentials using the same [az aks update-credentials][az-aks-update-credentials] command but using the *--reset-aad* variables.
108
+
You can create new Azure AD server and client applications by following the [Azure AD integration steps][create-aad-app], or reset your existing Azure AD applications following the [same method as for service principal reset](#reset-the-existing-service-principal-credentials). After that, you need to update your cluster Azure AD application credentials using the [`az aks update-credentials`][az-aks-update-credentials] command with the *--reset-aad* variables.
120
109
121
110
```azurecli-interactive
122
111
az aks update-credentials \
@@ -128,10 +117,9 @@ az aks update-credentials \
128
117
--aad-client-app-id <CLIENT APPLICATION ID>
129
118
```
130
119
131
-
132
120
## Next steps
133
121
134
-
In this article, the service principal for the AKS cluster itself and the Azure AD Integration Applications were updated. For more information on how to manage identity for workloads within a cluster, see [Best practices for authentication and authorization in AKS][best-practices-identity].
122
+
In this article, you learned how to update or rotate service principal and Azure AD application credentials. For more information on how to manage identity for workloads within an AKS cluster, see [Best practices for authentication and authorization in AKS][best-practices-identity].
135
123
136
124
<!-- LINKS - internal -->
137
125
[install-azure-cli]: /cli/azure/install-azure-cli
@@ -141,7 +129,7 @@ In this article, the service principal for the AKS cluster itself and the Azure
0 commit comments