Add note for declarative API

Author: RichardChen820

articles/azure-app-configuration/media/quickstarts/kubernetes-provider-get-provider-status.png

@@ -11,17 +11,18 @@ ms.date: 04/06/2023
 ms.author: junbchen
 #Customer intent: As an Azure Kubernetes Service user, I want to manage all my app settings in one place using Azure App Configuration.
 ---
+
 # Quickstart: Use Azure App Configuration in Azure Kubernetes Service (preview)
-In Kubernetes, you set up pods to consume ConfigMaps for configuration. It lets you decouple configuration from your container images, making your applications easily portable. [Azure App Configuration Kubernetes Provider](https://mcr.microsoft.com/product/azure-app-configuration/kubernetes-provider/about) can construct ConfigMaps based on your data in Azure App Configuration. It enables you to take advantage of Azure App Configuration for the centralized storage and management of your configuration without any changes to your application code.
+
+In Kubernetes, you set up pods to consume configuration from ConfigMaps. It lets you decouple configuration from your container images, making your applications easily portable. [Azure App Configuration Kubernetes Provider](https://mcr.microsoft.com/product/azure-app-configuration/kubernetes-provider/about) can construct ConfigMaps and Secrets from your key-values and Key Vault references in Azure App Configuration. It enables you to take advantage of Azure App Configuration for the centralized storage and management of your configuration without any changes to your application code.
 
 In this quickstart, you incorporate Azure App Configuration Kubernetes Provider in an Azure Kubernetes Service workload where you run a simple ASP.NET Core app consuming configuration from environment variables.
 
 ## Prerequisites
 
-* An Azure account with an active subscription. [Create one for free](https://azure.microsoft.com/free/).
 * An App Configuration store. [Create a store](./quickstart-azure-app-configuration-create.md#create-an-app-configuration-store).
-* An Azure Container Registry. [Create a registry](/azure/aks/tutorial-kubernetes-prepare-acr?tabs=azure-cli#create-an-azure-container-registry).
-* An Azure Kubernetes Service (AKS) cluster that integrates with the Azure Container Registry you created. [Create an AKS cluster](/azure/aks/tutorial-kubernetes-deploy-cluster?tabs=azure-cli#create-a-kubernetes-cluster).
+* An Azure Container Registry. [Create a registry](/azure/aks/tutorial-kubernetes-prepare-acr#create-an-azure-container-registry).
+* An Azure Kubernetes Service (AKS) cluster that integrates with the Azure Container Registry you created. [Create an AKS cluster](/azure/aks/tutorial-kubernetes-deploy-cluster#create-a-kubernetes-cluster).
 * [.NET Core SDK](https://dotnet.microsoft.com/download)
 * [Azure CLI](/cli/azure/install-azure-cli)
 * [helm](https://helm.sh/docs/intro/install/)
@@ -32,17 +33,20 @@ In this quickstart, you incorporate Azure App Configuration Kubernetes Provider
 >
 
 ## Create an application running in AKS
+
 In this section, it creates an ASP.NET Core web application that consumes environment variables as configuration and run it in Azure Kubernetes Service. This section has nothing to do with Azure App Configuration or Azure App Configuration Kubernetes Provider, it just for demonstrating the end-to-end usage scenario of Azure App Configuration Kubernetes Provider later. If you already have an application that is consuming environment variables in Kubernetes, you can just skip this section and go to [Use App Configuration Kubernetes Provider](#use-app-configuration-kubernetes-provider). 
+
 ### Create an application
-1. Use the .NET Core command-line interface (CLI) and run the following command to create a new ASP.NET Core web app project in a new MyWebApp folder:
+
+1. Use the .NET Core command-line interface (CLI) and run the following command to create a new ASP.NET Core web app project in a new MyWebApp directory:
 
-    ``` dotnetcli
+    ```dotnetcli
     dotnet new webapp --output MyWebApp --framework net6.0
     ```
 
 1. Open *Index.cshtml* in the Pages directory, and update the content with the following code.
    
-    ``` html
+    ```html
     @page
     @model IndexModel
     @using Microsoft.Extensions.Configuration
@@ -63,15 +67,16 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
     ```
 
 ### Containerize the application 
+
 1. Run the [dotnet publish](/dotnet/core/tools/dotnet-publish) command to build the app in release mode and create the assets in the published folder.
    
-    ``` dotnetcli
+    ```dotnetcli
     dotnet publish -c Release -o published
     ```
 
 1. Create a file named *Dockerfile* in the directory containing your .csproj file, open it in a text editor, and enter the following content. A Dockerfile is a text file that doesn't have an extension and that is used to create a container image.
 
-    ``` dockerfile
+    ```dockerfile
     FROM mcr.microsoft.com/dotnet/aspnet:6.0 AS runtime
     WORKDIR /app
     COPY published/ ./
@@ -80,12 +85,13 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
 
 1. Build a container image named *aspnetapp* by running the following command.
 
-   ``` docker
+   ```docker
    docker build --tag aspnetapp .
    ```
 
 ### Push the image to Azure Container Registry
-1. Run the [az acr login](/cli/azure/acr#az-acr-login) command to login your container registry. The following example login a registry named *myregistry*. Replace the registry name with yours.
+
+1. Run the [az acr login](/cli/azure/acr#az-acr-login) command to login your container registry. The following example logs into a registry named *myregistry*. Replace the registry name with yours.
 
     ```azurecli
     az acr login --name myregistry
@@ -108,12 +114,13 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
     docker push myregistry.azurecr.io/aspnetapp:v1
     ```
 
-### Deploy and visit the application
+### Deploy the application
+
 1.  Create an *AKS-AppConfiguration-Demo* directory in the root directory of your project.
 
-1. Add a *deployment.yaml* to the *AKS-AppConfiguration-Demo* directory with the following content to create a deployment. Replace the value of `template.spec.containers.image` with the image you created in the previous step.
+1. Add a *deployment.yaml* file to the *AKS-AppConfiguration-Demo* directory with the following content to create a deployment. Replace the value of `template.spec.containers.image` with the image you created in the previous step.
 
-    ``` yaml
+    ```yaml
     apiVersion: apps/v1
     kind: Deployment
     metadata:
@@ -142,9 +149,9 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
               value: "Black"
     ```
 
-1. Add a *service.yaml* to the *AKS-AppConfiguration-Demo* directory with the following content to create a LoadBalancer service. 
+1. Add a *service.yaml* file to the *AKS-AppConfiguration-Demo* directory with the following content to create a LoadBalancer service. 
  
-    ``` yaml
+    ```yaml
     apiVersion: v1
     kind: Service
     metadata:
@@ -159,14 +166,14 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
 
 1. Run the following command to deploy the application to the AKS cluster.
 
-    ``` bash
+    ```console
     kubectl create namespace appconfig-demo
     kubectl apply -f ./AKS-AppConfiguration-Demo -n appconfig-demo
     ```
 
-1. Run the following command and get the External IP that exposed by the LoadBalancer service.
+1. Run the following command and get the External IP address exposed by the LoadBalancer service.
    
-    ``` bash
+    ```console
     kubectl get service configmap-demo-service -n appconfig-demo
     ```
 
@@ -175,8 +182,11 @@ In this section, it creates an ASP.NET Core web application that consumes enviro
     ![Kubernetes Provider before using configMap ](./media/quickstarts/kubernetes-provider-app-launch-before.png)
 
 ## Use App Configuration Kubernetes Provider
+
 Now that you have an application running in AKS, you'll deploy the App Configuration Kubernetes Provider to your AKS cluster running as a Kubernetes controller. The provider retrieves data from your App Configuration store and creates a ConfigMap, which is consumable as environment variables by your application.
+
 ### Setup the Azure App Configuration store
+
 1. Add following key-values to the App Configuration store and leave **Label** and **Content Type** with their default values. For more information about how to add key-values to a store using the Azure portal or the CLI, go to [Create a key-value](./quickstart-azure-app-configuration-create.md#create-a-key-value).
 
     |**Key**|**Value**|
@@ -186,7 +196,7 @@ Now that you have an application running in AKS, you'll deploy the App Configura
     
 1. [Enabling the system-assigned managed identity on the Virtual Machine Scale Sets of your AKS cluster](/azure/active-directory/managed-identities-azure-resources/qs-configure-portal-windows-vmss#enable-system-assigned-managed-identity-on-an-existing-virtual-machine-scale-set). This allows the App Configuration Kubernetes Provider to use the managed identity to connect to your App Configuration store.
 
-1. Grant read access to your App Configuration store by [assigning the managed identity the App Configuration Data Reader role](/azure/azure-app-configuration/howto-integrate-azure-managed-service-identity?tabs=core5x&pivots=framework-dotnet#grant-access-to-app-configuration).
+1. Grant read access to your App Configuration store by [assigning the managed identity the App Configuration Data Reader role](/azure/azure-app-configuration/howto-integrate-azure-managed-service-identity#grant-access-to-app-configuration).
 
 ### Install App Configuration Kubernetes Provider to AKS cluster
 1. Run the following command to get access credentials for your AKS cluster. Replace the value of the `name` and `resource-group` parameters with your AKS instance:
@@ -197,76 +207,96 @@ Now that you have an application running in AKS, you'll deploy the App Configura
 
 1. Install Azure App Configuration Kubernetes Provider to your AKS cluster using `helm`:
    
-    ``` bash
+    ```console
     helm install azureappconfiguration.kubernetesprovider \
          oci://mcr.microsoft.com/azure-app-configuration/helmchart/kubernetes-provider \
          --version 1.0.0-preview \
          --namespace azappconfig-system \
          --create-namespace
     ```
 
-1. Add an *appConfigurationProvider.yaml* file to the *AKS-AppConfiguration-Demo* directory with the following content to create an `AzureAppConfigurationProvider` resource. `AzureAppConfigurationProvider` is a custom resource that defines how to retrieve key-values from an Azure App Configuration store.
+1. Add an *appConfigurationProvider.yaml* file to the *AKS-AppConfiguration-Demo* directory with the following content to create an `AzureAppConfigurationProvider` resource. `AzureAppConfigurationProvider` is a custom resource that defines how to retrieve key-values from an Azure App Configuration store and create a configMap.
 
     Replace the value of the `endpoint` field with the endpoint of your Azure App Configuration store.
    
-    ``` yaml
+    ```yaml
     apiVersion: azconfig.io/v1beta1
     kind: AzureAppConfigurationProvider
     metadata:
       name: appconfigurationprovider-sample
     spec:
       endpoint: <your-app-configuration-store-endpoint>
       target:
-        configMapName: demo-configmap
+        configMapName: configmap-created-by-appconfig-provider
     ```
-
-2. Update the *deployment.yaml* in *AKS-AppConfiguration-Demo* directory to use the configMap `demo-configmap` as environment variable.
+    
+    > [!NOTE]
+    > `AzureAppConfigurationProvider` is a declarative API, it defines the desired state of the configMap that retrieves the key-values from the App Configuration store with following behavior:
+    >
+    > - The provider creates a configMap according to the definition of an `AzureAppConfigurationProvider`.
+    > - The provider doesn't update a configMap that is not created by the provider.
+    > - The provider keeps the data of configMap as a mirror of key-values from Azure App Configuration. Any changes to the configMap through other approaches will be reverted.
+    > - Deleting provider will delete the corresponding configMap along with it. If the configMap is deleted solely, the provider will recreate it.
+
+1. Update the *deployment.yaml* in *AKS-AppConfiguration-Demo* directory to use the configMap `configmap-created-by-appconfig-provider` as environment variable.
    
     Replace the whole `env` section 
-    ``` yaml
+    ```yaml
     env:
     - name: Settings__Message
       value: "Message from the local configuration"
     - name: Settings__FontColor
       value: "Black"
     ```
     with
-    ``` yaml
+    ```yaml
     envFrom:
     - configMapRef:
-        name: demo-configmap
+        name: configmap-created-by-appconfig-provider
     ```
 
-3. Run the following command to deploy the `AzureAppConfigurationProvider` resource.
+1. Run the following command to deploy the `AzureAppConfigurationProvider` resource.
    
-    ``` bash
+    ```console
     kubectl apply -f ./AKS-AppConfiguration-Demo -n appconfig-demo
     ```
 
-4. Refresh the browser. The page shows updated content.
+1. Refresh the browser. The page shows updated content.
 
     ![Kubernetes Provider after using configMap](./media/quickstarts/kubernetes-provider-app-launch-after.png)
 
 ### Troubleshooting
+
 If you don't see your application picking up the data from your App Configuration store, run the following command to validate that the ConfigMap is created properly.
 
-``` bash
-kubectl get configmap demo-configmap -n appconfig-demo
+```console
+kubectl get configmap configmap-created-by-appconfig-provider -n appconfig-demo
 ```
 
 If the ConfigMap is not created properly, run the following command to get the data retrieval status.
 
-``` bash
+```console
 kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml
 ```
 
 If the Azure App Configuration Kubernetes Provider retrieved data from your App Configuration store successfully, the `phase` property under the status section of the output should be `COMPLETE`, as shown in the following example.
 
-![Kubernetes Provider get provider status](./media/quickstarts/kubernetes-provider-get-provider-status.png)
+```console
+$ kubectl get AzureAppConfigurationProvider appconfigurationprovider-sample -n appconfig-demo -o yaml
+
+apiVersion: azconfig.io/v1beta1
+kind: AzureAppConfigurationProvider
+  ... ... ...
+status:
+  lastReconcileTime: "2023-04-06T06:17:06Z"
+  lastSyncTime: "2023-04-06T06:17:06Z"
+  message: Complete sync settings to ConfigMap or Secret
+  phase: COMPLETE
+```
 
 If the phase is not `COMPLETE`, the data isn't downloaded from your App Configuration store properly. Run the following command to show the logs of the Azure App Configuration Kubernetes Provider.
 
-``` bash    
+```console    
 kubectl logs deployment/az-appconfig-k8s-provider -n azappconfig-system
 ```   
 
@@ -278,22 +308,22 @@ Use the logs for further troubleshooting. For example, if you see requests to yo
 
 Remove the resources that have been deployed to AKS.
 
-``` bash
+```console
 kubectl delete -f ./AKS-AppConfiguration-Demo -n appconfig-demo
 kubectl delete namespace appconfig-demo
 ```
 
 Follow the steps below to uninstall the Azure App Configuration Kubernetes Provider from your AKS cluster.
 
-``` bash
+```console
 helm uninstall azureappconfiguration.kubernetesprovider --namespace azappconfig-system
 ```
 
 ## Summary
 
 In this quickstart, you:
 
-* Provisioned a new App Configuration store.
-* Connected to your App Configuration store in Kubernetes using the App Configuration Kubernetes Provider controller.
-* Download your App Configuration store's key-values to a ConfigMap.
-* Displayed a web page in Kubernetes using the settings you configured in your App Configuration store.
+* Created an application running in Azure Kubernetes Service (AKS).
+* Connected your AKS cluster to your App Configuration store using the App Configuration Kubernetes Provider.
+* Created a ConfigMap with data from your App Configuration store.
+* Ran the application with configuration from your App Configuration store without changing your application code.