Configuration management is essential for any application, and Micronaut offers robust support for loading external YAML or configuration files. This article explores various methods for loading these files in Micronaut and demonstrates how to access configuration values using @ConfigurationProperties.
1. Importance of External Configuration Files
External configuration files allow applications to be more flexible and adaptable to different environments without modifying the source code. By separating configuration from the application logic, we can:
- Easily manage environment-specific settings (e.g., development, staging, production).
- Modify application behaviour without redeployment by updating external files.
- Secure sensitive data by keeping credentials or API keys outside the codebase.
- Enhance maintainability by centralizing configuration management.
2. Default Configuration in application.yml
Micronaut applications use application.yml (or application.properties) for configuration. By default, this file is located in src/main/resources/. Micronaut Framework uses SnakeYAML to read configuration from files like application.yml, but since version 4.0 does not expose it as a transitive dependency, we must manually add the following Maven dependency to continue using YAML.
1 2 3 4 5 | <dependency> <groupId>org.yaml</groupId> <artifactId>snakeyaml</artifactId> <scope>runtime</scope></dependency> |
Example application.yml:
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 | micronaut: application: name: "MicronautConfigDemo"app: name: "MicronautApp" version: 1 supportedLanguages: - "English" - "German" - "Japanese" metadata: author: "John Doe" license: "Apache 2.0" features: enableLogging: true maxUsers: 1000 maintenanceMode: false |
Micronaut automatically loads this configuration when the application starts.
3. Loading External Configuration Files
External configuration files allow applications to manage settings dynamically without modifying the core codebase. Micronaut enables the loading of such files to support different environments, override defaults, and enhance flexibility.
3.1 Using micronaut.config.files
Micronaut allows loading external configuration files using the micronaut.config.files system property.
Example External YAML File Location: opt/config/custom-config.yml
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 | micronaut: application: name: "MicronautConfigDemo"app: name: "MicronautApp-2" version: 1 supportedLanguages: - "English" - "French" - "Chinese" metadata: author: "Mr Fish" license: "2025 OpenSource License" features: enableLogging: true maxUsers: 5000 maintenanceMode: true |
Run the application with:
1 | java -Dmicronaut.config.files=opt/config/custom-config.yml -jar target/configdemo-0.1.jar |
3.2 Using Environment Variables
Micronaut allows environment variables to override configuration values.
1 2 | export MICRONAUT_CONFIG_FILES=opt/config/custom-config.ymljava -jar target/configdemo-0.1.jar |
Micronaut will prioritize loading configuration from opt/config/custom-config.yml instead of the default application.yml in src/main/resources/. If both files define the same properties, values from custom-config.yml will override those in application.yml.
If we want to set a specific order for loading configuration files, list them as a comma-separated value. For example, if we want to add another configuration file but keep classpath:application.yml as the highest priority, we should do the following:
1 | java -Dmicronaut.config.files=opt/config/custom-config.yml,classpath:application.yml -jar target/configdemo-0.1.jar |
4. Accessing Configuration Values in Micronaut
Micronaut allows us to access configuration values in a structured way using @ConfigurationProperties. This approach helps map YAML or properties file values directly to Java objects, making configuration management more organized and type-safe.
4.1 Using @ConfigurationProperties
To map these properties, we use @ConfigurationProperties.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | @ConfigurationProperties("app")public class AppConfig { private String name; private int version; private List<String> supportedLanguages; private Map<String, String> metadata; private Map<String, Object> features; public String getName() { return name; } public void setName(String name) { this.name = name; } public int getVersion() { return version; } public void setVersion(int version) { this.version = version; } public List<String> getSupportedLanguages() { return supportedLanguages; } public void setSupportedLanguages(List<String> supportedLanguages) { this.supportedLanguages = supportedLanguages; } public Map<String, String> getMetadata() { return metadata; } public void setMetadata(Map<String, String> metadata) { this.metadata = metadata; } public Map<String, Object> getFeatures() { return features; } public void setFeatures(Map<String, Object> features) { this.features = features; } } |
This AppConfig class is annotated with @ConfigurationProperties("app"), which means it maps properties under the app key in application.yml to this Java class. Each field in the class corresponds to a specific property or group of properties in the YAML file.
The name and version fields map directly to app.name and app.version, storing the application’s name and version as a String and int, respectively. The supportedLanguages field is a List<String>, which aligns with a YAML array, allowing multiple values to be stored under app.supportedLanguages.
The metadata field is a Map<String, String>, meaning it captures key-value pairs from the app.metadata section of application.yml. This is useful for storing structured information like an author’s name and license type. Similarly, features is a Map<String, Object>, which allows flexibility in storing various configuration options that might include different data types, making it ideal for handling dynamic feature settings.
4.2 Using the Configuration Class in a Controller
Once the configuration values are mapped to a Java class, they can be injected into other components of the application, such as controllers or services. This allows easy access to configuration properties at runtime without hardcoding values. In this section, we will use the AppConfig class inside a Micronaut controller to expose the configuration details through an HTTP endpoint.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 | @Controller("/config")public class ConfigController { private final AppConfig appConfig; public ConfigController(AppConfig appConfig) { this.appConfig = appConfig; } @Get public String getConfig() { return "App: " + appConfig.getName() + ", Version: " + appConfig.getVersion() + ", SupportedLanguages: " + appConfig.getSupportedLanguages() + ", Metadata: " + appConfig.getMetadata() + ", Features: " + appConfig.getFeatures(); }} |
4.3 Testing the Configuration
Start the application and access the /config endpoint to retrieve the configuration values.
1 2 3 | ./mvnw packagejava -jar target/configdemo-0.1.jar |
Call the /config endpoint:
1 | curl http://localhost:8080/config |
The response will display the properties defined in the default application.yml file.
1 2 3 | App: MicronautApp, Version: 1, SupportedLanguages: [English, German, Japanese], Metadata: {author=John Doe, license=Apache 2.0, website=https://example.com}, Features: {enable-logging=true, max-users=1000, maintenance-mode=false} |
Running the Application with an External Configuration
To override the default configuration, we can run the application while specifying an external configuration file. This allows us to load settings from opt/config/custom-config.yml, ensuring that the application uses custom values instead of those defined in application.yml.
Use the following command to run the application with the external configuration file:
1 | java -Dmicronaut.config.files=opt/config/custom-config.yml -jar target/configdemo-0.1.jar |
This tells Micronaut to prioritize loading configuration from opt/config/custom-config.yml. After starting the application, we can test the loaded configuration by calling the /config endpoint. The expected output from the /config endpoint would be:
This confirms that the application is successfully loading and using the external configuration file.
5. Conclusion
In this article, we explored how Micronaut loads external YAML configuration files and how to access configuration values using @ConfigurationProperties. We demonstrated the default behaviour of application.yml, the process of overriding configurations with an external file, and how to inject configuration values into a controller. By leveraging external configuration files, Micronaut applications can remain flexible, environment-independent, and easily configurable without modifying the source code.
6. Download the Source Code
This article covered loading an external YAML or configuration file in Micronaut.
You can download the full source code of this example here: micronaut loading external yaml or configuration file
