Configuration Format

Edit online

The configuration of a container can either be included in the YAML configuration file, or can be specified by using environment variables.

Note:

The supported configuration entries for each of the Verify Directory containers can be found in the YAML Specification.
In a noncontainerized environment, use the LDAP modify operations to modify the configuration. LDAP modify operations must not be used to modify the configuration of a container, otherwise the configuration changes are lost when the container restarts.

YAML Configuration

Specifying the configuration file

The YAML configuration must be present in a file that is available on the container file system. The name of the YAML configuration file is specified by setting the YAML_CONFIG_FILE environment variable within the container.

In a Kubernetes environment a ConfigMap can be created to store the configuration information, as depicted in the following example.

apiVersion: v1 
kind: ConfigMap 

metadata: 
  name: isvd-config 
  namespace: default 

data: 
  config.yaml: | 
    general: 
      id: test-server
      license:
        key: "insert-valid-license-key-here"
        accept: standard
      admin: 
        pwd: passw0rd1

    server:
      suffixes:
      - dn: dc=ibm.com

A container in a Kubernetes environment can be created to use the configuration found within the ConfigMap with the following deployment descriptor.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: isvd-server

spec:
  selector:
    matchLabels:
      app: isvd-server

  template:
    metadata:
      labels:
        app: isvd-server

    spec:
      containers:
      - name: isvd-server
        image: icr.io/isvd/verify-directory-server:latest

        env:
        - name: YAML_CONFIG_FILE
          value: /var/isvd/config.yaml

        volumeMounts:
        - name: config-volume
          mountPath: /var/isvd/config.yaml
          subPath: config.yaml

      volumes:
      - name: config-volume
        configMap:
          name: isvd-config

Special Types

A number of special types exist that can be used in addition to plain text within the YAML file. These special types can be used to substitute values from alternative sources.

Table 1. YAML value types
Type	Syntax	Example
Environment Variable	`$<environment variable>`	`$id`
External File	`"@<file name>"`	`"@/var/config/cert.pem"`
Base64 Encoded Data	`B64:<base64 encoded string>`	`B64:VGVzdAo=`
Kubernetes ConfigMap	`configmap:<config map name>/<config map field>`	`configmap:map-name/key`
Kubernetes Secret	`secret:<secret name>/<secret field>`	`secret:secret-name/key`

Example Environment Variable

The following example shows how a value that is stored in an environment variable can be used in the configuration YAML. In this example, the license key is loaded from an environment variable.

The environment variable MY_LICENSE_KEY is set in the container context:

MY_LICENSE_KEY=exampleOnlyDoNotUseThisValue

A configuration YAML document can indicate that this value must be loaded from the environment variable by specifying $MY_LICENSE_KEY as a value.

general:
...
  license:
    key: $MY_LICENSE_KEY
...

This action is equivalent to specifying the value as-is within the YAML configuration data.

general:
...
  license:
    key: exampleOnlyDoNotUseThisValue
...

Example File Reference

The following example shows how a file reference can be used to source content from an external file. In this example, a certificate is loaded from an external file.

The following file is present in the configuration directory /var/isvd/config.

my_cert.pem

In this example, my_cert.pem contains a PEM formatted certificate.

In the configuration file, the content of my_cert.pem is included by specifying "@/var/isvd/config/my_cert.pem" as a value.

key-file:
...
  trusted-certificates: 
    - "@/var/isvd/config/my_cert.pem"
...

Note: A file reference must always be surrounded by quotations as the @ character cannot appear at the beginning of an unquoted YAML value.

Example Base 64 Data

For some types of data, it is not practical to store the value as text within the configuration YAML. In some scenarios, it is useful to be able to embed all data within a single configuration YAML document. In these cases, the values can be base 64 encoded and embedded as values within the configuration YAML.

The following example shows how a certificate can be embedded in the configuration YAML as base 64 encoded data.

First, generate the base 64 representation of the certificate. On macOS and other UNIX-like systems this action can be achieved with the base64 command.

$ base64 my_cert.pem
PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHhzbDpzdHlsZXNoZWV0IHht
...

In the configuration YAML, this data can be placed on a single line that is preceded by the B64: prefix.

key-file:
  ...
    trusted-certificates:
      - B64:PD94bWwgdmVyc2lvbj0i...
...

Example Kubernetes ConfigMap

The Kubernetes ConfigMap type can be used to directly reference a field from a particular ConfigMap within the configuration YAML. During bootstrapping, the container uses the Kubernetes REST API endpoints to retrieve the ConfigMap and substitute the value into the configuration YAML.

Consider the following ConfigMap that is named admin-creds containing the fields dn and password.

apiVersion: v1
kind: ConfigMap
metadata:
  name: admin-creds
  ...
data:
  dn: cn=root
  password: passw0rd

To reference these values within the configuration YAML, use the syntax for the Kubernetes ConfigMap type.

general:
  admin:
    dn: "configmap:admin-creds/dn"
    pwd: "configmap:admin-creds/password"
...

During bootstrapping, the container retrieves the ConfigMap and substitutes it into the configuration YAML.

general:
  admin:
    dn: "cn=root"
    pwd: "passw0rd"
...

Example Kubernetes Secret

The Kubernetes Secret type can be used to directly reference a field from a particular secret within the configuration YAML. During bootstrapping, the container uses the Kubernetes REST API endpoints to retrieve the secret and substitute the secret value into the configuration YAML.

Consider the following secret that is named admin-creds containing the fields dn and password.

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: admin-creds
  ...
data:
  dn:       Y249cm9vdAo=
  password: cGFzc3cwcmQK

To reference these values within the configuration YAML, use the syntax for the Kubernetes Secret type.

general:
  admin:
    dn: "secret:admin-creds/dn"
    pwd: "secret:admin-creds/password"
...

During bootstrapping, the container retrieves the secret, base64 decodes the data and substitutes it into the configuration YAML.

general:
  admin:
    dn: "cn=root"
    pwd: "passw0rd"
...

Environment Variables

Each of the configuration entries can also be set by an environment variable, by using a normalized version of the configuration entry name. Separate each element within the configuration entry name by a period (.), and surround array subscripts by brackets ([]). For example, the following YAML extract can be used to set the identifier of the container.

general:
  id: my-server-id

This identifier might also be set by using the following environment variable name in the container context: general.id.

Note: A configuration entry that is set by an environment variable takes precedence over a configuration entry that is included in the YAML file.