Add docs on building images

Change-Id: I0074b8ef2153813b3ffdd5e8254d76df25e49302
Story: 2004337
Task: 28486

ansible/group_vars/all/kolla

@@ -55,7 +55,7 @@ kolla_node_custom_config_path: "{{ kolla_config_path }}/config"
 # Kolla base container image distribution.
 kolla_base_distro: "centos"
 
-# Kolla installation type: binary or source.
+# Kolla container image type: binary or source.
 kolla_install_type: "binary"
 
 # Docker namespace to use for Kolla images.

doc/source/configuration/index.rst

@@ -9,4 +9,5 @@ Configuration Guide
    physical-network
    network
    hosts
+   kolla
    kolla-ansible

doc/source/configuration/kolla.rst

@@ -0,0 +1,310 @@
+===================
+Kolla Configuration
+===================
+
+Anyone using Kayobe to build images should familiarise themselves with the
+`Kolla project's documentation
+<https://docs.openstack.org/kolla/latest/>`__.
+
+Container Image Build Host
+==========================
+
+Images are built on hosts in the ``container-image-builders`` group. The
+default Kayobe Ansible inventory places the seed host in this group, although
+it is possible to put a different host in the group, by modifying the
+inventory.
+
+For example, to build images on ``localhost``:
+
+.. code-block:: console
+   :caption: ``inventory/groups``
+
+   [container-image-builders:children]
+
+.. code-block:: console
+   :caption: ``inventory/hosts``
+
+   [container-image-builders]
+   localhost
+
+Kolla Installation
+==================
+
+Prior to building container images, Kolla and its dependencies will be
+installed on the container image build host. The following variables affect the
+installation of Kolla:
+
+``kolla_ctl_install_type``
+    Type of installation, either ``binary`` (PyPI) or ``source`` (git). Default
+    is ``source``.
+``kolla_source_path``
+    Path to directory for Kolla source code checkout. Default is ``{{
+    source_checkout_path ~ '/kolla' }}``.
+``kolla_source_url``
+    URL of Kolla source code repository if type is ``source``. Default is
+    https://git.openstack.org/openstack/kolla.
+``kolla_source_version``
+    Version (branch, tag, etc.) of Kolla source code repository if type is
+    ``source``. Default is the same as the Kayobe upstream branch name.
+``kolla_venv``
+    Path to virtualenv in which to install Kolla on the container image build
+    host. Default is ``{{ virtualenv_path ~ '/kolla' }}``.
+``kolla_build_config_path``
+    Path in which to generate kolla configuration. Default is ``{{ config_path
+    ~ '/kolla' }}``.
+
+For example, to install from a custom Git repository:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_source_url: https://git.example.com/kolla
+   kolla_source_version: downstream
+
+Global Configuration
+====================
+
+The following variables are global, affecting all container images. They are
+used to generate the Kolla configuration file, ``kolla-build.conf``.
+
+``kolla_base_distro``
+    Kolla base container image distribution. Default is ``centos``.
+``kolla_install_type``
+    Kolla container image type: ``binary`` or ``source``. Default is
+    ``binary``.
+``kolla_docker_namespace``
+    Docker namespace to use for Kolla images. Default is ``kolla``.
+``kolla_docker_registry``
+    URL of docker registry to use for Kolla images. Default is not set, in
+    which case Dockerhub will be used.
+``kolla_docker_registry_username``
+    Username to use to access a docker registry. Default is not set, in which
+    case the registry will be used without authentication.
+``kolla_docker_registry_password``
+    Password to use to access a docker registry. Default is not set, in which
+    case the registry will be used without authentication.
+``kolla_openstack_release``
+    Kolla OpenStack release version. This should be a Docker image tag. Default
+    is the OpenStack release name (e.g. ``rocky``) on stable branches and
+    tagged releases, or ``master`` on the Kayobe ``master`` branch.
+
+For example, to build the Kolla ``centos`` ``binary`` images with a namespace
+of ``example``, and a private Docker registry at ``registry.example.com:4000``,
+tagged with ``7.0.0.1``:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_base_distro: centos
+   kolla_install_type: binary
+   kolla_docker_namespace: example
+   kolla_docker_registry: registry.example.com:4000
+   kolla_openstack_release: 7.0.0.1
+
+The ``ironic-api`` image built with this configuration would be referenced as
+follows:
+
+.. code-block:: console
+
+   registry.example.com:4000/example/centos-binary-ironic-api:7.0.0.1
+
+Further customisation of the Kolla configuration file can be performed by
+writing a file at ``${KAYOBE_CONFIG_PATH/kolla/kolla-build.conf``. For example,
+to enable debug logging:
+
+.. code-block:: ini
+   :caption: ``kolla/kolla-build.conf``
+
+   [DEFAULT]
+   debug = True
+
+Seed Images
+===========
+
+The ``kayobe seed container image build`` command builds images for the seed
+services. The only image required for the seed services is the
+``bifrost-deploy`` image.
+
+Overcloud Images
+================
+
+The ``kayobe overcloud container image build`` command builds images for the
+control plane.  The default set of images built depends on which services and
+features are enabled via the ``kolla_enable_<service>`` flags in
+``$KAYOBE_CONFIG_PATH/kolla.yml``.
+
+For example, the following configuration will enable the Magnum service and add
+the ``magnum-api`` and ``magnum-conductor`` containers to the set of overcloud
+images that will be built:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_enable_magnum: true
+
+If a required image is not built when the corresponding flag is set, check the
+image sets defined in ``overcloud_container_image_sets`` in
+``ansible/group_vars/all/kolla``.
+
+Image Customisation
+===================
+
+There are three main approaches to customising the Kolla container images:
+
+#. Overriding Jinja2 blocks
+#. Overriding Jinja2 variables
+#. Source code locations
+
+Overriding Jinja2 blocks
+------------------------
+
+Kolla's images are defined via Jinja2 templates that generate Dockerfiles.
+Jinja2 blocks are frequently used to allow specific statements in one or more
+Dockerfiles to be replaced with custom statements. See the `Kolla documentation
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#generic-customisation>`__
+for details.
+
+Blocks are configured via the ``kolla_build_blocks`` variable, which is a dict
+mapping Jinja2 block names in to their contents.
+
+For example, to override the block ``header`` to add a custom label to every
+image:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_build_blocks:
+     header: |
+       LABEL foo="bar"
+
+This will result in Kayobe generating a ``template-override.j2`` file with the
+following content:
+
+.. code-block:: console
+   :caption: ``template-override.j2``
+
+   {% extends parent_template %}
+
+   {% block header %}
+   LABEL foo="bar"
+   {% endblock %}
+
+Overriding Jinja2 variables
+---------------------------
+
+Jinja2 variables offer another way to customise images.  See the `Kolla
+documentation
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#package-customisation>`__
+for details of using variable overrides to modify the list of packages to
+install in an image.
+
+Variable overrides are configured via the ``kolla_build_customizations``
+variable, which is a dict/map mapping names of variables to override to their
+values.
+
+For example, to add ``mod_auth_openidc`` to the list of packages installed in
+the ``keystone-base`` image, we can set the variable
+``keystone_base_packages_append`` to a list containing ``mod_auth_openidc``.
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_build_customizations:
+     keystone_base_packages_append:
+       - mod_auth_openidc
+
+This will result in Kayobe generating a ``template-override.j2`` file with the
+following content:
+
+.. code-block:: console
+   :caption: ``template-override.j2``
+
+   {% extends parent_template %}
+
+   {% set keystone_base_packages_append = ["mod_auth_openidc"] %}
+
+Note that the variable value will be JSON-encoded in ``template-override.j2``.
+
+Source code locations
+---------------------
+
+For ``source`` image builds, configuration of source code locations for
+packages installed in containers by Kolla is possible via the ``kolla_sources``
+variable. The format is a dict/map mapping names of sources to their
+definitions. See the `Kolla documentation
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#build-openstack-from-source>`__
+for details. The default is to specify the URL and version of Bifrost, as
+defined in ``${KAYOBE_CONFIG_PATH}/bifrost.yml``.
+
+For example, to specify a custom source location for the ``ironic-base``
+package:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_sources:
+     bifrost-base:
+       type: "git"
+       location: "{{ kolla_bifrost_source_url }}"
+       reference: "{{ kolla_bifrost_source_version }}"
+     ironic-base:
+       type: "git"
+       location: https://git.example.com/ironic
+       reference: downstream
+
+This will result in Kayobe adding the following configuration to
+``kolla-build.conf``:
+
+.. code-block:: ini
+   :caption: ``kolla-build.conf``
+
+   [bifrost-base]
+   type = git
+   location = https://git.openstack.org/openstack/bifrost
+   reference = stable/rocky
+
+   [ironic-base]
+   type = git
+   location = https://git.example.com/ironic
+   reference = downstream
+
+Note that is is currently necessary to include the Bifrost source location if
+using a seed.
+
+Plugins & additions
+-------------------
+
+These features can also be used for installing `plugins
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#plugin-functionality>`__
+and `additions
+<https://docs.openstack.org/kolla/latest/admin/image-building.html#additions-functionality>`__
+to ``source`` type images.
+
+For example, to install a ``networking-ansible`` plugin in the
+``neutron-server`` image:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_sources:
+     bifrost-base:
+       type: "git"
+       location: "{{ kolla_bifrost_source_url }}"
+       reference: "{{ kolla_bifrost_source_version }}"
+     neutron-server-plugin-networking-ansible:
+       type: "git"
+       location: https://git.example.com/networking-ansible
+       reference: downstream
+
+The ``neutron-server`` image automatically installs any plugins provided to it.
+For images that do not, a block such as the following may be required:
+
+.. code-block:: yaml
+   :caption: ``kolla.yml``
+
+   kolla_build_blocks:
+     neutron_server_footer: |
+       ADD plugins-archive /
+       pip --no-cache-dir install /plugins/*
+
+A similar approach may be used for additions.

etc/kayobe/kolla.yml

@@ -57,7 +57,7 @@
 # Kolla base container image distribution.
 #kolla_base_distro:
 
-# Kolla installation type: binary or source.
+# Kolla container image type: binary or source.
 #kolla_install_type:
 
 # URL of docker registry to use for Kolla images.