doc: new configuration explained

docs/modules/ROOT/nav.adoc

@@ -18,11 +18,14 @@
 * xref:cli/cli.adoc[CLI]
 ** xref:cli/modeline.adoc[Modeline]
 * xref:configuration/configuration.adoc[Configuration]
-** xref:configuration/maven.adoc[Maven]
+** xref:configuration/build-time-properties.adoc[Build time properties]
 ** xref:configuration/components.adoc[Components]
 ** xref:configuration/logging.adoc[Logging]
 ** xref:configuration/dependencies.adoc[Dependencies]
-** xref:configuration/configmap-secret.adoc[ConfigMap/Secret]
+** xref:configuration/runtime-properties.adoc[Properties]
+** xref:configuration/runtime-config.adoc[Runtime configuration]
+** xref:configuration/runtime-resources.adoc[Runtime resources]
+** xref:configuration/maven.adoc[Maven]
 * Observability
 ** xref:observability/monitoring.adoc[Monitoring]
 *** xref:observability/operator.adoc[Operator]

docs/modules/ROOT/pages/cli/cli.adoc

@@ -69,9 +69,9 @@ While each command has a dedicated set of flags, there are global flags that are
 |===
 |Flag |Description |Example
 
-|`--config PATH`
+|`--kube-config PATH`
 |Path to the config file to use for CLI requests
-|kamel install --config ~/.kube/config
+|kamel install --kube-config ~/.kube/config
 
 |`-h` or `--help`
 |Help for `kamel`, or the command

docs/modules/ROOT/pages/configuration/build-time-properties.adoc

@@ -0,0 +1,56 @@
+[[build-time-props]]
+= Build time properties
+
+You may be required to provide certain *build-time properties* that are needed only during the process of `Integration` building. Since Camel K version 1.5, we introduced a `--build-property` flag that will be handful in such circumstances. The property value may be also used inside Camel K integrations using the *property placeholder* mechanism.
+
+[[build-time-single-prop]]
+== Single property
+
+You will find this feature very useful when dealing with configuration that affects how `Quarkus` builds the `Integration`. For example, let's see how to override the default `quarkus.application.name` expected by any `Quarkus` application:
+
+[source,groovy]
+.build-property-route.groovy
+----
+from('timer:build-property')
+    .log('The application name: {{quarkus.application.name}}')
+----
+
+In order to give a value to the `quarkus.application.name` property you can pass it using the command line with the `--build-property` flag:
+
+----
+kamel run --build-property=quarkus.application.name=my-super-application build-property-route.groovy --dev
+----
+
+You can provide more than one single `build-property` at once by just adding the flag repeatedly (ie, `--build-property=prop1=val1 --build-property=prop2=val2 ...`)
+
+[[build-time-props-file]]
+== Property File
+
+Repeating the property flag when you have many *build time configuration* may be cumbersome. Usually you deal with property files instead. You will be able to use the _file_ syntax available for `--build-property` flag. Here, as an example you have a property files with 2 `Quarkus` properties:
+
+[source,properties]
+.quarkus.properties
+----
+quarkus.application.name = my-super-application
+quarkus.banner.enabled = true
+----
+
+[source,groovy]
+.build-property-route.groovy
+----
+from('timer:build-property')
+    .log('The application name: {{quarkus.application.name}}')
+----
+
+The `quarkus.banner.enabled` is configured to show the banner during the `Integration` startup. Let's use `--build-property` flag in conjunction with file:
+
+----
+kamel run --build-property=file:quarkus.properties build-property-file-route.groovy --dev
+----
+
+The property file is parsed and its properties configured on the `Integration`. As soon as the application starts, you will see the log with the expected configuration.
+
+[[build-time-runtime-conf]]
+== Run time properties
+
+If you're looking for *runtime properties configuration* you can look at the xref:configuration/runtime-properties.adoc[runtime properties] section.

docs/modules/ROOT/pages/configuration/configuration.adoc

@@ -1,7 +1,7 @@
 [[configuration]]
 = Configure Integrations
 
-Properties associated to an integration can be configured either using a ConfigMap/Secret or by setting using the `--property` flag when running the integration.
+Runtime properties associated to an integration can be configured using the `--property` flag when running the integration. If the property is a *build time property* (ie, certain `Quarkus` configuration), then, you can use xref:configuration/build-time-properties.adoc[`--build-property`] instead.
 
 The property value can be used inside Camel K integrations using the *property placeholder* mechanism.
 
@@ -20,4 +20,4 @@ In order to give a value to the `my.message` property you can pass it using the
 kamel run --property my.message="Hello World" examples/props.js
 ```
 
-An alternative, is to provide a value using a Kubernetes xref:configuration/configmap-secret.adoc[ConfigMap or Secret]
+For more details and advanced use cases, see the xref:configuration/runtime-properties.adoc[runtime properties] section.

docs/modules/ROOT/pages/configuration/runtime-config.adoc

@@ -0,0 +1,135 @@
+[[runtime-config]]
+= Runtime configuration
+
+When you develop an integration with `Camel-K` there are many ways you can provide a *configuration* resource to the runtime `Integration`. The most familiar way is to handle local file, but since we are dealing with `Kubernetes` you may need also to use `Configmap` or `Secret`. The `kamel run` command is provided with a `--config` flag that help you setting any configuration resource your `Integration` need.
+
+The *runtime configuration* are expected to be `ÙTF-8` resources as they are processed by runtime `Camel Context` and tried to be parsed as property files. These resources are materialized as files in a well known path in the `Ìntegration` `Pod`. They are also made available on the classpath in order to ease their usage directly from the `Route`. If you need to provide a non `UTF-8` (ie, a binary resource) you may look for `--resource` flag instead.
+
+NOTE: the scope of `--config` global option had different meaning prior Camel K version 1.5. The old global `--config` has been replaced with `--kube-config` since Camel K version 1.5.
+
+[[runtime-config-file]]
+== Runtime file configuration
+
+The most classic way to provide a configuration is probably to have a file where you have certain text data stored. In this case you can use the `--config file:/path/to/file` flag that will copy that file and made available at classpath level.
+
+[source,txt]
+.resources-data.txt
+----
+the file body
+----
+
+[source,groovy]
+.config-file-route.groovy
+----
+from('timer:config-file')
+    .setBody()
+        .simple("resource:classpath:resources-data.txt")
+    .log('resource file content is: ${body}')
+----
+
+We are referring to the file expected to be copied somewhere in the classpath, with the same name as the source file. In order to use it, we'll execute the following `--config` _file_ flag command:
+
+----
+kamel run --config file:resources-data.txt config-file-route.groovy --dev
+----
+
+You can provide more than one single `config` at once by just adding the flag repeatedly (ie, `--config file:file1.txt ---config file:file2.txt ...`).
+
+[[runtime-config-configmap]]
+== Runtime configmap configuration
+
+In a `Kubernetes` world we're dealing with `Configmap` that are containing configuration previously stored in the platform. When you need to materialize a `Configmap` into a file configuration available at your `Integration`, you can use the `--config` _configmap_ syntax.
+
+As an example, let's create a `Configmap` named _my-cm_ containing certain information. You can alternatively use any `Configmap` you've already stored in your cluster:
+
+----
+kubectl create configmap my-cm --from-literal=my-configmap-key="configmap content"
+----
+
+We want to use the materialized file in an integration:
+
+[source,groovy]
+.config-configmap-route.groovy
+----
+from('timer:configmap')
+    .setBody()
+        .simple("resource:classpath:my-configmap-key")
+    .log('configmap content is: ${body}')
+----
+
+You can see that we're expecting to use a _my-configmap-key_ file stored somewhere in the classpath. In order to materialize the `Configmap` will be as easy as running the `--config` _configmap_ syntax:
+
+----
+kamel run --config configmap:my-cm config-configmap-route.groovy --dev
+----
+
+As soon as the `Integration` starts, the `Camel-K` operator will take care to mount a volume with the `Configmap`'s content.
+
+NOTE: you can provide a `Configmap` which is not yet available on the cluster. The `Integration` won't start until the resource will be made available.
+
+[[runtime-config-secret]]
+== Runtime secret configuration
+
+We can apply the very same concept seen in the previous section for the Kubernetes `Secret`s.
+
+As an example, let's create a `Secret` named _my-sec_ containing certain information. You can alternatively use any `Secret` you've already stored in your cluster:
+
+----
+kubectl create secret generic my-sec --from-literal=my-secret-key="very top secret"
+----
+
+We want to use the materialized secret file in an integration:
+
+[source,groovy]
+.config-secret-route.groovy
+----
+from('timer:secret')
+    .setBody()
+        .simple("resource:classpath:my-secret-key")
+    .log('secret content is: ${body}')
+----
+
+You can see that we're expecting to use a _my-secret-key_ file stored somewhere in the classpath. In order to materialize the `Secret` will be as easy as running the `--config` _secret_ syntax:
+
+----
+kamel run --config secret:my-sec config-secret-route.groovy --dev
+----
+
+As soon as the `Integration` starts, the `Camel-K` operator will take care to mount a volume with the `Secret`'s content.
+
+NOTE: you can provide a `Secret` which is not yet available on the cluster. The `Integration` won't start until the resource will be made available.
+
+[[runtime-config-keys]]
+== Configmap/Secret key filtering
+
+When you deal with `Configmap` or `Secret`, you may want to limit the quantity of information to recover from such resources. Both `Configmap` and `Secret` can hold more than one resource in the same unit. For this reason you will find a _key_ filtering feature available in the `--config` flag. In order to use it, you can add a _/key_ notation after the `Configmap` or `Secret` name (ie, `--config configmap:my-cm/my-key`).
+
+Let's see an example with multiple `Secret` in action. The very same concept can be easily applied to `Configmap`. We start creating a `Secret` containing multiple resources:
+
+----
+kubectl create secret generic my-sec-multi --from-literal=my-secret-key="very top secret" --from-literal=my-secret-key-2="even more secret"
+----
+
+In our `Integration` we plan to use only one of the resources of the `Secret`:
+
+[source,groovy]
+.config-secret-key-route.groovy
+----
+from('timer:secret')
+    .setBody()
+        .simple("resource:classpath:my-secret-key-2")
+    .log('secret content is: ${body}')
+----
+
+Let's use the _key_ filtering:
+
+----
+kamel run --config secret:my-sec-multi/my-secret-key-2 config-secret-key-route.groovy --dev
+----
+
+You may check in the `Integration` `Pod` that only the _my-secret-key-2_ file has been mounted.
+
+[[runtime-config-resources]]
+== Runtime resources
+
+If you're looking for *runtime resources* (ie, binary resources) you can look at the xref:configuration/runtime-resources.adoc[runtime resources] section.