Building Container Images¶

Generic Customisation¶

Anywhere the line {% block ... %} appears may be modified. The Kolla community have added blocks throughout the Dockerfiles where we think they will be useful, however, operators are free to submit more if the ones provided are inadequate.

The following is an example of how an operator would modify the setup steps within the Horizon Dockerfile.

First, create a file to contain the customisations, for example: template-overrides.j2. In this place the following:

{% extends parent_template %}

# Horizon
{% block horizon_redhat_binary_setup %}
RUN useradd --user-group myuser
{% endblock %}

Then rebuild the horizon image, passing the --template-override argument:

kolla-build --template-override template-overrides.j2 horizon

• For development, run:

python tools/build.py --template-override template-overrides.j2 horizon

Package Customisation¶

Packages installed as part of an image build can be overridden, appended to, and deleted. Taking the Horizon example, the following packages are installed as part of a binary install type build:

• openstack-dashboard
• httpd
• python2-mod_wsgi or python3-mod_wsgi
• mod_ssl
• gettext

To add a package to this list, say, iproute, first create a file, for example, template-overrides.j2. In this place the following:

{% extends parent_template %}

# Horizon
{% set horizon_packages_append = ['iproute'] %}

Then rebuild the horizon image, passing the --template-override argument:

kolla-build --template-override template-overrides.j2 horizon

• For development, run:

python tools/build.py --template-override template-overrides.j2 horizon

Alternatively template_override can be set in kolla-build.conf.

The append suffix in the above example carries special significance. It indicates the operation taken on the package list. The following is a complete list of operations available:

override

Replace the default packages with a custom list.

append

Add a package to the default list.

remove

Remove a package from the default list.

Using a different base image¶

Base-image can be specified by argument --base-image. For example:

kolla-build --base-image registry.access.redhat.com/rhel7/rhel --base rhel

Plugin Functionality¶

The Dockerfile customisation mechanism is also useful for adding/installing plugins to services. An example of this is Neutron’s third party L2 drivers.

The bottom of each Dockerfile contains two blocks, image_name_footer, and footer. The image_name_footer is intended for image specific modifications, while the footer can be used to apply a common set of modifications to every Dockerfile.

For example, to add the networking-cisco plugin to the neutron_server image, one may want to add the following to the template-override file:

{% extends parent_template %}

{% block neutron_server_footer %}
RUN git clone https://git.openstack.org/openstack/networking-cisco \
    && pip --no-cache-dir install networking-cisco
{% endblock %}

Astute readers may notice there is one problem with this however. Assuming nothing else in the Dockerfile changes for a period of time, the above RUN statement will be cached by Docker, meaning new commits added to the Git repository may be missed on subsequent builds. To solve this the Kolla build tool also supports cloning additional repositories at build time, which will be automatically made available to the build, within an archive named plugins-archive.

To use this, add a section to /etc/kolla/kolla-build.conf in the following format:

[<image>-plugin-<plugin-name>]

Where <image> is the image that the plugin should be installed into, and <plugin-name> is the chosen plugin identifier.

Continuing with the above example, add the following to /etc/kolla/kolla-build.conf:

[neutron-server-plugin-networking-cisco]
type = git
location = https://git.openstack.org/openstack/networking-cisco
reference = master

The build will clone the repository, resulting in the following archive structure:

plugins-archive.tar
|__ plugins
    |__networking-cisco

The template now becomes:

{% block neutron_server_footer %}
ADD plugins-archive /
pip --no-cache-dir install /plugins/*
{% endblock %}

Many of the Dockerfiles already copy the plugins-archive to the image and install available plugins at build time.

Additions Functionality¶

The Dockerfile customisation mechanism is also useful for adding/installing additions into images. An example of this is adding your jenkins job build metadata (say formatted into a jenkins.json file) into the image.

Similarly to the plugins mechanism, the Kolla build tool also supports cloning additional repositories at build time, which will be automatically made available to the build, within an archive named additions-archive. The main difference between plugins-archive and additions-archive is that plugins-archive is copied to the relevant images and processed to install available plugins while additions-archive processing is left to the Kolla user.

To use this, add a section to /etc/kolla/kolla-build.conf in the following format:

[<image>-additions-<additions-name>]

Where <image> is the image that the plugin should be installed into, and <additions-name> is the chosen additions identifier.

Continuing with the above example, add the following to /etc/kolla/kolla-build.conf file:

[neutron-server-additions-jenkins]
type = local
location = /path/to/your/jenkins/data

The build will copy the directory, resulting in the following archive structure:

additions-archive.tar
|__ additions
    |__jenkins

Alternatively, it is also possible to create an additions-archive.tar file yourself without passing by /etc/kolla/kolla-build.conf in order to use the feature for binary build type.

The template now becomes:

{% block neutron_server_footer %}
ADD additions-archive /
RUN cp /additions/jenkins/jenkins.json /jenkins.json
{% endblock %}

Custom Repos¶

Red Hat¶

The build method allows the operator to build containers from custom repos. The repos are accepted as a list of comma separated values and can be in the form of .repo, .rpm, or a url. See examples below.

Update rpm_setup_config in /etc/kolla/kolla-build.conf:

rpm_setup_config = https://trunk.rdoproject.org/centos7/currrent/delorean.repo,https://trunk.rdoproject.org/centos7/delorean-deps.repo

If specifying a .repo file, each .repo file will need to exist in the same directory as the base Dockerfile (kolla/docker/base):

rpm_setup_config = epel.repo,delorean.repo,delorean-deps.repo

Ubuntu¶

For Debian based images, additional apt sources may be added to the build as follows:

apt_sources_list = custom.list

Kolla-ansible with Local Registry¶

To make kolla-ansible pull images from a local registry, set "docker_registry" to "172.22.2.81:5000" in "/etc/kolla/globals.yml". Make sure Docker is allowed to pull images from insecure registry. See Docker Insecure Registry.

Building behind a proxy¶

We can insert http_proxy settings into the images to fetch packages during build, and then unset them at the end to avoid having them carry through to the environment of the final images. Note however, it’s not possible to drop the info completely using this method; it will still be visible in the layers of the image.

To set the proxy settings, we can add this to the template’s header block:

ENV http_proxy=https://evil.corp.proxy:80
ENV https_proxy=https://evil.corp.proxy:80

To unset the proxy settings, we can add this to the template’s footer block:

ENV http_proxy=""
ENV https_proxy=""

Besides this configuration options, the script will automatically read these environment variables. If the host system proxy parameters match the ones going to be used, no other input parameters will be needed. These are the variables that will be picked up from the user env:

HTTP_PROXY, http_proxy, HTTPS_PROXY, https_proxy, FTP_PROXY,
ftp_proxy, NO_PROXY, no_proxy

Also these variables could be overwritten using --build-args, which have precedence.