Document Kolla image API
A first shot at documenting the kolla image API. Not perfect but this should at least provide a good overview for the projects that want to consume kolla images. Change-Id: I10943a050e4d21dfcdebb75084a26c12845d322b
This commit is contained in:
Martin André
Mark Goddard
parent
1e2db34c7f
commit
1b0f4197f9
@ -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
|
||||
|
||||
174
doc/source/admin/kolla_api.rst
Normal file
174
doc/source/admin/kolla_api.rst
Normal file
@ -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, ...)
|
||||
Loading…
Reference in New Issue
Block a user