Merge pull request #1167 from somtochiama/azure-docs

Update docs on Azure identity

Author: stefanprodan

docs/spec/v1beta2/buckets.md

@@ -439,8 +439,8 @@ data:
 
 ##### Workload Identity
 
-If you have [Workload Identity mutating webhook](https://azure.github.io/azure-workload-identity/docs/installation/managed-clusters.html)
-installed on your cluster. You need to create an Azure Identity and give it
+If you have [Workload Identity](https://azure.github.io/azure-workload-identity/docs/installation/managed-clusters.html)
+set up on your cluster, you need to create an Azure Identity and give it
 access to Azure Blob Storage.
 
 ```shell
@@ -465,7 +465,7 @@ az identity federated-credential create \
   --subject "system:serviceaccount:flux-system:source-controller"
 ```
 
-Add a patch to label and annotate the source-controller Pods and ServiceAccount
+Add a patch to label and annotate the source-controller Deployment and ServiceAccount
 correctly so that it can match an identity binding:
 
 ```yaml
@@ -501,7 +501,7 @@ patches:
 ```
 
 If you have set up Workload Identity correctly and labeled the source-controller
-Pod and ServiceAccount, then you don't need to reference a Secret. For more information,
+Deployment and ServiceAccount, then you don't need to reference a Secret. For more information,
 please see [documentation](https://azure.github.io/azure-workload-identity/docs/quick-start.html).
 
 ```yaml
@@ -517,7 +517,7 @@ spec:
   endpoint: https://testfluxsas.blob.core.windows.net
 ```
 
-##### Managed Identity with AAD Pod Identity
+##### Deprecated: Managed Identity with AAD Pod Identity
 
 If you are using [aad pod identity](https://azure.github.io/aad-pod-identity/docs),
 You need to create an Azure Identity and give it access to Azure Blob Storage.
@@ -561,7 +561,7 @@ spec:
   selector: ${IDENTITY_NAME}
 ```
 
-Label the source-controller correctly so that it can match an identity binding:
+Label the source-controller Deployment correctly so that it can match an identity binding:
 
 ```yaml
 apiVersion: apps/v1
@@ -577,7 +577,7 @@ spec:
 ```
 
 If you have set up aad-pod-identity correctly and labeled the source-controller
-Pod, then you don't need to reference a Secret.
+Deployment, then you don't need to reference a Secret.
 
 ```yaml
 apiVersion: source.toolkit.fluxcd.io/v1beta2

docs/spec/v1beta2/helmrepositories.md

@@ -224,15 +224,21 @@ to the IAM role when using IRSA.
 
 #### Azure
 
-The `azure` provider can be used to authenticate automatically using kubelet managed
-identity or Azure Active Directory pod-managed identity (aad-pod-identity), and 
+The `azure` provider can be used to authenticate automatically using Workload Identity, Kubelet Managed
+Identity or Azure Active Directory pod-managed identity (aad-pod-identity), and
 by extension gain access to ACR.
 
 ##### Kubelet Managed Identity
 
 When the kubelet managed identity has access to ACR, source-controller running on 
 it will also have access to ACR.
 
+**Note:** If you have more than one identity configured on the cluster, you have to specify which one to use
+by setting the `AZURE_CLIENT_ID` environment variable in the source-controller deployment.
+
+If you are running into further issues, please look at the
+[troubleshooting guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md#azure-virtual-machine-managed-identity).
+
 ##### Azure Workload Identity
 
 When using Workload Identity to enable access to ACR, add the following patch to
@@ -270,13 +276,17 @@ patches:
               azure.workload.identity/use: "true"
 ```
 
-To use Workload Identity, you have to install the Workload Identity
-mutating webhook and create an identity that has access to ACR. Next, establish
+Ensure Workload Identity is properly set up on your cluster and the mutating webhook is installed.
+Create an identity that has access to ACR. Next, establish
 a federated identity between the source-controller ServiceAccount and the
-identity. Patch the source-controller Pod and ServiceAccount as shown in the patch
+identity. Patch the source-controller Deployment and ServiceAccount as shown in the patch
 above. Please take a look at this [guide](https://azure.github.io/azure-workload-identity/docs/quick-start.html#6-establish-federated-identity-credential-between-the-identity-and-the-service-account-issuer--subject).
 
-##### AAD Pod Identity
+##### Deprecated: AAD Pod Identity
+
+**Warning:** The AAD Pod Identity project will be archived in
+[September 2023](https://github.com/Azure/aad-pod-identity#-announcement),
+and you are advised to use Workload Identity instead.
 
 When using aad-pod-identity to enable access to ACR, add the following patch to
 your bootstrap repository, in the `flux-system/kustomization.yaml` file:
@@ -302,7 +312,7 @@ to give the `source-controller` pod access to the ACR. To do this, you have to i
 `aad-pod-identity` on your cluster, create a managed identity that has access to the
 container registry (this can also be the Kubelet identity if it has `AcrPull` role
 assignment on the ACR), create an `AzureIdentity` and `AzureIdentityBinding` that describe
-the managed identity and then label the `source-controller` pods with the name of the
+the managed identity and then label the `source-controller` deployment with the name of the
 AzureIdentity as shown in the patch above. Please take a look at [this guide](https://azure.github.io/aad-pod-identity/docs/)
 or [this one](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity)
 if you want to use AKS pod-managed identities add-on that is in preview.

docs/spec/v1beta2/ocirepositories.md

@@ -157,15 +157,21 @@ to the IAM role when using IRSA.
 
 #### Azure
 
-The `azure` provider can be used to authenticate automatically using kubelet
-managed identity or Azure Active Directory pod-managed identity (aad-pod-identity),
+The `azure` provider can be used to authenticate automatically using Workload Identity, Kubelet Managed
+Identity or Azure Active Directory pod-managed identity (aad-pod-identity),
 and by extension gain access to ACR.
 
 ##### Kubelet Managed Identity
 
 When the kubelet managed identity has access to ACR, source-controller running
 on it will also have access to ACR.
 
+**Note:** If you have more than one identity configured on the cluster, you have to specify which one to use
+by setting the `AZURE_CLIENT_ID` environment variable in the source-controller deployment.
+
+If you are running into further issues, please look at the
+[troubleshooting guide](https://github.com/Azure/azure-sdk-for-go/blob/main/sdk/azidentity/TROUBLESHOOTING.md#azure-virtual-machine-managed-identity).
+
 ##### Workload Identity
 
 When using Workload Identity to enable access to ACR, add the following patch to
@@ -203,13 +209,17 @@ patches:
               azure.workload.identity/use: "true"
 ```
 
-To use Workload Identity, you have to install the Workload Identity
-mutating webhook and create an identity that has access to ACR. Next, establish 
-a federated identity between the source-controller ServiceAccount and the 
-identity. Patch the source-controller Pod and ServiceAccount as shown in the patch
+Ensure Workload Identity is properly set up on your cluster and the mutating webhook is installed.
+Create an identity that has access to ACR. Next, establish
+a federated identity between the source-controller ServiceAccount and the
+identity. Patch the source-controller Deployment and ServiceAccount as shown in the patch
 above. Please take a look at this [guide](https://azure.github.io/azure-workload-identity/docs/quick-start.html#6-establish-federated-identity-credential-between-the-identity-and-the-service-account-issuer--subject).
 
-##### AAD Pod Identity
+##### Deprecated: AAD Pod Identity
+
+**Note:** The AAD Pod Identity project will be archived in [September 2023](https://github.com/Azure/aad-pod-identity#-announcement),
+and you are advised to use Workload Identity instead.
+
 When using aad-pod-identity to enable access to ACR, add the following patch to
 your bootstrap repository, in the `flux-system/kustomization.yaml` file:
 
@@ -234,7 +244,7 @@ has to be used to give the `source-controller` pod access to the ACR.
 To do this, you have to install `aad-pod-identity` on your cluster, create a managed identity
 that has access to the container registry (this can also be the Kubelet identity
 if it has `AcrPull` role assignment on the ACR), create an `AzureIdentity` and `AzureIdentityBinding`
-that describe the managed identity and then label the `source-controller` pods
+that describe the managed identity and then label the `source-controller` deployment
 with the name of the AzureIdentity as shown in the patch above. Please take a look
 at [this guide](https://azure.github.io/aad-pod-identity/docs/) or
 [this one](https://docs.microsoft.com/en-us/azure/aks/use-azure-ad-pod-identity)