Kolla Images API¶

Kolla offers two different ways to make changes to containers at runtime. The first is via a configuration file exposed to the container and processed by the init scripts, and the second is via more traditional environment variables.

External Config¶

All of the Kolla images understand a JSON-formatted configuration describing a set of actions the container needs to perform at runtime before it executes the (potentially) long running process. This configuration also specifies the command to execute to run the service.

When a container runs kolla_start, the default entry-point, it processes the configuration file using kolla_set_configs with escalated privileges, meaning it is able to set file ownership and permissions.

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

Environment Variables¶

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, …)

Kolla Images API