Configure a managed Spring Cloud Config Server in Azure Spring Apps

Note

The Basic, Standard, and Enterprise plans will be deprecated starting from mid-March, 2025, with a 3 year retirement period. We recommend transitioning to Azure Container Apps. For more information, see the Azure Spring Apps retirement announcement.

The Standard consumption and dedicated plan will be deprecated starting September 30, 2024, with a complete shutdown after six months. We recommend transitioning to Azure Container Apps. For more information, see Migrate Azure Spring Apps Standard consumption and dedicated plan to Azure Container Apps.

This article applies to: ✔️ Java ✔️ C#

This article applies to: ✔️ Standard consumption and dedicated (Preview) ✔️ Basic/Standard ✔️ Enterprise

This article shows you how to configure a managed Spring Cloud Config Server in Azure Spring Apps.

Spring Cloud Config Server provides server and client-side support for an externalized configuration in a distributed system. The Spring Cloud Config Server instance provides a central place to manage external properties for applications across all environments. For more information, see Spring Cloud Config.

Note

To use config server in the Standard consumption and dedicated plan, you must enable it first. For more information, see Enable and disable Spring Cloud Config Server in Azure Spring Apps.

Prerequisites

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

• An already provisioned and running Azure Spring Apps service instance using the Basic or Standard plan. To set up and launch an Azure Spring Apps service, see Quickstart: Deploy your first application to Azure Spring Apps.

• An already provisioned and running Azure Spring Apps service instance. To set up and launch an Azure Spring Apps service, see Quickstart: Build and deploy apps to Azure Spring Apps using the Enterprise plan.

• Git.

Enable Spring Cloud Config Server

You can enable Spring Cloud Config Server when you provision an Azure Spring Apps Enterprise plan service instance. If you already have an Azure Spring Apps Enterprise plan instance, see the Manage Spring Cloud Config Server in an existing Enterprise plan instance section in this article.

You can enable Spring Cloud Config Server using the Azure portal or Azure CLI.

Azure portal

Use the following steps to enable Spring Cloud Config Server:

1. Open the Azure portal.

2. On the Basics tab, select Enterprise tier in the Pricing section and specify the required information. Then, select Next: Managed components.

3. On the Managed components tab, select Enable Spring Cloud Config Server.

   

4. Specify other settings, and then select Review and Create.

5. On the Review an create tab, make sure that Enable Spring Cloud Config Server is set to Yes. Select Create to create the Enterprise plan instance.

Azure CLI

Use the following steps to provision an Azure Spring Apps service instance with Spring Cloud Config Server enabled.

1. Use the following commands to sign in to the Azure CLI and choose your active subscription:

   az login
   az account list --output table
   az account set --subscription <subscription-ID>
   

2. Use the following commands to accept the legal terms and privacy statements for the Azure Spring Apps Enterprise plan. This step is necessary only if your subscription has never been used to create an Enterprise plan instance of Azure Spring Apps.

   az provider register --namespace Microsoft.SaaS
   az term accept \
       --publisher vmware-inc \
       --product azure-spring-cloud-vmware-tanzu-2 \
       --plan asa-ent-hr-mtr
   

3. Select a location. The location must support the Azure Spring Apps Enterprise plan. For more information, see the Azure Spring Apps FAQ.

4. Use the following command to create a resource group:

   az group create \
       --name <resource-group-name> \
       --location <location>
   

   For more information about resource groups, see What is Azure Resource Manager?

5. Prepare a name for your Azure Spring Apps service instance. The name must be between 4 and 32 characters long and can contain only lowercase letters, numbers, and hyphens. The first character of the service name must be a letter and the last character must be either a letter or a number.

6. Use the following command to create an Azure Spring Apps service instance with Spring Cloud Config Server enabled:

   az spring create \
       --resource-group <resource-group-name> \
       --name <Azure-Spring-Apps-service-instance-name> \
       --sku enterprise \
       --enable-config-server
   

Restrictions

There are some restrictions when you use Config Server with a Git back end. The following properties are automatically injected into your application environment to access Config Server and Service Discovery. If you also configure those properties from your Config Server files, you might experience conflicts and unexpected behavior.

• eureka.client.service-url.defaultZone
• eureka.client.tls.keystore
• eureka.instance.preferIpAddress
• eureka.instance.instance-id
• server.port
• spring.cloud.config.tls.keystore
• spring.config.import
• spring.application.name
• spring.jmx.enabled
• management.endpoints.jmx.exposure.include

Caution

Avoid putting these properties in your Config Server application files.

Create your Config Server files

Azure Spring Apps supports Azure DevOps Server, GitHub, GitLab, and Bitbucket for storing your Config Server files. When your repository is ready, you can create the configuration files and store them there.

Some configurable properties are available only for certain types. The following sections describe the properties for each repository type.

Note

Config Server takes master (on Git) as the default label if you don't specify one. However, GitHub has recently changed the default branch from master to main. To avoid Azure Spring Apps Config Server failure, be sure to pay attention to the default label when setting up Config Server with GitHub, especially for newly created repositories.

Using a hyphen (-) to separate words is the only property naming convention currently supported. For example, you can use default-label, but not defaultLabel.

Public repository

When you use a public repository, your configurable properties are more limited than they are with a private repository.

The following table lists the configurable properties you can use to set up a public Git repository:

Property	Required	Feature
uri	Yes	The URI of the Git repository used as the Config Server back end. Should begin with http://, https://, git@, or ssh://.
default-label	No	The default label of the Git repository. Should be a branch name, tag name, or commit ID in the repository.
search-paths	No	An array of strings that are used to search subdirectories of the Git repository.

Private repository with SSH authentication

The following table lists the configurable properties you can use to set up a private Git repository with SSH:

Property	Required	Feature
uri	Yes	The URI of the Git repository used as the Config Server back end. Should begin with http://, https://, git@, or ssh://.
default-label	No	The default label of the Git repository. Should be the branch name, tag name, or commit ID of the repository.
search-paths	No	An array of strings used to search subdirectories of the Git repository.
private-key	No	The SSH private key to access the Git repository. Required when the URI starts with git@ or ssh://.
host-key	No	The host key of the Git repository server. Shouldn't include the algorithm prefix as covered by host-key-algorithm.
host-key-algorithm	No	The host key algorithm. Should be ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Required only if host-key exists.
strict-host-key-checking	No	The Config Server indicator that shows whether it fails to start when using the private host-key. Should be true (default value) or false.

Private repository with basic authentication

The following table lists the configurable properties you can use to set up a private Git repository with basic authentication:

Property	Required	Feature
uri	Yes	The URI of the Git repository used as the Config Server back end. Should begin with http://, https://, git@, or ssh://.
default-label	No	The default label of the Git repository. Should be a branch name, tag name, or commit-id in the repository.
search-paths	No	An array of strings used to search subdirectories of the Git repository.
username	No	The username used to access the Git repository server. Required when the Git repository server supports HTTP basic authentication.
password	No	The password or personal access token used to access the Git repository server. Required when the Git repository server supports HTTP basic authentication.

Note

Many Git repository servers support the use of tokens rather than passwords for HTTP basic authentication. Some repositories allow tokens to persist indefinitely. However, some Git repository servers, including Azure DevOps Server, force tokens to expire in a few hours. Repositories that cause tokens to expire shouldn't use token-based authentication with Azure Spring Apps. If you use such a token, remember to update it before it expires.

GitHub has removed support for password authentication, so you need to use a personal access token instead of password authentication for GitHub. For more information, see Token authentication requirements for Git operations.

Other Git repositories

The following table lists the configurable properties you can use to set up Git repositories with a pattern:

Property	Required	Feature
repos	No	A map consisting of the settings for a Git repository with a given name.
repos."uri"	Yes on repos	The URI of the Git repository used as the Config Server back end. Should begin with http://, https://, git@, or ssh://.
repos."name"	Yes on repos	A name to identify the repository; for example, team-A or team-B. Required only if repos exists.
repos."pattern"	No	An array of strings used to match an application name. For each pattern, use the format {application}/{profile} with wildcards.
repos."default-label"	No	The default label of the Git repository. Should be the branch name, tag name, or commit IOD of the repository.
repos."search-paths"	No	An array of strings used to search subdirectories of the Git repository.
repos."username"	No	The username used to access the Git repository server. Required when the Git repository server supports HTTP basic authentication.
repos."password"	No	The password or personal access token used to access the Git repository server. Required when the Git repository server supports HTTP basic authentication.
repos."private-key"	No	The SSH private key to access Git repository. Required when the URI begins with git@ or ssh://.
repos."host-key"	No	The host key of the Git repository server. Shouldn't include the algorithm prefix as covered by host-key-algorithm.
repos."host-key-algorithm"	No	The host key algorithm. Should be ssh-dss, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521. Required only if host-key exists.
repos."strict-host-key-checking"	No	Indicates whether the Config Server instance fails to start when using the private host-key. Should be true (default value) or false.

The following table shows some examples of patterns for configuring your service with an optional extra repository. For more information, see the Extra repositories section in this article and the Pattern Matching and Multiple Repositories section of Spring Cloud Config.

Patterns	Description
test-config-server-app-0/*	The pattern and repository URI matches a Spring boot application named test-config-server-app-0 with any profile.
test-config-server-app-1/dev	The pattern and repository URI matches a Spring boot application named test-config-server-app-1 with a dev profile.
test-config-server-app-2/prod	The pattern and repository URI matches a Spring boot application named test-config-server-app-2 with a prod profile.

Configure a Git repository against Config Server

After you save your configuration files in a repository, use the following steps to connect Azure Spring Apps to the repository:

1. Sign in to the Azure portal.

2. Go to your Azure Spring Apps Overview page.

3. Select Spring Cloud Config Server in the navigation pane.

4. In the Default repository section, set URI to https://github.com/Azure-Samples/piggymetrics-config.

5. Select Validate.

   

   

6. When validation is complete, select Apply to save your changes.

   

   

Updating the configuration can take a few minutes. You should get a notification when the configuration is complete.

Enter repository information directly to the Azure portal

You can enter repository information for the default repository and, optionally, for extra repositories.

Default repository

This section shows you how to enter repository information for a public or private repository. For a private repo, you can use Basic authentication or SSH.

Use the following steps to enter repo information for a public repository:

1. In the Default repository section, in the Uri box, paste the repository URI.
2. For the Label setting, enter config.
3. Ensure that the Authentication setting is Public.
4. Select Apply.

Use the following steps to enter repo information for a private repository using basic password/token-based authentication:

1. In the Default repository section, in the Uri box, paste the repository URI.

2. Under Authentication, select Edit Authentication.

3. In the Edit Authentication pane, on the Authentication type drop-down list, select HTTP Basic.

4. Enter your username and password/token to grant access to Azure Spring Apps.

5. Select OK, and then select Apply to finish setting up your Config Server instance.

   

   Note

   Many Git repository servers support the use of tokens rather than passwords for HTTP basic authentication. Some repositories allow tokens to persist indefinitely. However, some Git repository servers, including Azure DevOps Server, force tokens to expire in a few hours. Repositories that cause tokens to expire shouldn't use token-based authentication with Azure Spring Apps. If you use such a token, remember to update it before it expires.

   GitHub has removed support for password authentication, so you need to use a personal access token instead of password authentication for GitHub. For more information, see Token authentication requirements for Git operations.

Use the following steps to enter repo information for a private repository using SSH:

1. In the Default repository section, in the Uri box, paste the repository URI.

2. Under Authentication, select Edit Authentication.

3. On the Edit Authentication pane, in the Authentication type drop-down list, select SSH.

4. Enter your private key. Optionally, specify your host key and host key algorithm.

5. Include your public key in your Config Server repository.

6. Select OK, and then select Apply to finish setting up your Config Server instance.

   

Extra repositories

If you want to configure your service with an optional extra repository, use the following steps:

1. Specify the Uri and Authentication settings as you did for the default repository. Be sure to include a Name setting for your pattern.
2. Select Apply to attach the repository to your instance.

Configure a Git repository by importing a YAML file

If you wrote a YAML file with your repository settings, you can import the file directly from your local machine to Azure Spring Apps. The following example shows a simple YAML file for a private repository with basic authentication:

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/azure-spring-apps-samples-pr/config-server-repository.git
          username: <username>
          password: <password/token>

Use the following steps to import a YAML file:

1. Select Import settings and then select the YAML file from your project directory. Select Import.

   

   

   The Notifications pane displays an async operation. Config Server should report success after 1-2 minutes. The information from your YAML file displays in the Azure portal.

2. Select Apply to finish the import.

Configure Azure Repos against Config Server

Azure Spring Apps can access Git repositories that are public, secured by SSH, or secured using HTTP basic authentication. HTTP basic authentication is the easiest of the options for creating and managing repositories with Azure Repos.

Get the repo URL and credentials

Use the following steps to get your repo URL and credentials:

1. In the Azure Repos portal for your project, select Clone.

2. Copy the clone URL from the textbox. This URL is typically in the following form:

   https://<organization name>@dev.azure.com/<organization name>/<project name>/_git/<repository name>
   

   Remove everything after https:// and before dev.azure.com, including the @ symbol. The resulting URL should be in the following form:

   https://dev.azure.com/<organization name>/<project name>/_git/<repository name>
   

   Save this URL to use later.

3. Select Generate Git Credentials to display a username and password. Save this username and password to use in the following section.

Configure a Git repository against Config Server

Use the following steps to configure the repo:

1. Sign in to the Azure portal.

2. Go to your Azure Spring Apps Overview page.

3. Select the service to configure.

4. In the left pane of the service page under Settings, select the Spring Cloud Config Server tab.

5. Use the following steps to configure the repository you created:

   • Add the repository URI that you saved earlier.
   • Select the setting under Authentication to open the Edit Authentication pane.
   • For Authentication type, select HTTP Basic.
   • For Username, specify the user name that you saved earlier.
   • For Password, specify the password that you saved earlier.
   • Select OK, and then wait for the operation to complete.

   

Bind an app to Spring Cloud Config Server

Use the following command to bind an app to Spring Cloud Config Server, enabling the app to pull configurations from Config Server.

az spring config-server bind \
    --resource-group <resource-group> \
    --service <service-name> \
    --app <app-name>

You can also set up the app binding from the Azure portal, as shown in the following screenshot:

Note

These changes take a few minutes to propagate to all applications when the config server status changes.

If you change the binding/unbinding status, you need to restart or redeploy the application.

You can now choose to bind your application to the Spring Cloud Config Server directly when creating a new app by using the following command:

az spring app create \ 
    --resource-group <resource-group> \ 
    --service <service-name> \ 
    --name <app-name> \ 
    --bind-config-server

You can also bind your application to the Spring Cloud Config Server from the Azure portal, as shown in the following screenshot:

Delete your configuration

Select Reset on the Spring Cloud Config Server tab to erase your existing settings. Delete the config server settings if you want to connect your Config Server instance to another source, such as when you're moving from GitHub to Azure DevOps Server.

Refresh Config Server

When properties are changed, services consuming those properties must be notified before changes can be made. The default solution for Spring Cloud Config Server is to manually trigger the refresh event, which might not be feasible if there are many app instances. For more information, see Centralized Configuration

Instead, you can automatically refresh values from Config Server by letting the config client poll for changes based on a refresh internal.

Use the following steps to automatically refresh values from Config Server:

1. Register a scheduled task to refresh the context in a given interval, as shown in the following example:

   @ConditionalOnBean({RefreshEndpoint.class})
   @Configuration
   @AutoConfigureAfter({RefreshAutoConfiguration.class, RefreshEndpointAutoConfiguration.class})
   @EnableScheduling
   public class ConfigClientAutoRefreshConfiguration implements SchedulingConfigurer {
       @Value("${spring.cloud.config.refresh-interval:60}")
       private long refreshInterval;
       @Value("${spring.cloud.config.auto-refresh:false}")
       private boolean autoRefresh;
       private RefreshEndpoint refreshEndpoint;
       public ConfigClientAutoRefreshConfiguration(RefreshEndpoint refreshEndpoint) {
           this.refreshEndpoint = refreshEndpoint;
       }
       @Override
       public void configureTasks(ScheduledTaskRegistrar scheduledTaskRegistrar) {
           if (autoRefresh) {
               // set minimal refresh interval to 5 seconds
               refreshInterval = Math.max(refreshInterval, 5);
               scheduledTaskRegistrar.addFixedRateTask(() -> refreshEndpoint.refresh(), refreshInterval * 1000);
           }
       }
   }
   

2. Enable autorefresh and set the appropriate refresh interval in your application.yml file. In the following example, the client polls for configuration changes every 60 seconds, which is the minimum value you can set for a refresh interval.

   By default, autorefresh is set to false and the refresh-interval is set to 60 seconds.

   spring:
       cloud:
            config:
             auto-refresh: true
             refresh-interval: 60
   management:
       endpoints:
            web:
             exposure:
               include:
                 - refresh
   

3. Add @RefreshScope to your code. In the following example, the variable connectTimeout is automatically refreshed every 60 seconds.

   @RestController
   @RefreshScope
   public class HelloController {
       @Value("${timeout:4000}")
       private String connectTimeout;
   }
   

For more information, see the config-client-polling sample.

Manage Spring Cloud Config Server in an existing Enterprise plan instance

You can enable and disable Spring Cloud Config Server after service creation using the Azure portal or Azure CLI. Before disabling Spring Cloud Config Server, you're required to unbind all of your apps from it.

Azure portal

Use the following steps to enable or disable Spring Cloud Config Server:

1. Navigate to your service instance and then select Spring Cloud Config Server.

2. Select Manage.

3. Select or unselect Enable Spring Cloud Config Server, and then select Save.

   

4. You can now view the state of Spring Cloud Config Server on the Spring Cloud Config Server page.

Azure CLI

Use the following Azure CLI commands to enable or disable Spring Cloud Config Server:

az spring config-server create \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

az spring config-server delete \
    --resource-group <resource-group-name> \
    --service <Azure-Spring-Apps-service-instance-name>

Related content

Azure Spring Apps