Helidon config documentation updates (#3187)

helidon-io · Jul 16, 2021 · c15fa53 · c15fa53
1 parent 2a7b01f
commit c15fa53
Show file tree

Hide file tree

Showing 5 changed files with 117 additions and 598 deletions.
diff --git a/docs/mp/config/01_introduction.adoc b/docs/mp/config/01_introduction.adoc
@@ -44,10 +44,8 @@ include::{common-deps-page-prefix-inc}[tag=maven-dependency]
 == About {spec-name}
 
 Helidon MicroProfile Config is an implementation of https://github.com/eclipse/microprofile-config/[Eclipse MicroProfile Config].
-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` by implementing the
-`org.eclipse.microprofile.config.spi.ConfigSource` and `org.eclipse.microprofile.config.spi.Converter` interfaces respectively.
+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`.
 
 === {spec-name} Features
 
@@ -61,8 +59,6 @@ instance programmatically.
 {spec-name} provides typed access to configuration values, using built-in converters, and `Converter` implementations located
 by Java Service Loader.
 
-{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`.
-
 ==== Using {spec-name} API
 
 You can use MicroProfile Config API to get configuration properties by using `ConfigProvider.getConfig()`
@@ -98,6 +94,13 @@ server.port=8080
 server.host=0.0.0.0
 ----
 
+==== {spec-name} 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:
@@ -118,7 +121,7 @@ service-2: "${uri}/service2"
 * *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 <<security/03_configuration-secrets.adoc,Configuration Secrets>>.
+For more information, see <<mp/security/03_configuration-secrets.adoc,Configuration Secrets>>.
 
 [source,properties]
 .Example of encrypted secrets
@@ -133,52 +136,12 @@ client_secret=${CLEAR=known_password}
 ----
 
 * *Meta Configuration* +
-You can configure the Config using Helidon MP Config meta configuration feature.
-This is a Helidon specific feature available since version 2.3.0.
-
-When used, the {spec-name} uses configuration sources and flags configured in the meta configuration file.
+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.
 
-The meta-config allows configuration of config sources and other configuration options,
-including addition of discovered sources and converters.
+This is a Helidon specific feature available since version 2.3.0. See <<mp/config/02_MP_config_sources.adoc,Microprofile Config Sources>> for detailed information.
 
-If a file named `mp-meta-config.yaml`, or `mp-meta-config.properties` is in the current directory or
-on the classpath, and there is no explicit setup of configuration in the code, the configuration will
-be loaded from the `meta-config` file.
-The location of the file can be overridden using system property `io.helidon.config.mp.meta-config`,
-    or environment variable `HELIDON_MP_META_CONFIG`
-
-[source,yaml]
-.Example of a YAML meta configuration file:
-----
-add-discovered-sources: true <1>
-add-discovered-converters: false <2>
-add-default-sources: false <3>
-
-sources:
-  - type: "environment-variables" <4>
-  - type: "system-properties" <5>
-  - type: "properties" <6>
-    path: "/conf/prod.properties" <7>
-    ordinal: 50 <8>
-    optional: true <9>
-  - type: "yaml"  <10>
-    classpath: "META-INF/database.yaml" <11>
-
-----
-
-<1> If configured to `true`, config sources discovered through service loader will be added
-<2> If configured to `true`, converters discovered through service loader will be added
-<3> If configured to `true`, default config sources (system properties, environment variables, and `META-INF/microprofile-config.properties) will be added
-<4> Loads the environment variables config source.
-<5> Loads the system properties config source.
-<6> Loads a properties file
-<7> Location of the file: `/conf/prod.properties` on the file system
-<8> Custom ordinal, if not defined, the value defined in the file, or default value is used
-<9> The file is optional (if not optional and no file is found, the bootstrap fails)
-<10> Loads a YAML file
-<11> Location of the file: `META-INF/database.yaml` on the classpath
-
-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.
+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.
 
 == Guides
 
@@ -192,57 +155,6 @@ Step-by-step guide about using {spec-name} in your Helidon MP application.
 --
 ====
 
-== Using MicroProfile Config Sources
-
-The following configuration sources can be 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 MicroProfile Config specification.
-
-|`META-INF/microprofile-config.properties`   |The properties config source as defined by MicroProfile Config specification.
-
-|`application.yaml`    |The Helidon default configuration source.
-
-|File    |Creates the source from a properties file on the file system with `MpConfigSources.create(Path)`.
-
-|URL    |Creates the source from properties from an URL with `MpConfigSources.create(URL)`.
-
-|`Map<String, String>`   |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)`.
-
-|===
-
-== Using Helidon Config APIs
-
-You can use `MpConfigSources.create(helidonConfig)` to create a config source from Helidon config and then use it to create a MicroProfile instance.
-
-[source,java]
-----
-io.helidon.config.Config helidonConfig = io.helidon.config.Config.builder()
-                .addSource(ConfigSources.create(Map.of("key", "value"))) <1>
-                .build();
-
-Config config = ConfigProviderResolver.instance()
-                .getBuilder()
-                .withSources(MpConfigSources.create(helidonConfig)) <2>
-                .build();
-----
-
-<1> Creates a config source from Helidon Config.
-<2> Creates a MicroProfile Config instance.
-
-For more information on using Helidon Config APIs, see the Helidon SE Configuration documentation.
-
 == Additional Information
 
 - link:{javadoc-base-url-api}spi/package-summary.html[Helidon Config SPI]

diff --git a/docs/mp/config/02_MP_config_sources.adoc b/docs/mp/config/02_MP_config_sources.adoc
@@ -1,6 +1,6 @@
 ///////////////////////////////////////////////////////////////////////////////
 
-    Copyright (c) 2020 Oracle and/or its affiliates.
+    Copyright (c) 2020, 2021 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.
@@ -25,6 +25,34 @@
 
 A Config Source provides configuration values from different sources such as property files and user classes that are registered by the application.
 
+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
+
+|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 MicroProfile Config specification.
+
+|`META-INF/microprofile-config.properties`   |The properties config source as defined by MicroProfile Config specification.
+
+|File    |Creates the source from a properties file on the file system with `MpConfigSources.create(Path)`.
+
+|URL    |Creates the source from properties from an URL with `MpConfigSources.create(URL)`.
+
+|`Map<String, String>`   |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)`.
+
+|===
+
 == Understanding the Ordering of Default Config Sources
 
 The default MicroProfile Config Sources are:
@@ -41,7 +69,6 @@ from low-priority Config Source.
 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.
 
-
 == Creating Custom Config Sources
 
 Custom Config Sources are loaded using the Java Service Loader pattern, by implementing
@@ -118,14 +145,15 @@ To create an in-memory source from properties with custom name, use `create(Stri
 
 |===
 
-=== Example
+=== Create Custom Map MicroProfile Config Source
+You can create Microprofile Config Source from a map.
 
 [source,java]
 .Create MicroProfile Config Source based on Environment Variables and Custom Map
 ----
 ConfigProviderResolver resolver = ConfigProviderResolver.instance();
 
-org.eclipse.microprofile.config.Config Config config = resolver.getBuilder().getBuilder() <1>
+org.eclipse.microprofile.config.Config config = resolver.getBuilder().getBuilder() <1>
         .withSources(MpConfigSources.environmentVariables()) <2>
         .withSources(MpConfigSources.create(Map.of("key","value"))) <3>
         .build(); <4>
@@ -138,6 +166,63 @@ resolver.registerConfig(config, null); <5>
 <4> Builds the MicroProfile Config Source.
 <5> Registers the config, so it can be used by other components
 
+=== Create Yaml MicroProfile Config Source
+
+You can create Yaml Microprofile Config Source from a path or a URL. When you create a MicroProfile instance from the builder,
+the `YamlMpConfigSource` allows you to create a custom Config Source and register
+it with the builder.
+
+[source,java]
+.Create YamlMPConfigSource from a path
+----
+ConfigProviderResolver.instance().newBuilder()
+        .withSources(YamlMpConfigSource.create(path))
+        .build()
+----
+
+== Creating MicroProfile Config Sources from meta-config
+
+Instead of directly specifying the configuration sources in your code, you can use meta-configuration in a file that declares
+the configuration sources, and their attributes as mentioned in <<mp/config/01_introduction.adoc,Microprofile Config>>
+
+When used, the Microprofile Config uses configuration sources and flags configured in the meta configuration file.
+
+If a file named `mp-meta-config.yaml`, or `mp-meta-config.properties` is in the current directory or
+on the classpath, and there is no explicit setup of configuration in the code, the configuration will
+be loaded from the `meta-config` file.
+The location of the file can be overridden using system property `io.helidon.config.mp.meta-config`,
+or environment variable `HELIDON_MP_META_CONFIG`
+
+[source,yaml]
+.Example of a YAML meta configuration file:
+----
+add-discovered-sources: true <1>
+add-discovered-converters: false <2>
+add-default-sources: false <3>
+
+sources:
+  - type: "environment-variables" <4>
+  - type: "system-properties" <5>
+  - type: "properties" <6>
+    path: "/conf/prod.properties" <7>
+    ordinal: 50 <8>
+    optional: true <9>
+  - type: "yaml"  <10>
+    classpath: "META-INF/database.yaml" <11>
+
+----
+
+<1> If configured to `true`, config sources discovered through service loader will be added
+<2> If configured to `true`, converters discovered through service loader will be added
+<3> If configured to `true`, default config sources (system properties, environment variables, and `META-INF/microprofile-config.properties) will be added
+<4> Loads the environment variables config source.
+<5> Loads the system properties config source.
+<6> Loads a properties file
+<7> Location of the file: `/conf/prod.properties` on the file system
+<8> Custom ordinal, if not defined, the value defined in the file, or default value is used. The source precedence order is the order of appearance in the file.
+<9> The file is optional (if not optional and no file is found, the bootstrap fails)
+<10> Loads a YAML file
+<11> Location of the file: `META-INF/database.yaml` on the classpath
 
 == Creating MicroProfile Config Source from Helidon SE Config Source
 
@@ -157,30 +242,16 @@ To use advanced Helidon SE features in Helidon MP, create MicroProfile Config So
 The latest config version is queried each time  `org.eclipse.microprofile.config.spi.ConfigSource#getValue(String)` is called.
 
 ----
+io.helidon.config.Config helidonConfig = io.helidon.config.Config.builder()
+                .addSource(ConfigSources.create(Map.of("key", "value"))) <1>
+                .build();
 ConfigProviderResolver.instance();
 Config config = ConfigProviderResolver.instance()
                 .getBuilder()
-                .withSources(MpConfigSources.create(helidonConfig)) <1>
+                .withSources(MpConfigSources.create(helidonConfig)) <2>
                 .build();
 ----
 
-<1> Creates a MicroProfile config instance using Helidon Config.
-
-
-== Create Yaml MicroProfile Config Source Programatically
-
-You can create Yaml Microprofile Config Source from a path or a URL. When you create a MicroProfile instance from the builder,
-the `YamlMpConfigSource` allows you to create a custom Config Source and register
-it with the builder.
-
-
-=== Example
-
-[source,java]
-.Create YamlMPConfigSource from a path 
-----
-ConfigProviderResolver.instance().newBuilder()
-        .withSources(YamlMpConfigSource.create(path))
-        .build()
-----
+<1> Creates a config source from Helidon Config.
+<2> Creates a MicroProfile config instance using Helidon Config.