13 KiB
| title | description | services | documentationcenter | author | editor | ms.service | ms.topic | ms.date | ms.custom | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|
| Azure Spring Cloud App Configuration | An in-depth guide on the Azure Spring Cloud App Configuration Library | azure-app-configuration | mrm9084 | azure-app-configuration | guide | 09/16/2021 | devx-track-java | mametcal |
Azure Spring Cloud App Configuration Client Library
The Azure Spring Cloud App Configuration Client Library loads configurations and feature flags from the Azure App Configuration service. The client library generates PropertySource abstractions, to match those already being generated by the Spring environment such as; Environment Variables, Command-line configurations, local configuration files, and so on.
Setting up your App Configuration Store
To create your Azure App Configuration store, you can use:
az appconfig create --resource-group <your-resource-group> --name <name-of-your-new-store> --sku Standard
This command will create you a new empty configuration store. You can upload you configurations using the import command:
az appconfig kv import -n <name-of-your-new-store> -s file --path <location-of-your-properties-file> --format properties --prefix /application/
It will have you confirm your configurations before loading them. You can upload yaml files by changing the format to yaml. The prefix field is important as it is the default prefix loaded by the client library.
Client Usage
To use the feature in an application, you can build it as a Spring Boot application. The most convenient way to add the dependency is with our Spring Boot starter com.azure.spring:azure-spring-cloud-starter-appconfiguration-config. The following example pom.xml file uses Azure App Configuration:
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>{spring-boot-version}</version>
<relativePath />
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>{spring-cloud-version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.azure.spring</groupId>
<artifactId>azure-spring-cloud-starter-appconfiguration-config</artifactId>
<version>{azure-appconfiguration-version}</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
A basic Spring Boot application using App Configuration:
@SpringBootApplication
@RestController
public class Application {
@RequestMapping("/")
public String home() {
return "Hello World!";
}
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
with bootstrap.properties containing:
spring.cloud.azure.appconfiguration.stores[0].connection-string=${CONFIG_STORE_CONNECTION_STRING}
where CONFIG_STORE_CONNECTION_STRING is an Environment Variable with the connection string to your Azure App Configuration Store. You can access your connection string by running:
az appconfig credential list --name <name-of-your-store>
By default, if no configurations are set, then the configurations starting with /application/ are loaded with a default label of (No Label) unless a Spring Profile is set in which case the default label is your Spring Profile. Because the store is empty no configurations are loaded, but the Azure App Configuration Property Source is still generated.
A property source named /application/https://<name-of-your-store>.azconfig.io/ is created containing the properties of that store.The label used in the request is appended to the end of the name, if no label is set the character \0 is there, as an empty space.
Loading Configuration
The library supports the loading of one or multiple App Configuration stores. This allows for complex configuration scenarios, such as loading of configurations from multiple stores at once or having fallbacks for added resilience. In the situation where a key is duplicated across multiple stores, loading all stores will result in the highest priority, last one wins, stores configuration being loaded. Example:
spring.cloud.azure.appconfiguration.stores[0].connection-string=[first-store-connection-string]
spring.cloud.azure.appconfiguration.stores[1].connection-string=[second-store-connection-string]
In the example, if both the first and second stores have the same configuration, the configuration in the second store has the highest priority, last one wins.
Selecting Configurations
Configurations are loaded by their key and label. By default, the configurations that start with the key /application/ are loaded. The default label is ${spring.profiles.active}. If ${spring.profiles.active} is not set then configuration with the null label seen as (No Label) in the portal are loaded.
The configurations that are loaded can be configured by selecting different key and label filters.
spring.cloud.azure.appconfiguration.stores[0].selects[0].key-filter=[my-key]
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=[my-label]
key-filter supports the following filters:
| Key Filter | Effect |
|---|---|
* |
Matches any key |
abc |
Matches a key named abc |
abc* |
Matches key names that start with abc |
abc,xyz |
Matches key names abc or xyz (limited to 5 CSV) |
label-filter supports the following filters:
| Label | Description |
|---|---|
* |
Matches any label, which includes \0 |
\0 |
Matches null labels, seen as (No Label) in the portal |
1.0.0 |
Matches label 1.0.0 exactly |
1.0.* |
Matches labels that start with 1.0. |
,1.0.0 |
Matches labels null or 1.0.0, limited to five CSVs |
If you are using yaml with label filters and need to start with null, then the label filter needs to be surrounded by single quotes.
spring:
cloud:
azure:
appconfiguration:
stores:
-
selects:
-
label-filter: ',1.0.0'
[!NOTE] You are unable to combine
*with,in filters. In that case you need to use an additional select.
Spring Profiles
By default, spring.profiles.active is set as the default label-filter for all selected configurations. This functionality can be overridden by the label-filter. The Spring Profiles can be used in the label-filter by using ${spring.profiles.active} in the label-filter.
spring.cloud.azure.appconfiguration.stores[0].selects[0].label-filter=,${spring.profiles.active}
spring.cloud.azure.appconfiguration.stores[0].selects[1].label-filter=${spring.profiles.active}_local
In the first label-filter, all configurations with null label are loaded, then all configurations matching the Spring Profiles. Spring Profiles have priority over the null configurations, because they are at the end.
In the second label-filter, the string _local is appended to the end of the Spring Profiles, though only to the last Spring Profile.
Disabled Stores
Using the configuration spring.cloud.azure.appconfiguration.enabled you can disable loading all configuration stores. With the spring.cloud.azure.appconfiguration.stores[0].enabled configuration, you can disable an individual store.
In addition to disabling all stores, stores can be configured to be disabled if they fail to load using the spring.cloud.azure.appconfiguration.stores[0].fail-fast. When fail-fast is enabled, set to true, a RuntimeException that would result in the application not starting up will instead have the store disabled with no configurations from it loaded. If a configuration store is disabled on startup it will not be checked for changes with refresh, or attempted to be loaded from if configurations are updated.
If, an error resulting in a RuntimeException happens during a refresh check or a reload of configuration the refresh attempt is ended and will be retried after the refresh-interval has passed.
Authentication
The client library supports all forms of Identity supported by the Azure Identity Library. Authentication can be done through configuration for Connection Strings and Managed Identity. All other forms of Identity can be done by using the TokenCredentialProvider.
Connection String
Authentication through connection string is the simplest form to setup. You can access a stores connection strings using:
az appconfig credential list --name <name-of-your-store>
The connection string can be then set to the property spring.cloud.azure.appconfiguration.stores[0].connection-string. It is highly recommended that the connection string in the local configuration file should be a placeholder value, which should map to an Environment Variable to avoid having it added to source control.
User Assigned Identity
If you already don't have one, you can create a new Managed Identity using:
az identity create -g myResourceGroup -n myUserAssignedIdentity
Connecting to Azure app configuration with any authentication method other connection string requires three steps to setup.
- Adding the Identity to the resource connecting to your App Configuration store
- Adding the required information to your client application.
- Authorizing the Identity to use App Configuration.
For user assigned, the identity needs to be added to the azure resource. How the user assigned identity is added varies between resources so you will need to check the specific docs of that resource.
Configuration of the client application just needs two values to be set.
spring.cloud.azure.appconfiguration.managed-identity.client-id= <your client id>
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
The first property tells us which of the configured User Assigned identities to use. The second is which configuration store we are connecting to. With this method, all configuration stores need to use the same User Assigned Identity.
Next, the User Assigned Identity needs to be setup in your configuration store. Setup can be done through IAM in the Azure Portal or using the cli:
az role assignment create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
System Assigned Identity
Setting up System Assigned Identity involves enabling it on the azure resource. How the identity is enabled depends on the resource, so you will need to check the documentation for that resource. Once it is enabled, you need to configure your client application to use it.
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
You will then need to assign the System Assigned Identity to read configurations.
az role assignment create --role "App Configuration Data Reader" --assignee <your client id> --scope /subscriptions/<your subscription>/resourceGroups/<your stores resource group>/providers/Microsoft.AppConfiguration/configurationStores/<name of your Configuration Store>
Token Credential
To authenticate with any other method supported by the Azure Identity Library, you can use AppConfigurationCredentialProvider. AppConfigurationCredentialProvider allows you to dynamically return any TokenCredential for any given URI to connect to your Configuration stores.
@Bean
public AppConfigurationCredentialProvider appConfigurationCredentialProvider() {
return new AppConfigurationCredentialProvider() {
@Override
public TokenCredential getAppConfigCredential(String uri) {
...
return myTokenCredential;
}
};
}
You will also need to configure the endpoints that you will be connecting too.
spring.cloud.azure.appconfiguration.stores[0].endpoint= <URI of your Configuration Store>
[!NOTE] Only 1 authentication method can be defined per endpoint; Connection String, User Assigned Identity, Token Credential. If you need to mix and match you can have
AppConfigurationCredentialProviderreturnnullfor stores that use a different method.
For more information
See Starter Readme for more details and compete documentation of all settings.