1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.. _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``.
* **exclude**: array of names of the directories or files to be excluded when
``recurse`` is set to ``true``. Supports Python regular expressions.
Defaults to empty array.
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,
"exclude": ["/var/log/^snapshot.*"]
}
]
}
Passing the configuration file to the container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The configuration to the container can be passed through a dedicated path:
``/var/lib/kolla/config_files/config.json``.
It is advised to ensure this path is mounted read-only for security reasons.
Mounting the configuration file in the container:
.. code-block:: console
docker run -e KOLLA_CONFIG_STRATEGY=COPY_ALWAYS \
-v /path/to/config.json:/var/lib/kolla/config_files/config.json:ro \
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_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_UPGRADE_CHECK**: if set, and supported by the image, runs the
``<service>-status upgrade check`` command, defined in the images
``extend_start.sh`` scripts. Currently, this is hard-coded to just
``nova-status upgrade check``. 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://opendev.org/openstack/kolla/src/branch/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)
|
