Update for feedback

RichardChen820 · RichardChen820 · commit 521671280e4d · 2024-09-03T16:52:03.000+08:00
diff --git a/articles/azure-app-configuration/quickstart-azure-kubernetes-service.md b/articles/azure-app-configuration/quickstart-azure-kubernetes-service.md
@@ -241,10 +241,34 @@ Add following key-values to the App Configuration store and leave **Label** and
          --namespace azappconfig-system \
          --create-namespace
     ```
-
+    
     > [!TIP]
     > The App Configuration Kubernetes Provider is also available as an AKS extension. This integration allows for seamless installation and management via the Azure CLI, ARM templates, or Bicep templates. Utilizing the AKS extension facilitates automatic minor/patch version updates, ensuring your system is always up-to-date. For detailed installation instructions, please refer to the [Azure App Configuration extension for Azure Kubernetes Service](/azure/aks/azure-app-configuration).
 
+1. Follow the step 1-4 in [using workload identity](./reference-kubernetes-provider.md#use-workload-identity) and note down the client ID, tenant ID, resource group and name of the managed identity, the OIDC issuer URL of the AKS cluster, you will use them in the following steps.
+
+1. Add a *serviceaccount.yaml* file to the *Deployment* directory with the following content to create a service account for the application.
+
+    ```yaml
+    apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+      name: aspnetapp-demo-service-account
+      annotations:
+        azure.workload.identity/client-id: <your-managed-identity-client-id>
+        azure.workload.identity/tenant-id: <your-tenant-id>
+    ```
+
+    Replace the value of the `azure.workload.identity/client-id` and `azure.workload.identity/tenant-id` fields with the client ID and tenant ID of the managed identity you created in the previous step.
+
+1. Create federated credentials for the service account by running the following command:
+   
+    ```azurecli
+     az identity federated-credential create --name "federated-credential-demo" --identity-name <identity-name> --resource-group  <resource-group> --issuer <OIDC-issuer> --subject system:serviceaccount:default:aspnetapp-demo-service-account --audience api://AzureADTokenExchange
+    ```
+
+    Replace the value of the `identity-name`, `resource-group` fields with the name, resource group of your managed identity created in the previous step. Replace the value of the `OIDC-issuer` field with the OIDC issuer URL of your AKS cluster. 
+
 1. Add an *appConfigurationProvider.yaml* file to the *Deployment* directory with the following content to create an `AzureAppConfigurationProvider` resource. `AzureAppConfigurationProvider` is a custom resource that defines what data to download from an Azure App Configuration store and creates a ConfigMap.
    
     ```yaml
@@ -261,10 +285,10 @@ Add following key-values to the App Configuration store and leave **Label** and
           key: mysettings.json
       auth:
         workloadIdentity:
-          managedIdentityClientId: <your-managed-identity-client-id>
+          serviceAccountName: aspnetapp-demo-service-account
     ```
 
-    Replace the value of the `endpoint` field with the endpoint of your Azure App Configuration store. Follow the steps in [use workload identity](./reference-kubernetes-provider.md#use-workload-identity) and update the `auth` section with the client ID of the user-assigned managed identity you created.
+    Replace the value of the `endpoint` field with the endpoint of your Azure App Configuration store. 
     
     > [!NOTE]
     > `AzureAppConfigurationProvider` is a declarative API object. It defines the desired state of the ConfigMap created from the data in your App Configuration store with the following behavior:
@@ -370,6 +394,10 @@ Ensure that you specify the correct key-value selectors to match the expected da
 
 You can customize the installation by providing additional Helm values when installing the Azure App Configuration Kubernetes Provider. For example, you can set the log level, configure the provider to run on a specific node, or disable the workload identity. Refer to the [installation guide](./reference-kubernetes-provider.md#installation) for more information.
 
+#### Why the workload identity does not work after I upgrade the Azure App Configuration Kubernetes Provider to v2.0.0?
+
+Start from v2.0.0, per namespace service account should be used for workload identity by default. See the [workload identity](./reference-kubernetes-provider.md#use-workload-identity) documentation for more details. If you still want to use the provider's service account, binding your managed identities to the global service account `az-appconfig-k8s-provider` that been created in `azappconfig-system` namespace, you can enable it by setting `workloadIdentity.globalServiceAccountEnabled=true` at installation time, refer to the [installation guide](./reference-kubernetes-provider.md#installation) for more information.
+
 ## Clean up resources
 
 Uninstall the App Configuration Kubernetes Provider from your AKS cluster if you want to keep the AKS cluster.
diff --git a/articles/azure-app-configuration/reference-kubernetes-provider.md b/articles/azure-app-configuration/reference-kubernetes-provider.md
@@ -12,7 +12,7 @@ ms.author: junbchen
 
 # Azure App Configuration Kubernetes Provider reference
 
-The following reference outlines the properties supported by the Azure App Configuration Kubernetes Provider `v1.3.0`. See [release notes](https://github.com/Azure/AppConfiguration/blob/main/releaseNotes/KubernetesProvider.md) for more information on the change.
+The following reference outlines the properties supported by the Azure App Configuration Kubernetes Provider `v2.0.0`. See [release notes](https://github.com/Azure/AppConfiguration/blob/main/releaseNotes/KubernetesProvider.md) for more information on the change.
 
 ## Properties
 
@@ -162,7 +162,7 @@ The `spec.featureFlag.refresh` property has the following child properties.
 ## Installation
 
 Use the following `helm install` command to install the Azure App Configuration Kubernetes Provider. See [helm-values.yaml](https://github.com/Azure/AppConfiguration-KubernetesProvider/blob/main/deploy/parameter/helm-values.yaml) for the complete list of parameters and their default values. You can override the default values by passing the `--set` flag to the command.
- 
+
 ```bash
 helm install azureappconfiguration.kubernetesprovider \
     oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
@@ -174,6 +174,30 @@ helm install azureappconfiguration.kubernetesprovider \
 
 By default, autoscaling is disabled. However, if you have multiple `AzureAppConfigurationProvider` resources to produce multiple ConfigMaps/Secrets, you can enable horizontal pod autoscaling by setting `autoscaling.enabled` to `true`.
 
+```bash
+helm install azureappconfiguration.kubernetesprovider \
+    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
+    --namespace azappconfig-system \
+    --create-namespace
+    --set autoscaling.enabled=true
+```
+
+### Global service account
+
+By default, the provider uses custom per namespace service account to access Azure App Configuration and Key Vaults. If you still want to use the provider's service account, binding your managed identities to the global service account `az-appconfig-k8s-provider` that been created in `azappconfig-system` namespace, you can enable it by setting `workloadIdentity.globalServiceAccountEnabled=true` at installation time.
+
+```bash
+helm install azureappconfiguration.kubernetesprovider \
+    oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
+    --namespace azappconfig-system \
+    --create-namespace
+    --set workloadIdentity.globalServiceAccountEnabled=true
+```
+
+### Data collection
+
+The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry by setting the `requestTracing.enabled=false` while installing the Azure App Configuration Kubernetes Provider. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.
+
 ## Examples
 
 ### Authentication
@@ -251,36 +275,55 @@ By default, autoscaling is disabled. However, if you have multiple `AzureAppConf
 
 3. [Create a user-assigned managed identity](/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities#create-a-user-assigned-managed-identity) and note down its client ID after creation.
   
-4. [Grant the user-assigned managed identity **App Configuration Data Reader** role](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vmss#user-assigned-managed-identity) in Azure App Configuration.
+4. [Grant the user-assigned managed identity **App Configuration Data Reader** role](/azure/azure-app-configuration/concept-enable-rbac#assign-azure-roles-for-access-rights) in Azure App Configuration.
 
-5. Create the federated identity credential between the managed identity, OIDC issuer, and subject using the Azure CLI. You can choose to bind the managed identity to the provider global service account or a custom service account.
-
-    ##### [Use service account of provider](#tab/global)
-
-    ``` azurecli
-    az identity federated-credential create --name "${FEDERATED_IDENTITY_CREDENTIAL_NAME}" --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --issuer "${AKS_OIDC_ISSUER}" --subject system:serviceaccount:azappconfig-system:az-appconfig-k8s-provider --audience api://AzureADTokenExchange
-    ```
+5. Create federated identity credential between the managed identity, OIDC issuer, and subject using the Azure CLI. You can choose to bind the managed identity to the provider global service account or a custom service account.
 
     ##### [Use custom service account](#tab/custom)
 
     Create a custom service account in the same namespace as the `AzureAppConfigurationProvider` resource.
 
-    ``` console
-    kubectl create serviceaccount my-service-account -n default
+    ``` bash
+    cat <<EOF | kubectl create -f -
+    apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+      name: my-service-account
+      annotations:
+        azure.workload.identity/client-id: <managed-identity-client-id>
+        azure.workload.identity/tenant-id: <tenant-id>
+    EOF
     ```
 
     Create the federated identity credential to bind the managed identity to the custom service account.
 
     ``` azurecli
     az identity federated-credential create --name "${FEDERATED_IDENTITY_CREDENTIAL_NAME}" --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --issuer "${AKS_OIDC_ISSUER}" --subject system:serviceaccount:default:my-service-account --audience api://AzureADTokenExchange
+    ```
+
+    The subject of the federated identity credential should be in the format `system:serviceaccount:<service-account-namespace>:<service-account-name>`.
+
+    ##### [Use service account of provider](#tab/global)
+
+    > [!NOTE]
+    > To use the service account of the provider, please ensure the `workloadIdentity.enableGlobalServiceAccount` property is set to `true` while installing the Azure App Configuration Kubernetes Provider.
+    > ```bash
+    > helm install azureappconfiguration.kubernetesprovider \
+    >     oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
+    >     --namespace azappconfig-system \
+    >     --create-namespace \
+    >     --set workloadIdentity.enableGlobalServiceAccount=true
+    > ```
 
+    ``` azurecli
+    az identity federated-credential create --name "${FEDERATED_IDENTITY_CREDENTIAL_NAME}" --identity-name "${USER_ASSIGNED_IDENTITY_NAME}" --resource-group "${RESOURCE_GROUP}" --issuer "${AKS_OIDC_ISSUER}" --subject system:serviceaccount:azappconfig-system:az-appconfig-k8s-provider --audience api://AzureADTokenExchange
     ```
 
     ---
 
 6. Apply the following sample `AzureAppConfigurationProvider` resource to the Kubernetes cluster.
    
-    ##### [Use service account of provider](#tab/global)
+    ##### [Use custom service account](#tab/custom)
 
     ``` yaml
     apiVersion: azconfig.io/v1
@@ -293,10 +336,10 @@ By default, autoscaling is disabled. However, if you have multiple `AzureAppConf
         configMapName: configmap-created-by-appconfig-provider
       auth:
         workloadIdentity:
-          managedIdentityClientId: <your-managed-identity-client-id>
+          serviceAccountName: my-service-account
     ```
 
-    ##### [Use custom service account](#tab/custom)
+    ##### [Use service account of provider](#tab/global)
 
     ``` yaml
     apiVersion: azconfig.io/v1
@@ -309,7 +352,7 @@ By default, autoscaling is disabled. However, if you have multiple `AzureAppConf
         configMapName: configmap-created-by-appconfig-provider
       auth:
         workloadIdentity:
-          serviceAccountName: my-service-account
+          managedIdentityClientId: <your-managed-identity-client-id>
     ```
 
     ---
