Directory Config Source

This page details how to configure and use the Directory configuration source in the Payara Platform.

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

Use the following commands to configure and get the current settings of this configuration source:

Using Pre-boot and/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 subdirectory 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