From c8596f6d4e44a62155d7b55c4c2064fea9a6b60c Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 28 Jan 2021 17:16:29 +0100 Subject: [PATCH] docs(mpconfig): Match directory config source docs to current functionality. This doc change aligns the docs with the new implementation of the directory config source for MicroProfile Config API. - See PR https://github.com/payara/Payara/pull/5007 - Internal ticket FISH-788 --- .../microprofile/config/directory.adoc | 78 +++++++++++++------ 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/docs/modules/ROOT/pages/documentation/microprofile/config/directory.adoc b/docs/modules/ROOT/pages/documentation/microprofile/config/directory.adoc index 2d38a4f6..30dd4a5b 100644 --- a/docs/modules/ROOT/pages/documentation/microprofile/config/directory.adoc +++ b/docs/modules/ROOT/pages/documentation/microprofile/config/directory.adoc @@ -1,3 +1,5 @@ +:source-highlighter: rouge + = Directory Config Source == Configuration @@ -24,7 +26,10 @@ include::partial$tech-preview.adoc[] `asadmin> set-config-dir --directory= --target=` *Aim*:: Sets the directory to be used for the directory config source. - +- *Leaf directory may not start with a dot*, rendering `/home/payara/.secret` + an invalid path ("." means hidden on a POSIX filesystem). +- If relative, will lookup beneath server instance location + (usually to be found at `/glassfish/domains//`) ===== Command Options @@ -36,7 +41,8 @@ Sets the directory to be used for the directory config source. |Mandatory |`directory` -|Full path to the directory containing configuration files +|Full path to the directory containing configuration files. + Leaf directory name may not start with a dot. |- |yes @@ -50,10 +56,10 @@ Sets the directory to be used for the directory config source. ===== Example -[source,Shell] +[source] ---- asadmin> set-config-dir - --directory=/home/payara/.secrets + --directory=/home/payara/secrets --target=myAppCluster ---- @@ -87,7 +93,7 @@ Gets the value of the directory to be used for the directory config source. ===== Example -[source,Shell] +[source] ---- asadmin> get-config-dir --target=myAppCluster @@ -101,34 +107,62 @@ Usually this config source is used to map secrets mounted by Kubernetes or Docker to a directory inside a running container. Once you configured a directory to read a config (secrets) from, you need to -make sure properties in your codebase map to files. +make sure file names correspond to properties in your codebase. === Map property names to flat file hierarchy _Since *5.183* _ 1. Say you have two properties `property1` and `foo.bar.property2`. -2. Payara is configured with secret directory `/home/payara/.secrets` -3. Secrets mounted as files to `/home/payara/.secrets/property1` and - `/home/payara/.secrets/foo.bar.property2` will be read. +2. Payara is configured with secret directory `/home/payara/secrets` +3. Secrets mounted as files to `/home/payara/secrets/property1` and + `/home/payara/secrets/foo.bar.property2` will be read. -Remember that the files may only contain the secret, no newline, metadata, etc. +Remember that the files may only contain the secret or other configuration +value - no newlines, metadata, etc! Plaintext files only, no file extensions +allowed. === Map property names to a sub-directory structure -_Since *5.2020.7* _ +_Since *5.2021.1* _ 1. Say you have two properties `property1` and `foo.bar.property2`. -2. Payara is configured with secret directory `/home/payara/.secrets` -3. Secrets mounted as files to `/home/payara/.secrets/property1` and - `/home/payara/.secrets/foo/bar/property2` will be read. - -Usually property scopes are done via "." in their names, reflecting to -subdirectories here. +2. Payara is configured with secret directory `/home/payara/secrets` +3. Secrets mounted as files to `/home/payara/secrets/property1` and + `/home/payara/secrets/foo/bar/property2` will be read. -Remember not to include "." in your file names or they won't be found reliably. Restrictions on the files content are the same as with the flat hierarchy. +Updates to files and subdirectories are picked up at runtime. Re-retrieving +the config property will use the updated values. This allows for clearing +a value by removing the file, too. + +==== Dots usage and depicting directories and file name + +Dots in property names are used to reflect scopes, for example to distinguish +different applications, modules, etc. + +1. Any dots in the property name may correspond to changing from one directory + to a subdirectory. + Example: `foo.bar.test` could be a file `test` in `foo/bar/` path. +2. You may combine any number of dot-separated "components" into directories + and file name. + Example: `foo.bar.test.example` may be a file `test.example` in + `foo/bar/` path or a file `example` in path `foo/bar.test/` and so on. +3. Do not use a file extension, as it would be taken as part of the + property name. +4. The longest, most specific match "wins" for reading the value into the + property. This allows to create scoped directory structures as you see fit. + Example: `foo.bar/test.example` is less specific than `foo/bar/test.example` + and so on. + +You cannot use directories or files whose names start with a dot. They will +be ignored, following the POSIX philosophy of hidden files and folders. + +Symlinks will be followed, so you can expose files from such hidden areas, +allowing for all types of mangling with names etc. (This allows the Kubernetes +Secret mounting magic to happen...) Don't symlink to directories, as the +file monitors rely on real directories. ==== Kubernetes Example @@ -152,23 +186,23 @@ stringData: property1: my-super-secret-value ---- -And your pod mounts it at `/home/payara/.secrets/foo/bar` +And your pod mounts it at `/home/payara/secrets/foo/bar` (only showing the relevant parts from the `Deployment` K8s YAML): [source,Yaml] ---- volumeMounts: - name: test-secrets - mountPath: /home/payara/.secrets/foo/bar + mountPath: /home/payara/secrets/foo/bar volumes: - name: test-secret secret: secretName: foobar ---- -[source,Shell] +[source] ---- -/ # ls -la /home/payara/.secrets/foo/bar +/ # ls -la /home/payara/secrets/foo/bar total 3 drwxrwxrwt 3 root root 120 Nov 25 10:51 . drwxr-xr-x 3 root root 4096 Nov 25 10:51 ..