Merge pull request #110599 from zr-msft/ds-aad-pod-id-troubleshooting

[Dev Spaces] Added callout for aad-pod-id

Author: PRMerger20

articles/dev-spaces/faq.md

@@ -74,7 +74,7 @@ When using Visual Studio to prepare your project, you have the option of enablin
 
 ## Can I use pod managed identities with Azure Dev Spaces?
 
-Currently, Azure Dev Spaces does not support using [pod managed identities][aks-pod-managed-id] on AKS clusters with Azure Dev Spaces enabled. If you have pod managed identities installed and would like to uninstall it, you can find more details in the [uninstall notes][aks-pod-managed-id-uninstall].
+Yes, you can use [pod managed identities][aks-pod-managed-id] on AKS clusters with Azure Dev Spaces enabled, but there are [additional configuration steps][dev-spaces-pod-managed-id-steps] after you enable Azure Dev Spaces on your cluster with pod managed identities. If you have pod managed identities installed and would like to uninstall it, you can find more details in the [uninstall notes][aks-pod-managed-id-uninstall].
 
 ## Can I use Azure Dev Spaces with multiple microservices in an application?
 
@@ -93,6 +93,7 @@ In Visual Studio, it is possible to configure .NET Core solutions for debugging
 [aks-pod-managed-id-uninstall]: https://github.com/Azure/aad-pod-identity#uninstall-notes
 [aks-restrict-egress-traffic]: ../aks/limit-egress-traffic.md
 [bike-sharing]: https://github.com/Azure/dev-spaces/tree/master/samples/BikeSharingApp
+[dev-spaces-pod-managed-id-steps]: troubleshooting.md#error-no-azureassignedidentity-found-for-podazdsazds-webhook-deployment-id-in-assigned-state
 [dev-spaces-prep]: how-dev-spaces-works-prep.md
 [dev-spaces-routing]: how-dev-spaces-works-routing.md#how-routing-works
 [ingress-nginx]: how-to/ingress-https-nginx.md#configure-a-custom-nginx-ingress-controller

articles/dev-spaces/troubleshooting.md

@@ -34,7 +34,7 @@ You can also try deleting the controller:
 azds remove -g <resource group name> -n <cluster name>
 ```
 
-Use the Azure Dev Spaces CLI to delete a controller. It’s not possible to delete a controller from Visual Studio. You also can't install the Azure Dev Spaces CLI in the Azure Cloud Shell so you can't delete a controller from the Azure Cloud Shell.
+Use the Azure Dev Spaces CLI to delete a controller. It's not possible to delete a controller from Visual Studio. You also can't install the Azure Dev Spaces CLI in the Azure Cloud Shell so you can't delete a controller from the Azure Cloud Shell.
 
 If you don't have the Azure Dev Spaces CLI installed, you can first install it using the following command then delete your controller:
 
@@ -89,7 +89,7 @@ To fix this issue, update your installation of the [Azure CLI](/cli/azure/instal
 
 ### Error "Unable to reach kube-apiserver"
 
-You might see this error when Azure Dev Spaces is unable to connect to your AKS cluster's API server. 
+You might see this error when Azure Dev Spaces is unable to connect to your AKS cluster's API server.
 
 If access to your AKS cluster API server is locked down or if you have [API server authorized IP address ranges](../aks/api-server-authorized-ip-ranges.md) enabled for your AKS cluster, you must also [create](../aks/api-server-authorized-ip-ranges.md#create-an-aks-cluster-with-api-server-authorized-ip-ranges-enabled) or [update](../aks/api-server-authorized-ip-ranges.md#update-a-clusters-api-server-authorized-ip-ranges) your cluster to [allow additional ranges based on your region](https://github.com/Azure/dev-spaces/tree/master/public-ips).
 
@@ -266,6 +266,113 @@ For example, to stop and disable the *Windows BranchCache* service:
 * Optionally, you can disable it by setting *Startup type* to *Disabled*.
 * Click *OK*.
 
+### Error "no AzureAssignedIdentity found for pod:azds/azds-webhook-deployment-\<id\> in assigned state"
+
+When running a service with Azure Dev Spaces on an AKS cluster with a [managed identity](../aks/use-managed-identity.md) and [pod managed identities](../aks/developer-best-practices-pod-security.md#use-pod-managed-identities) installed, the process may hang after the *chart install* step. If you inspect the *azds-injector-webhook* in the *azds* name space, you may see this error.
+
+The services Azure Dev Spaces runs on your cluster utilize the cluster's managed identity to talk to the Azure Dev Spaces backend services outside the cluster. When the pod managed identity is installed, networking rules are configured on your cluster's nodes to redirect all calls for managed identity credentials to a [Node Managed Identity (NMI) DaemonSet installed on the cluster](https://github.com/Azure/aad-pod-identity#node-managed-identity). This NMI DaemonSet identifies the calling pod and ensures that pod has been labeled appropriately to access the requested managed identity. Azure Dev Spaces can't detect if a cluster has pod managed identity installed and can't perform the necessary configuration to allow Azure Dev Spaces services to access the cluster's managed identity. Since the Azure Dev Spaces services haven't been configured to access the cluster's managed identity, the NMI DaemonSet will not allow them to obtain an AAD token for the managed identity and fail to communicate with Azure Dev Spaces backend services.
+
+To fix this issue, apply an [AzurePodIdentityException](https://github.com/Azure/aad-pod-identity/blob/master/docs/readmes/README.app-exception.md) for the *azds-injector-webhook* and update pods instrumented by Azure Dev Spaces to access the managed identity.
+
+Create a file named *webhookException.yaml* and copy the following YAML definition:
+
+```yaml
+apiVersion: "aadpodidentity.k8s.io/v1"
+kind: AzurePodIdentityException
+metadata:
+  name: azds-infrastructure-exception
+  namespace: azds
+spec:
+  PodLabels:
+    azds.io/uses-cluster-identity: "true"
+```
+
+The above file creates a *AzurePodIdentityException* object for the *azds-injector-webhook*. To deploy this object, use `kubectl`:
+
+```cmd
+kubectl apply -f webhookException.yaml
+```
+
+To update pods instrumented by Azure Dev Spaces to access the managed identity, update the *namespace* in the below YAML definition and use `kubectl` to apply it for each dev space.
+
+```yaml
+apiVersion: "aadpodidentity.k8s.io/v1"
+kind: AzurePodIdentityException
+metadata:
+  name: azds-infrastructure-exception
+  namespace: myNamespace
+spec:
+  PodLabels:
+    azds.io/instrumented: "true"
+```
+
+Alternatively, you can create *AzureIdentity* and *AzureIdentityBinding* objects and update the pod labels for workloads running in spaces instrumented by Azure Dev Spaces to access the managed identity created by the AKS cluster.
+
+To list the details of the managed identity, run the following command for your AKS cluster:
+
+```azurecli
+az aks show -g <resourcegroup> -n <cluster> -o json --query "{clientId: identityProfile.kubeletidentity.clientId, resourceId: identityProfile.kubeletidentity.resourceId}"
+```
+
+The above command outputs the *clientId* and *resourceId* for the managed identity. For example:
+
+```json
+{
+  "clientId": "<clientId>",
+  "resourceId": "/subscriptions/<subid>/resourcegroups/<resourcegroup>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>"
+}
+```
+
+To create an *AzureIdentity* object, create a file named *clusteridentity.yaml* and use the following YAML definition updated with the details of your managed identity from the previous command:
+
+```yaml
+apiVersion: "aadpodidentity.k8s.io/v1"
+kind: AzureIdentity
+metadata:
+  name: my-cluster-mi
+spec:
+  type: 0
+  ResourceID: /subscriptions/<subid>/resourcegroups/<resourcegroup>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>
+  ClientID: <clientId>
+```
+
+To create an *AzureIdentityBinding* object, create a file named *clusteridentitybinding.yaml* and use the following YAML definition:
+
+```yaml
+apiVersion: "aadpodidentity.k8s.io/v1"
+kind: AzureIdentityBinding
+metadata:
+  name: my-cluster-mi-binding
+spec:
+  AzureIdentity: my-cluster-mi
+  Selector: my-label-value
+```
+
+To deploy the *AzureIdentity* and *AzureIdentityBinding* objects, use `kubectl`:
+
+```cmd
+kubectl apply -f clusteridentity.yaml
+kubectl apply -f clusteridentitybinding.yaml
+```
+
+After you deploy the *AzureIdentity* and *AzureIdentityBinding* objects, any workload with the *aadpodidbinding: my-label-value* label can access the cluster's managed identity. Add this label and redeploy all workloads running in any dev space. For example:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: sample
+spec:
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: sample
+        aadpodidbinding: my-label-value
+    spec:
+      [...]
+```
+
 ## Common issues using Visual Studio and Visual Studio Code with Azure Dev Spaces
 
 ### Error "Required tools and configurations are missing"