Merge pull request #268571 from jiec-msft/mason/show-acs-configs

Add doc to check configuration files pulled by ACS

Author: Stacyrch140

articles/spring-apps/enterprise/how-to-enterprise-application-configuration-service.md

@@ -6,7 +6,7 @@ author: KarlErickson
 ms.author: xiading
 ms.service: spring-apps
 ms.topic: how-to
-ms.date: 02/28/2024
+ms.date: 03/27/2024
 ms.custom: devx-track-java, devx-track-extended-java, engagement-fy23, devx-track-azurecli
 ---
 
@@ -65,13 +65,13 @@ The **Refresh Interval** specifies the frequency (in seconds) for checking updat
 
 The following table describes the properties for each repository entry:
 
-| Property      | Required? | Description                                                                                                                                                                                                                                                                                                                                  |
-|---------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `Name`        | Yes       | A unique name to label each Git repository.                                                                                                                                                                                                                                                                                                  |
-| `Patterns`    | Yes       | Patterns to search in Git repositories. For each pattern, use a format such as *{application}* or *{application}/{profile}* rather than *{application}-{profile}.yml*. Separate the patterns with commas. For more information, see the [Pattern](./how-to-enterprise-application-configuration-service.md#pattern) section of this article. |
-| `URI`         | Yes       | A Git URI (for example, `https://github.com/Azure-Samples/piggymetrics-config` or `[email protected]:Azure-Samples/piggymetrics-config`)                                                                                                                                                                                                        |
-| `Label`       | Yes       | The branch name to search in the Git repository.                                                                                                                                                                                                                                                                                             |
-| `Search path` | No        | Optional search paths, separated by commas, for searching subdirectories of the Git repository.                                                                                                                                                                                                                                              |
+| Property      | Required? | Description                                                                                                                                                                                                                                                                                  |
+|---------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `Name`        | Yes       | A unique name to label each Git repository.                                                                                                                                                                                                                                                  |
+| `Patterns`    | Yes       | The patterns to search for in Git repositories. For each pattern, use a format such as *{application}* or *{application}/{profile}* rather than *{application}-{profile}.yml*. Separate the patterns with commas. For more information, see the [Pattern](#pattern) section of this article. |
+| `URI`         | Yes       | A Git URI (for example, `https://github.com/Azure-Samples/piggymetrics-config` or `[email protected]:Azure-Samples/piggymetrics-config`)                                                                                                                                                        |
+| `Label`       | Yes       | The branch name to search for in the Git repository.                                                                                                                                                                                                                                         |
+| `Search path` | No        | Optional search paths, separated by commas, for searching subdirectories of the Git repository.                                                                                                                                                                                              |
 
 ### Pattern
 
@@ -155,7 +155,7 @@ The Application Configuration Service also supports polyglot apps like dotNET, G
 When you modify and commit your configurations in a Git repository, several steps are involved before these changes are reflected in your applications. This process, though automated, involves the following distinct stages and components, each with its own timing and behavior:
 
 - Polling by Application Configuration Service: The Application Configuration Service regularly polls the backend Git repositories to detect any changes. This polling occurs at a set frequency, defined by the refresh interval. When a change is detected, Application Configuration Service updates the Kubernetes `ConfigMap`.
-- ConfigMap update and interaction with kubelet cache: In Azure Spring Apps, this `ConfigMap` is mounted as a data volume to the relevant application. However, there's a natural delay in this process due to the frequency at which the kubelet refreshes its cache to recognize changes in `ConfigMap`.
+- `ConfigMap` update and interaction with kubelet cache: In Azure Spring Apps, this `ConfigMap` is mounted as a data volume to the relevant application. However, there's a natural delay in this process due to the frequency at which the kubelet refreshes its cache to recognize changes in `ConfigMap`.
 - Application reads updated configuration: Your application running in the Azure Spring Apps environment can access the updated configuration values. The existing beans in the Spring Context aren't automatically refreshed to use the updated configurations.
 
 These stages are summarized in the following diagram:
@@ -375,6 +375,88 @@ az spring application-configuration-service delete \
 
 ---
 
+## Examine configuration file in ConfigMap
+
+The following section shows you how to examine the content of the configuration file pulled by Application Configuration Service from upstream Git repositories in the related Kubernetes `ConfigMap`. For more information, see the [Refresh strategies](#refresh-strategies) section of this article.
+
+### Assign an Azure role
+
+First, you must have the Azure role `Azure Spring Apps Application Configuration Service Config File Pattern Reader Role` assigned to you.
+
+#### [Azure portal](#tab/azure-Portal)
+
+Use the following steps to assign an Azure role:
+
+1. Open the [Azure portal](https://portal.azure.com) and go to your Azure Spring Apps service instance.
+
+1. In the navigation pane, select **Access Control (IAM)**.
+
+1. On the **Access Control (IAM)** page, select **Add**, and then select **Add role assignment**.
+
+   :::image type="content" source="media/how-to-enterprise-application-configuration-service/add-role-assignment.png" alt-text="Screenshot of the Azure portal that shows the Access Control (IAM) page for an Azure Spring Apps instance with the Add role assignment option highlighted." lightbox="media/how-to-enterprise-application-configuration-service/add-role-assignment.png":::
+
+1. On the **Add role assignment** page, in the **Name** list, search for and select the target role, and then select **Next**.
+
+   :::image type="content" source="media/how-to-enterprise-application-configuration-service\application-configuration-service-config-pattern-file-reader-role.png" alt-text="Screenshot of the Azure portal that shows the Add role assignment page for an Azure Spring Apps instance with the Azure Spring Apps Application Configuration Service Config File Pattern Reader Role name highlighted." lightbox="media/how-to-enterprise-application-configuration-service\application-configuration-service-config-pattern-file-reader-role.png":::
+
+1. Select **Members** and then search for and select your username.
+
+1. Select **Review + assign**.
+
+#### [Azure CLI](#tab/azure-CLI)
+
+Use the following command to assign an Azure role:
+
+```azurecli
+az role assignment create \
+    --role "Azure Spring Apps Application Configuration Service Config File Pattern Reader Role" \
+    --scope "<service-instance-resource-id>" \
+    --assignee "<your-identity>"
+```
+
+---
+
+### Examine configuration file with Azure CLI
+
+Use the following command to view the content of the configuration file by [Pattern](#pattern):
+
+```azurecli
+az spring application-configuration-service config show \
+    --resource-group <resource-group-name> \
+    --service <Azure-Spring-Apps-instance-name> \
+    --config-file-pattern <pattern>
+```
+
+This command produces JSON output similar to the following example:
+
+```json
+{
+  "configurationFiles": {
+    "application.properties": [
+      "example.property.application.name: example-service",
+      "example.property.cloud: Azure"
+    ]
+  }
+}
+```
+
+You can also use this command with the `--export-path {/path/to/target/folder}` parameter to export the configuration file to the specified folder. It supports both relative paths and absolute paths. If you don't specify the path, the command uses the path of the current directory by default.
+
+## Examine configuration file in the app
+
+After you bind the app to the Application Configuration Service and set the [Pattern](#pattern) for the app deployment, as described in the [Use Application Configuration Service with applications](#use-application-configuration-service-with-applications) section of this article, the `ConfigMap` containing the configuration file for the pattern should be mounted to the application container. Use the following steps to check the configuration files in each instance of the app deployment:
+
+1. Connect to one of the application instances. For more information, see [Connect to an app instance for troubleshooting](./how-to-connect-to-app-instance-for-troubleshooting.md).
+
+1. Use the `echo $AZURE_SPRING_APPS_CONFIG_FILE_PATH` command to find the folders containing the configuration files. A list of locations shows up separated by commas, as shown in the following example:
+
+   ```output
+     $ echo $AZURE_SPRING_APPS_CONFIG_FILE_PATH
+     /etc/azure-spring-cloud/configmap/acs-default-payment-default-e9d46,/etc/azure-spring-cloud/configmap/acs-default-catalog-default-616f4
+   ```
+
+1. Check the content of the configuration file using commands such as `cat`.
+
 ## Check logs
 
 The following sections show you how to view application logs by using either the Azure CLI or the Azure portal.
@@ -470,8 +552,8 @@ If the latest changes aren't reflected in the applications, check the following
   - Confirm that the branch of the desired config file changes is updated.
   - Confirm that the pattern configured in the Application Configuration Service matches the updated config files.
   - Confirm that the application is bound to the Application Configuration Service.
-- Confirm that the `ConfigMap` of the app is updated. If it isn't updated, raise a ticket.
-- Confirm that the `ConfigMap` is mounted to the application as a file by using `web shell`. If the file isn't updated, wait for the Kubernetes refresh interval (1 minute), or force a refresh by restarting the application.
+- Confirm that the `ConfigMap` containing the configuration file for the [Pattern](#pattern) used by the application is updated, as described in the [Examine configuration file in ConfigMap](#examine-configuration-file-in-configmap) section of this article. If it isn't updated, raise a ticket.
+- Confirm that the `ConfigMap` is mounted to the application as a file, as described in the [Examine configuration file in the app](#examine-configuration-file-in-the-app) section of this article. If the file isn't updated, wait for the Kubernetes refresh interval (1 minute), or force a refresh by restarting the application.
 
 After checking these items, the applications should be able to read the updated configurations. If the applications still aren't updated, raise a ticket.