diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/admin/index.rst | 12 | ||||
| -rw-r--r-- | doc/source/admin/kolla_api.rst | 174 |
2 files changed, 186 insertions, 0 deletions
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 4724b3bb2..d2315fdec 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -16,3 +16,15 @@ or build some images using ``--template-override``. image-building template-override/* + + +Kolla Images API +---------------- + +Take advantage of the Kolla API to configure containers at runtime. + +.. toctree:: + :maxdepth: 2 + :glob: + + kolla_api diff --git a/doc/source/admin/kolla_api.rst b/doc/source/admin/kolla_api.rst new file mode 100644 index 000000000..4c4bd69f5 --- /dev/null +++ b/doc/source/admin/kolla_api.rst @@ -0,0 +1,174 @@ +.. _kolla_api: + +================ +Kolla Images API +================ + +Kolla offers two different ways to make changes to containers at runtime. +The first is via a :ref:`configuration file <kolla_api_external_config>` +exposed to the container and processed by the init scripts, and the second +is via more traditional +:ref:`environment variables <kolla_api_environment_variables>`. + +.. _kolla_api_external_config: + +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. + +.. _kolla_start: https://github.com/openstack/kolla/blob/master/docker/base/start.sh +.. _kolla_set_configs: https://github.com/openstack/kolla/blob/master/docker/base/set_configs.py + +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: + +.. code-block:: json + + { + "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: + +.. code-block:: console + + docker run -e KOLLA_CONFIG_STRATEGY=COPY_ALWAYS \ + -e KOLLA_CONFIG='{ "command": "...", "permissions": [ { "path": "...", } ] }' \ + kolla-image + +Mounting the configuration file in the container: + +.. code-block:: console + + docker run -e KOLLA_CONFIG_STRATEGY=COPY_ALWAYS \ + -e KOLLA_CONFIG_FILE=/config.json \ + -v /path/to/config.json:/config.json kolla-image + +.. _kolla_api_environment_variables: + +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 :ref:`kolla_start + script <kolla_api_external_config>` 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`_. + +.. _horizon: https://github.com/openstack/kolla/blob/master/docker/horizon/extend_start.sh + +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, ...) |