Merge pull request #277661 from MicrosoftDocs/main

Publish to live, Sunday 4 AM PST, 6/9

Author: ttorble

articles/aks/TOC.yml

@@ -405,10 +405,10 @@
           items:
             - name: Azure kubelogin
               href: kubelogin-authentication.md
-            - name: Create service principal
-              href: kubernetes-service-principal.md
             - name: Use managed identities
               href: use-managed-identity.md
+            - name: Create a service principal
+              href: kubernetes-service-principal.md
             - name: Enable access to AKS clusters using Trusted Access
               href: trusted-access-feature.md
             - name: Limit access to cluster configuration file

articles/aks/access-control-managed-azure-ad.md

@@ -95,7 +95,13 @@ When you integrate Microsoft Entra ID with your AKS cluster, you can use [Condit
 6. Create the AKS cluster with AKS-managed Microsoft Entra integration using the [`az aks create`][az-aks-create] command with the `--aad-admin-group-objects-ids` and `--aad-tenant-id parameters` and include the values noted in the steps earlier.
 
     ```azurecli-interactive
-    az aks create --resource-group myResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <object-id> --aad-tenant-id <tenant-id>
+    az aks create \
+        --resource-group myResourceGroup \
+        --name myManagedCluster \
+        --enable-aad \
+        --aad-admin-group-object-ids <object-id> \
+        --aad-tenant-id <tenant-id> \
+        --generate-ssh-keys        
     ```
 
 7. In the Azure portal, select **Activity** > **Privileged Access (Preview)** > **Enable Privileged Access**.

articles/aks/app-routing-dns-ssl.md

@@ -226,7 +226,7 @@ Learn about monitoring the Ingress-nginx controller metrics included with the ap
 [kubectl-get]: https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#get
 
 <!-- LINKS - internal -->
-[summary-msi]: use-managed-identity.md#summary-of-managed-identities
+[summary-msi]: use-managed-identity.md#summary-of-managed-identities-used-by-aks
 [rbac-owner]: ../role-based-access-control/built-in-roles.md#owner
 [rbac-classic]: ../role-based-access-control/rbac-and-directory-admin-roles.md#classic-subscription-administrator-roles
 [app-routing-add-on-basic-configuration]: app-routing.md

articles/aks/app-routing-nginx-configuration.md

@@ -531,7 +531,7 @@ Learn about monitoring the ingress-nginx controller metrics included with the ap
 [az-network-public-ip-create]: /cli/azure/network/public-ip#az_network_public_ip_create
 [az-network-public-ip-list]: /cli/azure/network/public-ip#az_network_public_ip_list
 [az-group-create]: /cli/azure/group#az-group-create
-[summary-msi]: use-managed-identity.md#summary-of-managed-identities
+[summary-msi]: use-managed-identity.md#summary-of-managed-identities-used-by-aks
 [rbac-owner]: ../role-based-access-control/built-in-roles.md#owner
 [rbac-classic]: ../role-based-access-control/rbac-and-directory-admin-roles.md#classic-subscription-administrator-roles
 [app-routing-add-on-basic-configuration]: app-routing.md

articles/aks/azure-cni-overlay.md

@@ -252,8 +252,6 @@ The following attributes are provided to support dual-stack clusters:
         --generate-ssh-keys
     ```
 
----
-
 ## Create an example workload
 
 Once the cluster has been created, you can deploy your workloads. This article walks you through an example workload deployment of an NGINX web server.
@@ -383,4 +381,3 @@ To learn how to utilize AKS with your own Container Network Interface (CNI) plug
 [az-aks-update]: /cli/azure/aks#az-aks-update
 [az-extension-add]: /cli/azure/extension#az-extension-add
 [az-extension-update]: /cli/azure/extension#az-extension-update
-

articles/aks/cluster-container-registry-integration.md

@@ -286,7 +286,7 @@ The AKS to ACR integration assigns the [**AcrPull** role][acr-pull] to the [Micr
 <!-- LINKS - external -->
 [byo-kubelet-identity]: use-managed-identity.md#use-a-pre-created-kubelet-managed-identity
 [image-pull-secret]: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/
-[summary-msi]: use-managed-identity.md#summary-of-managed-identities
+[summary-msi]: use-managed-identity.md#summary-of-managed-identities-used-by-aks
 [acr-pull]: ../role-based-access-control/built-in-roles.md#acrpull
 [azure-cli-install]: /cli/azure/install-azure-cli
 [azure-powershell-install]: /powershell/azure/install-az-ps

articles/aks/configure-kubenet.md

@@ -159,7 +159,7 @@ For more information to help you decide which network model to use, see [Compare
 
 #### Create a managed identity
 
-* Create a managed identity using the [`az identity`][az-identity-create] command. If you have an existing managed identity, find the Principal ID using the `az identity show --ids <identity-resource-id>` command instead.
+* Create a managed identity using the [`az identity`][az-identity-create] command. If you have an existing managed identity, find the principal ID using the `az identity show --ids <identity-resource-id>` command instead.
 
     ```azurecli-interactive
     az identity create --name myIdentity --resource-group myResourceGroup
@@ -239,7 +239,7 @@ Kubenet networking requires organized route table rules to successfully route re
 * Using the same route table with multiple AKS clusters isn't supported.
 
 > [!NOTE]
-> When you create and use your own VNet and route table with the kubenet network plugin, you need to use a [user-assigned control plane identity][bring-your-own-control-plane-managed-identity]. For a system-assigned control plane identity, you can't retrieve the identity ID before creating a cluster, which causes a delay during role assignment.
+> When you create and use your own VNet and route table with the kubenet network plugin, you must configure a [user-assigned managed identity][bring-your-own-control-plane-managed-identity] for the cluster. With a system-assigned managed identity, you can't retrieve the identity ID before creating a cluster, which causes a delay during role assignment.
 >
 > Both system-assigned and user-assigned managed identities are supported when you create and use your own VNet and route table with the Azure network plugin. We highly recommend using a user-assigned managed identity for BYO scenarios.
 
@@ -295,4 +295,4 @@ This article showed you how to deploy your AKS cluster into your existing virtua
 [custom-route-table]: ../virtual-network/manage-route-table.yml
 [network-comparisons]: concepts-network-cni-overview.md
 [Create an AKS cluster with user-assigned managed identity]: configure-kubenet.md#create-an-aks-cluster-with-user-assigned-managed-identity
-[bring-your-own-control-plane-managed-identity]: ../aks/use-managed-identity.md#bring-your-own-managed-identity
+[bring-your-own-control-plane-managed-identity]: ../aks/use-managed-identity.md#enable-a-user-assigned-managed-identity

articles/aks/create-nginx-ingress-private-controller.md

@@ -306,7 +306,7 @@ For other configuration information related to SSL encryption other advanced NGI
 [app-routing-crds]: https://aka.ms/aks/approuting/nginxingresscontrollercrd
 
 <!-- LINKS - internal -->
-[summary-msi]: use-managed-identity.md#summary-of-managed-identities
+[summary-msi]: use-managed-identity.md#summary-of-managed-identities-used-by-aks
 [rbac-owner]: ../role-based-access-control/built-in-roles.md#owner
 [rbac-classic]: ../role-based-access-control/rbac-and-directory-admin-roles.md#classic-subscription-administrator-roles
 [app-routing-add-on-basic-configuration]: app-routing.md

articles/aks/kubelogin-authentication.md

@@ -1,6 +1,9 @@
 ---
 title: Use kubelogin to authenticate in Azure Kubernetes Service
-description: Learn how to use the kubelogin plugin for all Microsoft Entra authentication methods in Azure Kubernetes Service (AKS). 
+description: Learn how to use the kubelogin plugin for all Microsoft Entra authentication methods in Azure Kubernetes Service (AKS).
+author: tamram
+
+ms.author: tamram
 ms.topic: article
 ms.subservice: aks-security
 ms.custom:

articles/aks/kubernetes-service-principal.md

@@ -1,11 +1,11 @@
 ---
-title: Use a service principal with Azure Kubernetes Services (AKS)
+title: Use a service principal with AKS
 description: Learn how to create and manage a Microsoft Entra service principal with a cluster in Azure Kubernetes Service (AKS).
 author: tamram
 
-ms.topic: conceptual
+ms.topic: article
 ms.subservice: aks-security
-ms.date: 06/27/2023
+ms.date: 05/30/2024
 ms.author: tamram
 ms.custom: devx-track-azurepowershell, devx-track-azurecli
 
@@ -14,16 +14,15 @@ ms.custom: devx-track-azurepowershell, devx-track-azurecli
 
 # Use a service principal with Azure Kubernetes Service (AKS)
 
-An AKS cluster requires either an [Microsoft Entra service principal][aad-service-principal] or a [managed identity][managed-identity-resources-overview] to dynamically create and manage other Azure resources, such as an Azure Load Balancer or Azure Container Registry (ACR).
+An AKS cluster requires either a [Microsoft Entra service principal][aad-service-principal] or a [managed identity][managed-identity-resources-overview] to dynamically create and manage other Azure resources, such as an Azure Load Balancer or Azure Container Registry (ACR).
 
-> [!NOTE]
-> We recommend using managed identities to authenticate with other resources in Azure, and they're the default authentication method for your AKS cluster. For more information about using a managed identity with your cluster, see [Use a system-assigned managed identity][use-managed-identity].
+For optimal security and ease of use, Microsoft recommends using managed identities rather than service principals to authorize access from an AKS cluster to other resources in Azure. A managed identity is a special type of service principal that can be used to obtain Microsoft Entra credentials without the need to manage and secure credentials. For more information about using a managed identity with your cluster, see [Use a managed identity in AKS][use-managed-identity].
 
-This article shows you how to create and use a service principal for your AKS clusters.
+This article shows you how to create and use a service principal with your AKS clusters.
 
 ## Before you begin
 
-To create a Microsoft Entra service principal, you must have permissions to register an application with your Microsoft Entra tenant and to assign the application to a role in your subscription. If you don't have the necessary permissions, you need to ask your Microsoft Entra ID or subscription administrator to assign the necessary permissions or pre-create a service principal for you to use with your AKS cluster.
+To create a Microsoft Entra service principal, you must have permissions to register an application with your Microsoft Entra tenant and to assign the application to a role in your subscription. If you don't have the necessary permissions, you need to ask your Microsoft Entra ID or subscription administrator to assign the necessary permissions or pre-create a service principal for use with your AKS cluster.
 
 If you're using a service principal from a different Microsoft Entra tenant, there are other considerations around the permissions available when you deploy the cluster. You may not have the appropriate permissions to read and write directory information. For more information, see [What are the default user permissions in Microsoft Entra ID?][azure-ad-permissions]
 
@@ -32,7 +31,9 @@ If you're using a service principal from a different Microsoft Entra tenant, the
 * If using Azure CLI, you need Azure CLI version 2.0.59 or later. Run `az --version` to find the version. If you need to install or upgrade, see [Install Azure CLI][install-azure-cli].
 * If using Azure PowerShell, you need Azure PowerShell version 5.0.0 or later. Run `Get-InstalledModule -Name Az` to find the version. If you need to install or upgrade, see [Install the Azure Az PowerShell module][install-the-azure-az-powershell-module].
 
-## Manually create a service principal
+## Create a service principal
+
+Create a service principal before you create your cluster.
 
 ### [Azure CLI](#tab/azure-cli)
 
@@ -126,33 +127,45 @@ If you're using a service principal from a different Microsoft Entra tenant, the
 
 ## Delegate access to other Azure resources
 
-You can use the service principal for the AKS cluster to access other resources. For example, if you want to deploy your AKS cluster into an existing Azure virtual network subnet or connect to Azure Container Registry (ACR), you need to delegate access to those resources to the service principal. Permission granted to a cluster using a system-assigned managed identity may take up 60 minutes to populate.
+You can use the service principal for the AKS cluster to access other resources. For example, if you want to deploy your AKS cluster into an existing Azure virtual network subnet, connect to Azure Container Registry (ACR), or access keys or secrets in a key vault from your cluster, then you need to delegate access to those resources to the service principal. To delegate access, assign an Azure role-based access control (Azure RBAC) role to the service principal.
+
+> [!IMPORTANT]
+> Permissions granted to a service principal associated with a cluster may take up 60 minutes to propagate.
 
 ### [Azure CLI](#tab/azure-cli)
 
-* Create a role assignment using the [`az role assignment create`][az-role-assignment-create] command. Assign the `appId` to a particular scope, such as a resource group or virtual network resource. The role defines what permissions the service principal has on the resource.
+* Create a role assignment using the [`az role assignment create`][az-role-assignment-create] command. Provide the value of the service principal's appID for the `appId` parameter. Specify the scope for the role assignment, such as a resource group or virtual network resource. The role assignment determines what permissions the service principal has on the resource and at what scope.
 
-    > [!NOTE]
-    > The `--scope` for a resource needs to be a full resource ID, such as */subscriptions/\<guid\>/resourceGroups/myResourceGroup* or */subscriptions/\<guid\>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet*.
+    For example, to assign the service principal permissions to access secrets in a key vault, you might use the following command:
 
     ```azurecli-interactive
-    az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor
+    az role assignment create \
+        --assignee <appId> \
+        --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
+        --role "Key Vault Secrets User"
     ```
 
+    > [!NOTE]
+    > The `--scope` for a resource needs to be a full resource ID, such as */subscriptions/\<guid\>/resourceGroups/myResourceGroup* or */subscriptions/\<guid\>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet*.
+
 ### [Azure PowerShell](#tab/azure-powershell)
 
-* Create a role assignment using the [`New-AzRoleAssignment`][new-azroleassignment] command. Assign the `ApplicationId` to a particular scope, such as a resource group or virtual network resource. The role defines what permissions the service principal has on the resource.
+* Create a role assignment using the [`New-AzRoleAssignment`][new-azroleassignment] command. Provide the value of the service principal's appID for the `ApplicationId` parameter. Specify the scope for the role assignment, such as a resource group or virtual network resource. The role assignment determines what permissions the service principal has on the resource and at what scope.
 
-    > [!NOTE]
-    > The `Scope` for a resource needs to be a full resource ID, such as */subscriptions/\<guid\>/resourceGroups/myResourceGroup* or */subscriptions/\<guid\>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet*
+    For example, to assign the service principal permissions to access secrets in a key vault, you might use the following command:
 
     ```azurepowershell-interactive
-    New-AzRoleAssignment -ApplicationId <ApplicationId> -Scope <resourceScope> -RoleDefinitionName Contributor
+    New-AzRoleAssignment -ApplicationId <ApplicationId> `
+        -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
+        -RoleDefinitionName "Key Vault Secrets User"
     ```
 
+    > [!NOTE]
+    > The `Scope` for a resource needs to be a full resource ID, such as */subscriptions/\<guid\>/resourceGroups/myResourceGroup* or */subscriptions/\<guid\>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/myVnet*
+
 ---
 
-The following sections detail common delegations that you may need to assign.
+The following sections detail common delegations that you may need to assign to a service principal.
 
 ### Azure Container Registry
 
@@ -196,7 +209,11 @@ When using AKS and a Microsoft Entra service principal, consider the following:
   * To delete the service principal, query for your cluster's *servicePrincipalProfile.clientId* and delete it using the [`az ad sp delete`][az-ad-sp-delete] command. Replace the values for the `-g` parameter for the resource group name and `-n` parameter for the cluster name:
 
       ```azurecli
-      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)
+      az ad sp delete --id $(az aks show \
+        --resource-group myResourceGroup \
+        --name myAKSCluster \
+        --query servicePrincipalProfile.clientId \
+        --output tsv)
       ```
 
 ### [Azure PowerShell](#tab/azure-powershell)
@@ -222,7 +239,7 @@ When using AKS and a Microsoft Entra service principal, consider the following:
 
 ### [Azure CLI](#tab/azure-cli)
 
-Azure CLI caches the service principal credentials for AKS clusters. If these credentials expire, you encounter errors during AKS cluster deployment. If you run the [`az aks create`][az-aks-create] command and receive an error message similar to the following, it may indicate a problem with the cached service principal credentials:
+Azure CLI caches the service principal credentials for AKS clusters. If these credentials expire, you can encounter errors during AKS cluster deployment. If you run the [`az aks create`][az-aks-create] command and receive an error message similar to the following, it may indicate a problem with the cached service principal credentials:
 
 ```azurecli
 Operation failed with status: 'Bad Request'.
@@ -233,7 +250,10 @@ Details: The credentials in ServicePrincipalProfile were invalid. Please see htt
 You can check the expiration date of your service principal credentials using the [`az ad app credential list`][az-ad-app-credential-list] command with the `"[].endDateTime"` query.
 
 ```azurecli
-az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv
+az ad app credential list \
+    --id <app-id> \
+    --query "[].endDateTime" \
+    --output tsv
 ```
 
 The default expiration time for the service principal credentials is one year. If your credentials are older than one year, you can [reset the existing credentials][reset-credentials] or [create a new service principal][new-service-principal].