mp.config.introduction.adoc Maven / Gradle / Ivy
///////////////////////////////////////////////////////////////////////////////
Copyright (c) 2020, 2024 Oracle and/or its affiliates.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
///////////////////////////////////////////////////////////////////////////////
= MicroProfile Config
:spec-name: MicroProfile Config
:description: {spec-name} support in Helidon MP
:keywords: helidon, mp, microprofile, config, encryption, reference
:config-release: {version-lib-microprofile-config}
:feature-name: MicroProfile Config
:rootdir: {docdir}/../..
:microprofile-bundle: true
include::{rootdir}/includes/mp.adoc[]
== Contents
- <>
- <>
- <>
- <>
- <>
== Overview
Helidon {spec-name} is an implementation of https://github.com/eclipse/microprofile-config/[Eclipse {spec-name}]. You can configure your applications using MicroProfile's config configuration sources and APIs. You can also extend the configuration using MicroProfile SPI to add custom `ConfigSource` and `Converter`.
include::{rootdir}/includes/dependencies.adoc[]
[source,xml]
----
io.helidon.microprofile.config
helidon-microprofile-config
----
== Usage
=== {spec-name} Features
==== {spec-name} Sources
A Config Source provides configuration values from different sources such as property files and user classes that are registered by the application.
By default, the following configuration sources are used to retrieve the configuration:
[cols="3,5"]
|===
|Source |Description
|System properties |A mutable source that uses `System.getProperties()` to obtain configuration values.
|Environment variables |An immutable source that uses `System.env()` to obtain configuration values and resolves aliases as defined by the {spec-name} specification.
|`META-INF/microprofile-config.properties` |The properties config source as defined by {spec-name} specification.
|===
{spec-name} uses `ConfigSource` SPI to load configuration data, either from default configuration sources or from custom `ConfigSource` located by Java Service Loader.
==== Using {spec-name} API
You can use {spec-name} API to get configuration properties by using a `Config`
instance programmatically or injecting configuration values with `@ConfigProperty`.
[source,java]
.Using `Config`
----
include::{sourcedir}/mp/config/IntroductionSnippets.java[tag=snippet_1, indent=0]
----
[source,java]
.Injecting configured properties into a constructor
----
include::{sourcedir}/mp/config/IntroductionSnippets.java[tag=snippet_2, indent=0]
----
{spec-name} provides typed access to configuration values, using built-in converters, and `Converter` implementations located by Java Service Loader.
==== Ordering of Default Config Sources
In order to properly configure your application using configuration sources, you need to understand the precedence rules used to merge your configuration data. The default MicroProfile Config Sources ordering is:
* System properties (ordinal=400)
* Environment variables (ordinal=300)
* /META-INF/microprofile-config.properties (ordinal=100)
Each Config Source has an ordinal that determines the priority of the Config Source.
A Config Source with higher ordinal has higher priority as compared to the Config Source with
lower ordinal. The values taken from the high-priority Config Source overrides the values
from low-priority Config Source. The default value is 100.
NOTE: In MP, the ordering is not defined for sources that have the same ordinal.
This helps to customize the configuration of Config Sources using external Config Source
if an external Config Source has higher ordinal values than the built-in Config Sources of the application.
The example below shows how the MicroProfile configuration file `microprofile-config.properties` can be used to modify the server listen port property.
[source,properties]
----
# Application properties. This is the default greeting
app.greeting=Hello
# Microprofile server properties
server.port=8080
server.host=0.0.0.0
----
==== {spec-name} Profiles [[Config-Profiles]]
{spec-name} supports a concept of configuration profiles. You can define a profile using the configuration property `mp.config.profile`
(when using default configuration, this can be defined as a system property, environment variable or as a property in `microprofile-config.properties`).
When a profile is defined, additional config source is loaded (`microprofile-config-profile.properties`) and properties from profile have precedence over
default properties. Profile properties can be defined using `%profile` prefix, such as `%dev.server.port`.
=== Helidon {spec-name} Features
Helidon MicroProfile Config offers the following features on top of the specification:
=== Helidon {spec-name} Sources
Helidon configuration sources can use different formats for the configuration data. You can specify the format on a per source bases, mixing and matching formats as required.
The following configuration sources can be used to retrieve the configuration:
[cols="3,5"]
|===
|Source |Description
|File |Creates the source from a properties file on the file system with `MpConfigSources.create(Path)`.
|URL |Creates the source from properties from a URL with `MpConfigSources.create(URL)`.
|`Map` |Creates the source from a Map with `MpConfigSources.create(Map)`.
|`Properties` |Creates the source directly from Properties with `MpConfigSources.create(Properties)`.
|File on classpath |Creates the source from a properties file on classpath with `MpConfigSources.classpath(String)`.
|YAML |Creates the source from YAML using `YamlMpConfigSource.create(Path)` or `YamlMpConfigSource.create(URL)`.
|===
See xref:advanced-configuration.adoc#_creating_microprofile_config_sources_for_manual_setup_of_config[manual setup of config] section for more information.
==== References
You can use `${reference}` to reference another configuration key in a key value. This
allows to configure a single key to be reused in multiple other keys.
[source,yaml]
.Example
----
uri: "http://localhost:8080"
service-1: "${uri}/service1"
service-2: "${uri}/service2"
----
==== Change support
Polling (or change watching) for file based config sources (not classpath based).
To enable polling for a config source created using meta configuration (see below), or using
`MpConfigSources.create(Path)`, or `YamlMpConfigSource.create(Path)`, use the following properties:
[cols="3,5"]
|===
|Property |Description
|`helidon.config.polling.enabled` |To enable polling file for changes, uses timestamp to identify a change.
|`helidon.config.polling.duration` |Polling period duration, defaults to 10 seconds ('PT10S`) +
See link:{jdk-javadoc-url}/java.base/java/time/Duration.html#parse(java.lang.CharSequence)[javadoc]
|`helidon.config.watcher.enabled` |To enable watching file for changes using the Java `WatchService`. +
See link:{jdk-javadoc-url}/java.base/java/nio/file/WatchService.html
|===
==== Encryption
You can encrypt secrets using a master password and store them in a configuration file.
The config encryption filter in MicroProfile Config is enabled by default.
For more information, see xref:{rootdir}/mp/security/configuration-secrets.adoc[Configuration Secrets].
[source,properties]
.Example of encrypted secrets
----
# Password encrypted using a master password
client_secret=${GCM=mYRkg+4Q4hua1kvpCCI2hg==}
# Password encrypted using public key (there are length limits when using RSA)
client_secret_pke=${RSA=mYRkg+4Q4hua1kvpCCI2hg==}
# Password in clear text, can be used in development
# The system needs to be configured to accept clear text
client_secret_clear=${CLEAR=known_password}
----
==== Meta Configuration
You can configure the Config using Helidon MP Config meta configuration feature. The meta-config allows configuration of config sources and other
configuration options, including addition of discovered sources and converters.
See
xref:advanced-configuration.adoc#_creating_microprofile_config_sources_from_meta_config[Microprofile Config Sources] for detailed information.
NOTE: For backward compatibility, we will support usage of Helidon SE meta-configuration until version 3.0.0. Using this approach causes behavior that is not compatible with {spec-name} specification.
== Configuration
Config sources can be configured using the following properties.
The class responsible for configuration is:
include::{rootdir}/config/io_helidon_config_mp_MpConfigBuilder.adoc[leveloffset=+1,tag=config]
Current properties may be set in `application.yaml` or in `microprofile-config.properties` with `mp.config` prefix.
See xref:#Config-Profiles[Config Profiles] for more information.
== Additional Information
[PILLARS]
====
[CARD]
.MP Config Guide
[xref={rootdir}/mp/guides/config.adoc]
--
Step-by-step guide about using {spec-name} in your Helidon MP application.
--
====
== Reference
* link:{microprofile-config-spec-url}[{spec-name} Specifications]
* link:{microprofile-fault-tolerance-javadoc-url}[{spec-name} Javadocs]
© 2015 - 2025 Weber Informatics LLC | Privacy Policy