Directory Config Source

Configuration

Config Directory can be configured by using Admin Console or Asadmin commands.

Using the Admin Console

To configure the Config Directory in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Config → Directory:

Set Config Property

Using Asadmin Commands

set-config-dir

Unresolved include directive in modules/ROOT/pages/Technical Documentation/MicroProfile/Config/Directory.adoc - include::partial$tech-preview.adoc[]

Usage

asadmin> set-config-dir --directory=<full.path.to.dir> --target=<target[default:server]>

Aim

Sets the directory to be used for the directory config source.

  • Leaf directory cannot 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 <PAYARA-HOME>/glassfish/domains/<DOMAIN>/)

  • Defaults to secrets, targeting <PAYARA-HOME>/glassfish/domains/<DOMAIN>/secrets/

After setting via asadmin, you will need to restart the application server to reinitialize the config source!
Command Options
Option Description Default Mandatory

directory

Full path to the directory containing configuration files. Leaf directory name cannot start with a dot.

secrets

yes

target

The target configuration where the command should be run

server-config

no
Example
asadmin> set-config-dir
    --directory=/home/payara/secrets
    --target=myAppCluster

get-config-dir

Unresolved include directive in modules/ROOT/pages/Technical Documentation/MicroProfile/Config/Directory.adoc - include::partial$tech-preview.adoc[]

Usage

asadmin> get-config-dir --target=<target[default:server]>

Aim

Gets the value of the directory to be used for the directory config source.

Command Options
Option Description Default Mandatory

target

The target configuration where the command should be run

server-config

no
Example
asadmin> get-config-dir --target=myAppCluster

Using Preboot or Postboot Scripts

When running a Payara Platform distribution in a container, there is no way to restart a running instance after configuring via an asadmin command without losing the changes to the domain configuration.

Thus you should add the corresponding command to a boot script as described at Pre- and Postboot scripts.

See Payara Server Docker Image environment variables for details how to use this within non-micro containers.

Usage

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 file names correspond to properties in your codebase.

Map property names to flat file hierarchy

  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.

Remember that the files may only contain the secret or other configuration values. Plaintext files only, no file extensions allowed.

Map property names to a sub-directory structure

  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.

Restrictions on the files content are the same as with the flat hierarchy.

Updates to files and subdirectories are picked up at runtime. Retrieving the config property again 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.

Symbolic links will be followed, so you can expose files from such hidden areas, allowing for all types of mangling with names etc. Don’t link to directories, as the file monitors rely on real directories.

Kubernetes Example

You want to retrieve a (secret) value via property foo.bar.property1:

@ConfigProperty("foo.bar.property1")

You deployed a secret to your Kubernetes cluster:

apiVersion: v1
kind: Secret
metadata:
  name: foobar
type: Opaque
stringData:
  property1: my-super-secret-value

And your pod mounts it at /home/payara/secrets/foo/bar (only showing the relevant parts from the Deployment K8s YAML):

volumeMounts:
  - name: test-secrets
    mountPath: /home/payara/secrets/foo/bar
volumes:
  - name: test-secret
    secret:
      secretName: foobar
/ # 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 ..
drwxr-xr-x 2 root root   80 Nov 25 10:51 ..2020_11_25_10_51_55.283009570
lrwxrwxrwx 1 root root   31 Nov 25 10:51 ..data -> ..2020_11_25_10_51_55.283009570
lrwxrwxrwx 1 root root   15 Nov 25 10:51 property1 -> ..data/property1

The server instance will pick up the file and read its content as a value for property foo.bar.property1