Merge pull request #210558 from MGoedtel/draft-release-ignite-2022-aks-workload-identity

Initial drafts of Workload Identity

Author: Court72

articles/aks/TOC.yml

@@ -62,6 +62,10 @@
       href: tutorial-kubernetes-app-update.md
     - name: 7 - Upgrade cluster
       href: tutorial-kubernetes-upgrade-cluster.md
+    - name: Security
+      items:
+        - name: Configure application to use workload identity
+          href: learn/tutorial-kubernetes-workload-identity.md
 - name: Concepts
   items:
     - name: Core concepts
@@ -314,6 +318,14 @@
               href: enable-fips-nodes.md
         - name: Application security
           items:
+            - name: Workload identity (preview)
+              items:
+                - name: Overview
+                  href: workload-identity-overview.md
+                - name: Deploy and configure cluster
+                  href: workload-identity-deploy-cluster.md
+                - name: Modernize your app with workload identity sidecar
+                  href: workload-identity-migration-sidecar.md
             - name: Use Azure AD pod identity (preview)
               href: use-azure-ad-pod-identity.md
             - name: Secure pod traffic with network policies

articles/aks/cluster-configuration.md

@@ -3,20 +3,20 @@ title: Cluster extensions for Azure Kubernetes Service (AKS)
 description: Learn how to deploy and manage the lifecycle of extensions on Azure Kubernetes Service (AKS)
 ms.service: container-service
 ms.custom: event-tier1-build-2022
-ms.date: 05/13/2022
+ms.date: 09/29/2022
 ms.topic: article
 author: nickomang
 ms.author: nickoman
 ---
 
 # Deploy and manage cluster extensions for Azure Kubernetes Service (AKS)
 
-Cluster extensions provides an Azure Resource Manager driven experience for installation and lifecycle management of services like Azure Machine Learning (ML) on an AKS cluster. This feature enables:
+Cluster extensions provide an Azure Resource Manager driven experience for installation and lifecycle management of services like Azure Machine Learning (ML) on an AKS cluster. This feature enables:
 
 * Azure Resource Manager-based deployment of extensions, including at-scale deployments across AKS clusters.
 * Lifecycle management of the extension (Update, Delete) from Azure Resource Manager.
 
-In this article, you will learn about:
+In this article, you'll learn about:
 > [!div class="checklist"]
 
 > * How to create an extension instance.
@@ -36,24 +36,18 @@ A conceptual overview of this feature is available in [Cluster extensions - Azur
 * [Azure CLI](/cli/azure/install-azure-cli) version >= 2.16.0 installed.
 
 > [!NOTE]
-> If you have enabled [AAD-based pod identity][use-azure-ad-pod-identity] on your AKS cluster, please add the following `AzurePodIdentityException` to the release namespace of your extension instance on the AKS cluster:
-> ```yml
-> apiVersion: aadpodidentity.k8s.io/v1
-> kind: AzurePodIdentityException
-> metadata:
->  name: k8s-extension-exception
->  namespace: <release-namespace-of-extension>
-> spec:
->  podLabels:
->    clusterconfig.azure.com/managedby: k8s-extension
-> ```
-
-### Setup the Azure CLI extension for cluster extensions
+> If you have enabled [AAD-based pod identity][use-azure-ad-pod-identity] on your AKS cluster or are considering implementing it,
+> we recommend you first review [Migrate to workload identity][migrate-workload-identity] to understand our
+> recommendations and options to set up your cluster to use an Azure AD workload identity (preview).
+> This authentication method replaces pod-managed identity (preview), which integrates with the Kubernetes native capabilities
+> to federate with any external identity providers.
+
+### Set up the Azure CLI extension for cluster extensions
 
 > [!NOTE]
 > The minimum supported version for the `k8s-extension` Azure CLI extension is `1.0.0`. If you are unsure what version you have installed, run `az extension show --name k8s-extension` and look for the `version` field.
 
-You will also need the `k8s-extension` Azure CLI extension. Install this by running the following commands:
+You'll also need the `k8s-extension` Azure CLI extension. Install the extension by running the following command:
 
 ```azurecli-interactive
 az extension add --name k8s-extension
@@ -96,7 +90,7 @@ az k8s-extension create --name aml-compute --extension-type Microsoft.AzureML.Ku
 ```
 
 > [!NOTE]
-> The Cluster Extensions service is unable to retain sensitive information for more than 48 hours. If the cluster extension agents don't have network connectivity for more than 48 hours and cannot determine whether to create an extension on the cluster, then the extension transitions to `Failed` state. Once in `Failed` state, you will need to run `k8s-extension create` again to create a fresh extension instance.
+> The Cluster Extensions service is unable to retain sensitive information for more than 48 hours. If the cluster extension agents don't have network connectivity for more than 48 hours and can't determine whether to create an extension on the cluster, then the extension transitions to `Failed` state. Once in `Failed` state, you will need to run `k8s-extension create` again to create a fresh extension instance.
 
 #### Required parameters
 
@@ -112,15 +106,15 @@ az k8s-extension create --name aml-compute --extension-type Microsoft.AzureML.Ku
 
 | Parameter name | Description |
 |--------------|------------|
-| `--auto-upgrade-minor-version` | Boolean property that specifies if the extension minor version will be upgraded automatically or not. Default: `true`.  If this parameter is set to true, you cannot set `version` parameter, as the version will be dynamically updated. If set to `false`, extension will not be auto-upgraded even for patch versions. |
+| `--auto-upgrade-minor-version` | Boolean property that specifies if the extension minor version will be upgraded automatically or not. Default: `true`.  If this parameter is set to true, you can't set `version` parameter, as the version will be dynamically updated. If set to `false`, extension won't be auto-upgraded even for patch versions. |
 | `--version` | Version of the extension to be installed (specific version to pin the extension instance to). Must not be supplied if auto-upgrade-minor-version is set to `true`. |
-| `--configuration-settings` | Settings that can be passed into the extension to control its functionality. They are to be passed in as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-settings-file` can't be used in the same command. |
+| `--configuration-settings` | Settings that can be passed into the extension to control its functionality. Pass values as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-settings-file` can't be used in the same command. |
 | `--configuration-settings-file` | Path to the JSON file having key value pairs to be used for passing in configuration settings to the extension. If this parameter is used in the command, then `--configuration-settings` can't be used in the same command. |
-| `--configuration-protected-settings` | These settings are not retrievable using `GET` API calls or `az k8s-extension show` commands, and are thus used to pass in sensitive settings. They are to be passed in as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-protected-settings-file` can't be used in the same command. |
+| `--configuration-protected-settings` | These settings are not retrievable using `GET` API calls or `az k8s-extension show` commands, and are thus used to pass in sensitive settings. Pass values as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-protected-settings-file` can't be used in the same command. |
 | `--configuration-protected-settings-file` | Path to the JSON file having key value pairs to be used for passing in sensitive settings to the extension. If this parameter is used in the command, then `--configuration-protected-settings` can't be used in the same command. |
 | `--scope` | Scope of installation for the extension - `cluster` or `namespace` |
 | `--release-namespace` | This parameter indicates the namespace within which the release is to be created. This parameter is only relevant if `scope` parameter is set to `cluster`. |
-| `--release-train` |  Extension  authors can publish versions in different release trains such as `Stable`, `Preview`, etc. If this parameter is not set explicitly, `Stable` is used as default. This parameter can't be used when `autoUpgradeMinorVersion` parameter is set to `false`. |
+| `--release-train` |  Extension  authors can publish versions in different release trains such as `Stable`, `Preview`, etc. If this parameter isn't set explicitly, `Stable` is used as default. This parameter can't be used when `autoUpgradeMinorVersion` parameter is set to `false`. |
 | `--target-namespace` | This parameter indicates the namespace within which the release will be created. Permission of the system account created for this extension instance will be restricted to this namespace. This parameter is only relevant if the `scope` parameter is set to `namespace`. |
 
 ### Show details of an extension instance
@@ -155,7 +149,7 @@ az k8s-extension update --name azureml --extension-type Microsoft.AzureML.Kubern
 | Parameter name | Description |
 |----------------|------------|
 | `--name` | Name of the extension instance |
-| `--extension-type` | The type of extension you want to install on the cluster. For example: Microsoft.AzureML.Kubernetes | 
+| `--extension-type` | The type of extension you want to install on the cluster. For example: Microsoft.AzureML.Kubernetes |
 | `--cluster-name` | Name of the AKS cluster on which the extension instance has to be created |
 | `--resource-group` | The resource group containing the AKS cluster |
 | `--cluster-type` | The cluster type on which the extension instance has to be created. Specify `managedClusters` as it maps to AKS clusters|
@@ -164,14 +158,14 @@ az k8s-extension update --name azureml --extension-type Microsoft.AzureML.Kubern
 
 | Parameter name | Description |
 |--------------|------------|
-| `--auto-upgrade-minor-version` | Boolean property that specifies if the extension minor version will be upgraded automatically or not. Default: `true`.  If this parameter is set to true, you cannot set `version` parameter, as the version will be dynamically updated. If set to `false`, extension will not be auto-upgraded even for patch versions. |
+| `--auto-upgrade-minor-version` | Boolean property that specifies if the extension minor version will be upgraded automatically or not. Default: `true`.  If this parameter is set to true, you cannot set `version` parameter, as the version will be dynamically updated. If set to `false`, extension won't be auto-upgraded even for patch versions. |
 | `--version` | Version of the extension to be installed (specific version to pin the extension instance to). Must not be supplied if auto-upgrade-minor-version is set to `true`. |
-| `--configuration-settings` | Settings that can be passed into the extension to control its functionality. Only the settings that require an update need to be provided. The provided settings would be replaced with the provided values. They are to be passed in as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-settings-file` can't be used in the same command. |
+| `--configuration-settings` | Settings that can be passed into the extension to control its functionality. Only the settings that require an update need to be provided. The provided settings would be replaced with the provided values. Pass values as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-settings-file` can't be used in the same command. |
 | `--configuration-settings-file` | Path to the JSON file having key value pairs to be used for passing in configuration settings to the extension. If this parameter is used in the command, then `--configuration-settings` can't be used in the same command. |
-| `--configuration-protected-settings` | These settings are not retrievable using `GET` API calls or `az k8s-extension show` commands, and are thus used to pass in sensitive settings. When updating a setting, all settings are expected to be provided. If some settings are omitted, those settings would be considered obsolete and deleted. They are to be passed in as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-protected-settings-file` can't be used in the same command. |
+| `--configuration-protected-settings` | These settings are not retrievable using `GET` API calls or `az k8s-extension show` commands, and are thus used to pass in sensitive settings. When you update a setting, all settings are expected to be specified. If some settings are omitted, those settings would be considered obsolete and deleted. Pass values as space separated `key=value` pairs after the parameter name. If this parameter is used in the command, then `--configuration-protected-settings-file` can't be used in the same command. |
 | `--configuration-protected-settings-file` | Path to the JSON file having key value pairs to be used for passing in sensitive settings to the extension. If this parameter is used in the command, then `--configuration-protected-settings` can't be used in the same command. |
 | `--scope` | Scope of installation for the extension - `cluster` or `namespace` |
-| `--release-train` |  Extension  authors can publish versions in different release trains such as `Stable`, `Preview`, etc. If this parameter is not set explicitly, `Stable` is used as default. This parameter can't be used when `autoUpgradeMinorVersion` parameter is set to `false`. |
+| `--release-train` |  Extension  authors can publish versions in different release trains such as `Stable`, `Preview`, etc. If this parameter isn't set explicitly, `Stable` is used as default. This parameter can't be used when `autoUpgradeMinorVersion` parameter is set to `false`. |
 
 ### Delete extension instance
 
@@ -194,8 +188,8 @@ az k8s-extension delete --name azureml --cluster-name <clusterName> --resource-g
 [dapr-overview]: ./dapr.md
 [gitops-overview]: ../azure-arc/kubernetes/conceptual-gitops-flux2.md
 [k8s-extension-reference]: /cli/azure/k8s-extension
-[use-azure-ad-pod-identity]: ./use-azure-ad-pod-identity.md
 [use-managed-identity]: ./use-managed-identity.md
+[migrate-workload-identity]: workload-identity-overview.md
 
 <!-- EXTERNAL -->
 [arc-k8s-regions]: https://azure.microsoft.com/global-infrastructure/services/?products=azure-arc&regions=all

articles/aks/cluster-extensions.md

@@ -3,17 +3,18 @@ title: Concepts - Access and identity in Azure Kubernetes Services (AKS)
 description: Learn about access and identity in Azure Kubernetes Service (AKS), including Azure Active Directory integration, Kubernetes role-based access control (Kubernetes RBAC), and roles and bindings.
 services: container-service
 ms.topic: conceptual
-ms.date: 03/24/2021
+ms.date: 09/27/2022
 author: palma21
 ms.author: jpalma
 
 ---
 
 # Access and identity options for Azure Kubernetes Service (AKS)
 
-You can authenticate, authorize, secure, and control access to Kubernetes clusters in a variety of ways. 
-* Using Kubernetes role-based access control (Kubernetes RBAC), you can grant users, groups, and service accounts access to only the resources they need. 
-* With Azure Kubernetes Service (AKS), you can further enhance the security and permissions structure via Azure Active Directory and Azure RBAC. 
+You can authenticate, authorize, secure, and control access to Kubernetes clusters in a variety of ways:
+
+* Using Kubernetes role-based access control (Kubernetes RBAC), you can grant users, groups, and service accounts access to only the resources they need.
+* With Azure Kubernetes Service (AKS), you can further enhance the security and permissions structure using Azure Active Directory and Azure RBAC.
 
 Kubernetes RBAC and AKS help you secure your cluster access and provide only the minimum required permissions to developers and operators.
 
@@ -22,6 +23,7 @@ This article introduces the core concepts that help you authenticate and assign
 ## Kubernetes RBAC
 
 Kubernetes RBAC provides granular filtering of user actions. With this control mechanism:
+
 * You assign users or user groups permission to create and modify resources or view logs from running application workloads. 
 * You can scope permissions to a single namespace or across the entire AKS cluster. 
 * You create *roles* to define permissions, and then assign those roles to users with *role bindings*.
@@ -31,7 +33,8 @@ For more information, see [Using Kubernetes RBAC authorization][kubernetes-rbac]
 ### Roles and ClusterRoles
 
 #### Roles
-Before assigning permissions to users with Kubernetes RBAC, you'll define user permissions as a *Role*. Grant permissions within a namespace using roles. 
+
+Before assigning permissions to users with Kubernetes RBAC, you'll define user permissions as a *Role*. Grant permissions within a namespace using roles.
 
 > [!NOTE]
 > Kubernetes roles *grant* permissions; they don't *deny* permissions.
@@ -82,7 +85,8 @@ With Azure RBAC, you create a *role definition* that outlines the permissions to
 
 For more information, see [What is Azure role-based access control (Azure RBAC)?][azure-rbac]
 
-There are two levels of access needed to fully operate an AKS cluster: 
+There are two levels of access needed to fully operate an AKS cluster:
+
 * [Access the AKS resource in your Azure subscription](#azure-rbac-to-authorize-access-to-the-aks-resource). 
   * Control scaling or upgrading your cluster using the AKS APIs.
   * Pull your `kubeconfig`.
@@ -227,19 +231,22 @@ By default Node Access is not required for AKS.  The following access is needed
 
 | Access | Reason |
 |---|---|
-| `kubelet` | Required for customer to grant MSI access to ACR. |
+| `kubelet` | Required to grant MSI access to ACR. |
 | `http app routing` | Required for write permission to "random name".aksapp.io. |
-| `container insights` | Required for customer to grant permission to the Log Analytics workspace. |
+| `container insights` | Required to grant permission to the Log Analytics workspace. |
 
 ## Summary
 
 View the table for a quick summary of how users can authenticate to Kubernetes when Azure AD integration is enabled. In all cases, the user's sequence of commands is:
+
 1. Run `az login` to authenticate to Azure.
 1. Run `az aks get-credentials` to download credentials for the cluster into `.kube/config`.
-1. Run `kubectl` commands. 
+1. Run `kubectl` commands.
+
    * The first command may trigger browser-based authentication to authenticate to the cluster, as described in the following table.
 
 In the Azure portal, you can find:
+
 * The *Role Grant* (Azure RBAC role grant) referred to in the second column is shown on the **Access Control** tab. 
 * The Cluster Admin Azure AD Group is shown on the **Configuration** tab.
   * Also found with parameter name `--aad-admin-group-object-ids` in the Azure CLI.