diff --git a/ansible/group_vars/all/kolla b/ansible/group_vars/all/kolla index b50df3ecc..3f9c0c4bd 100644 --- a/ansible/group_vars/all/kolla +++ b/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. diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 99cf36dcc..7493a4ab4 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -9,4 +9,5 @@ Configuration Guide physical-network network hosts + kolla kolla-ansible diff --git a/doc/source/configuration/kolla.rst b/doc/source/configuration/kolla.rst new file mode 100644 index 000000000..c6e09e995 --- /dev/null +++ b/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 +`__. + +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_`` 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 +`__ +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 +`__ +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 +`__ +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 +`__ +and `additions +`__ +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. diff --git a/etc/kayobe/kolla.yml b/etc/kayobe/kolla.yml index ad35f10cc..42eef890b 100644 --- a/etc/kayobe/kolla.yml +++ b/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.