Kolla Images API¶

Format of the configuration file¶

The kolla_set_configs script understands the following attributes:

• command (required): the command the container runs once it finishes the initialization step.
• config_files: copies files and directories inside the container. A list of dicts, each containing the following attributes:
  • source (required): path to the file or directory that needs to be copied. Understands shell wildcards.
  • dest (required): path to where the file or directory will be copied. does not need to exist, destination is deleted if it exists.
  • owner (required, unless preserve_properties is set to true): the user:group to change ownership to. user is synonymous to user:user. Must be user and group names, not uid/gid.
  • perm (required, unless preserve_properties is set to true): the unix permissions to set to the target files and directories. Must be passed in the numeric octal form.
  • preserve_properties: copies the ownership and permissions from the original files and directory. Boolean, defaults to false.
  • optional: do not raise an error when the source file is not present on the filesystem. Boolean, defaults to false.
  • merge: merges the source directory into the target directory instead of replacing it. Boolean, defaults to false.
• permissions: change the permissions and/or ownership of files or directories inside the container. A list of dicts, each containing the following attributes:
  • path (required): the path to the file or directory to update.
  • owner (required): the user:group to change ownership to. user is synonymous to user:user. Must be user and group names, not uid/gid.
  • perm: the unix permissions to set to the target files and directories. Must be passed in the numeric octal form.
  • recurse: whether to apply the change recursively over the target directory. Boolean, defaults to false.

Here is an example configuration file:

{
    "command": "trove-api --config-file=/etc/trove/trove.conf",
    "config_files": [
        {
            "source": "/var/lib/kolla/config_files/trove.conf",
            "dest": "/etc/trove/trove.conf",
            "owner": "trove",
            "perm": "0600",
            "optional": false
        }
    ],
    "permissions": [
        {
            "path": "/var/log/kolla/trove",
            "owner": "trove:trove",
            "recurse": true
        }
    ]
}

Passing the configuration file to the container¶

The configuration can be either passed via the KOLLA_CONFIG environment variable or as a file bind-mounted into the container. When bind-mounting the configuration file, the KOLLA_CONFIG_FILE environment variable controls where the file is located in the container, the default path being /var/lib/kolla/config_files/config.json.

Passing the configuration file as environment variable:

docker run -e KOLLA_CONFIG_STRATEGY=COPY_ALWAYS \
    -e KOLLA_CONFIG='{ "command": "...", "permissions": [ { "path": "...", } ] }' \
    kolla-image

Mounting the configuration file in the container:

docker run -e KOLLA_CONFIG_STRATEGY=COPY_ALWAYS \
    -e KOLLA_CONFIG_FILE=/config.json \
    -v /path/to/config.json:/config.json kolla-image

Variables to pass to the containers¶

The Kolla containers also understand some environment variables to change their behavior at runtime:

• KOLLA_CONFIG: load kolla config from the environment, takes precedence over KOLLA_CONFIG_FILE.
• KOLLA_CONFIG_FILE: path to kolla json config file, defaults to /var/lib/kolla/config_files/config.json.
• KOLLA_CONFIG_STRATEGY (required): Defines how the kolla_start script copies the configuration file. Must be one of:
  • COPY_ONCE: the configuration files are copied just once, the first time the container is started. In this scenario the container is perfectly immutable.
  • COPY_ALWAYS: the configuration files are copied each time the container starts. If a config file changes on the host, the change is applied in the container the next time it restarts.
• KOLLA_SKIP_EXTEND_START: if set, bypass the extend_start.sh script. Not set by default.
• KOLLA_SERVICE_NAME: if set, shows the value of the variable on the PS1 inside the container. Not set by default.
• KOLLA_BOOTSTRAP: if set, and supported by the image, runs the bootstrap code defined in the images extend_start.sh scripts. Not set by default.
• KOLLA_UPGRADE: if set, and supported by the image, runs the upgrade code defined in the images extend_start.sh scripts. Not set by default.
• KOLLA_OSM: if set, and supported by the image, runs the online database migration code defined in the images extend_start.sh scripts. Not set by default.

The containers may expose other environment variables for turning features on or off, such as the horizon container that looks for ENABLE_XXX variables where XXX is a horizon plugin name. These are generally defined in the container-specific extend_start.sh script, example for horizon.

Variables available in the containers¶

The following variables available in all images and can be evaluated in scripts:

• KOLLA_BASE_DISTRO: base_distro used to build the image (e.g. centos, ubuntu)
• KOLLA_INSTALL_TYPE: install_type used to build the image (binary, source)
• KOLLA_INSTALL_METATYPE: install_metatype used to build the image (rdo, …)