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

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

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