Tutorial: Use dynamic configuration using push refresh in a Java Spring app

  • Article

The App Configuration Java Spring client library supports updating configuration on demand without causing an application to restart. An application can be configured to detect changes in App Configuration using one or both of the following two approaches.

  • Poll Model: This is the default behavior that uses polling to detect changes in configuration. Once the cached value of a setting expires, the next call to AppConfigurationRefresh's refreshConfigurations sends a request to the server to check if the configuration has changed, and pulls the updated configuration if needed.

  • Push Model: This uses App Configuration events to detect changes in configuration. Once App Configuration is set up to send key value change events with Event Grid, with a Web Hook, the application can use these events to optimize the total number of requests needed to keep the configuration updated.

This tutorial shows how you can implement dynamic configuration updates in your code using push refresh. It builds on the app introduced in the quickstarts. Before you continue, finish Create a Java Spring app with App Configuration first.

You can use any code editor to do the steps in this tutorial. Visual Studio Code is an excellent option that's available on the Windows, macOS, and Linux platforms.

In this tutorial, you learn how to:

  • Set up a subscription to send configuration change events from App Configuration to a Web Hook
  • Deploy a Spring Boot application to App Service
  • Set up your Java Spring app to update its configuration in response to changes in App Configuration.
  • Consume the latest configuration in your application.

Prerequisites

If you don't have an Azure subscription, create an Azure free account before you begin.

Setup Push Refresh

  1. Open pom.xml and update the file with the following dependencies.

    <dependency>
    <groupId>com.azure.spring</groupId>
    <artifactId>spring-cloud-azure-appconfiguration-config-web</artifactId>
</dependency>

<!-- Adds the Ability to Push Refresh -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

<dependencyManagement>
    <dependencies>
        <dependency>
        <groupId>com.azure.spring</groupId>
        <artifactId>spring-cloud-azure-dependencies</artifactId>
        <version>5.8.0</version>
        <type>pom</type>
        <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

  2. Set up Maven App Service Deployment so the application can be deployed to Azure App Service via Maven.

    mvn com.microsoft.azure:azure-webapp-maven-plugin:2.5.0:config

  3. Open bootstrap.properties and configure Azure App Configuration Push Refresh.

    # Azure App Configuration Properties
spring.cloud.azure.appconfiguration.stores[0].connection-string= ${AppConfigurationConnectionString}
spring.cloud.azure.appconfiguration.stores[0].monitoring.enabled= true
spring.cloud.azure.appconfiguration.stores[0].monitoring.refresh-interval= 30d
spring.cloud.azure.appconfiguration.stores[0].monitoring.triggers[0].key= sentinel
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.name= myToken
spring.cloud.azure.appconfiguration.stores[0].monitoring.push-notification.primary-token.secret= myTokenSecret

management.endpoints.web.exposure.include= appconfiguration-refresh

A random delay is added before the cached value is marked as dirty to reduce potential throttling. The default maximum delay before the cached value is marked as dirty is 30 seconds.

Note

The Primary token name should be stored in App Configuration as a key, and then the Primary token secret should be stores as an App Configuration Key Vault Reference for added security.

Build and run the app in app service

Event Grid Web Hooks require validation on creation. You can validate by following this guide or by starting your application with Azure App Configuration Spring Web Library already configured, which will register your application for you. To use an event subscription, follow the steps in the next two sections.

  1. Set the environment variable to your App Configuration instance's connection string:

    setx AppConfigurationConnectionString <connection-string-of-your-app-configuration-store>

  2. Update your pom.xml under the azure-webapp-maven-plugin's configuration add

    <appSettings>
  <AppConfigurationConnectionString>${AppConfigurationConnectionString}</AppConfigurationConnectionString>
</appSettings>

  3. Run the following command to build the console app:

     mvn package

  4. After the build successfully completes, run the following command to run the app locally:

    mvn azure-webapp:deploy

Set up an event subscription

  1. Open the App Configuration resource in the Azure portal, then select + Event Subscription in the Events pane.

    The events pane has an option to create new Subscriptions.

  2. Enter a name for the Event Subscription and the System Topic. By default the Event Types Key-Value modified and Key-Value deleted are set, this can be changed along with using the Filters tab to choose the exact reasons a Push Event will be sent.

    Events require a name, topic, and filters.

  3. Select the Endpoint Type as Web Hook, select Select an endpoint.

    Selecting Endpoint creates a new blade to enter the endpoint URI.

  4. The endpoint is the URI of the application + "/actuator/appconfiguration-refresh?{your-token-name}={your-token-secret}". For example https://my-azure-webapp.azurewebsites.net/actuator/appconfiguration-refresh?myToken=myTokenSecret

  5. Select Create to create the event subscription. When Create is selected a registration request for the Web Hook will be sent to your application. This is received by the Azure App Configuration client library, verified, and returns a valid response.

  6. Select Event Subscriptions in the Events pane to validate that the subscription was created successfully.

    Web Hook shows up in a table on the bottom of the page.

Note

When subscribing for configuration changes, one or more filters can be used to reduce the number of events sent to your application. These can be configured either as Event Grid subscription filters. For example, a subscription filter can be used to only subscribe to events for changes in a key that starts with a specific string.

Note

If you have multiple instances of your application running, you can use the appconfiguration-refresh-bus endpoint which requires setting up Azure Service Bus, which is used to send a message to all instances of your application to refresh their configuration. This is useful if you have multiple instances of your application running and want to ensure that all instances are updated with the latest configuration. This endpoint isn't available unless you have spring-cloud-bus as a dependency with it configured. See the Azure Service Bus Spring Cloud Bus documentation for more information. The service bus connection only needs to be set up and the Azure App Configuration library will handle sending and receiving the messages.

Verify and test application

  1. After your application is running, use curl to test your application, for example:

    curl -X GET https://my-azure-webapp.azurewebsites.net

  2. Open the Azure Portal and navigate to your App Configuration resource associated with your application. Select Configuration Explorer under Operations and update the values of the following keys:

    Key Value
    application/config.message Hello - Updated

  3. Refresh the browser page to see the new message displayed.

Clean up resources

If you don't want to continue using the resources created in this article, delete the resource group you created here to avoid charges.

Important

Deleting a resource group is irreversible. The resource group and all the resources in it are permanently deleted. Ensure that you don't accidentally delete the wrong resource group or resources. If you created the resources for this article inside a resource group that contains other resources you want to keep, delete each resource individually from its respective pane instead of deleting the resource group.

  1. Sign in to the Azure portal, and select Resource groups.
  2. In the Filter by name box, enter the name of your resource group.
  3. In the result list, select the resource group name to see an overview.
  4. Select Delete resource group.
  5. You're asked to confirm the deletion of the resource group. Enter the name of your resource group to confirm, and select Delete.

After a few moments, the resource group and all its resources are deleted.

Next steps

In this tutorial, you enabled your Java app to dynamically refresh configuration settings from App Configuration. For further questions see the reference documentation, it has all of the details on how the Spring Cloud Azure App Configuration library works. To learn how to use an Azure managed identity to streamline the access to App Configuration, continue to the next tutorial.

Managed identity integration