chore(docs): Add more documentation

Author: irby

docs/ambient-providers/azure.md

@@ -22,6 +22,16 @@ Since you are using ambient credentials generated by your Azure AKS workload and
 
 While system-assigned managed identity (MSI) is easy to use and enabled by default, user-assigned managed identity (UAMI) is the ***recommended identity type*** to use for your workload. UAMI identities can be shared with other AKS clusters and workloads, and offer more control over how the identity is used. If your app registration [requires a role assignment](#app-registration-assignment-requirement), you **must** use a UAMI. An MSI **cannot** be assigned to an app registration role.
 
+### Quick Decision Guide
+
+| Scenario | Recommended Identity Type |
+|----------|-------------------------|
+| Simple setup, single cluster | System-Assigned (MSI) |
+| Multiple clusters need same identity | User-Assigned (UAMI) |
+| App registration requires role assignment | User-Assigned (UAMI) - **Required** |
+| Production environments | User-Assigned (UAMI) |
+| Development/testing | Either (MSI for simplicity) |
+
 
 ## System-Assigned Managed Identity (MSI)
 
@@ -222,6 +232,12 @@ For more information about the assignment requirement for app registrations and
 
 This troubleshooting section is intended for issues specific to the Azure AKS environment. If you do not see your issue in these troubleshooting steps, please see the troubleshooting steps in the [directory root](../../README.md#troubleshooting).
 
+### Common Pitfalls
+
+1. **Forgetting the `/.default` suffix** in scopes configuration
+1. **Using wrong object ID** - If using MSI, MSI uses kubelet identity, not the cluster identity
+1. **ServiceAccount mismatch** - If using UAMI, federated credentials must exactly match ServiceAccount name/namespace
+
 ### Determining Which Managed Identity Your AKS Workload is Using
 
 Azure has documentation around [determining the managed identity a cluster is using](https://learn.microsoft.com/en-us/azure/aks/use-managed-identity#determine-which-type-of-managed-identity-a-cluster-is-using), but this section will confirm if your AKS workload is using UAMI or MSI for its managed identity.
@@ -278,6 +294,10 @@ NAME                              READY   STATUS    RESTARTS   AGE    LABELS
 command-issuer-86c4fdfb67-h4vqb   1/1     Running   0          105s   app.kubernetes.io/instance=cert-manager-issuer,app.kubernetes.io/name=command-cert-manager-issuer,azure.workload.identity/use=true,pod-template-hash=86c4fdfb67
 ```
 
+#### Conclusion
+
+If all of the above steps indicate your cluster has workload identity enabled, the pod is labeled to use workload identity, and the ServiceAccount is annotated with the UAMI client ID, your workload is most likely using **user-assigned managed identity**.
+
 ### Required Query Variable 'Resource' Is Missing
 
 If you see the following error, this indicates your issuer / cluster issuer is missing a `scopes` field in its spec. DefaultAzureCredentials requires a valid scope, which should reference the [app registration](#azure-app-registration).