构建容器镜像¶

首先，确保 kolla 和您选择的容器引擎已安装。

目前支持的容器引擎有 docker 和 podman。

python3 -m pip install kolla
#only one of these is needed:
python3 -m pip install podman
python3 -m pip install docker

然后，kolla-build 命令可用于构建 Docker 镜像。

构建 kolla 镜像¶

通常，镜像的构建方式如下

kolla-build

默认情况下，上述命令将基于 CentOS Stream 镜像构建所有镜像。

操作员可以使用 -b 选项更改基础分发版

kolla-build -b ubuntu

可用于构建镜像的可用分发版（基础镜像）如下

centos
debian
ubuntu

有关支持的基础镜像分发版版本和每个分发版上支持的镜像的信息，请参阅支持矩阵。

可以通过在命令行中指定它们来仅构建镜像子集

kolla-build keystone

在这种情况下，构建脚本将构建名称包含 keystone 字符串的所有镜像，以及它们的父镜像。

可以在命令行中指定多个名称

kolla-build keystone nova

每个字符串实际上都是一个正则表达式，因此可以执行

kolla-build ^nova-

kolla-build 可以通过 INI 文件进行配置，该文件通常命名为 kolla-build.conf 并放置在 /etc/kolla 中。可以通过 --config-file 参数设置其自定义路径。大多数 CLI 参数都可以通过此配置文件设置。请记住将带有连字符的名称转换为下划线。运行 kolla-build --help 以查看所有可用选项。

可以在 kolla-build.conf 的 profiles 部分中定义要构建的镜像集合作为配置文件。然后，可以通过 --profile CLI 参数或 kolla-build.conf 中的 profile 选项指定配置文件。

例如，由于 Magnum 需要 Heat，因此可以将以下配置文件添加到 kolla-build.conf 的 profiles 部分

[profiles]
magnum = magnum,heat

可以使用命令行构建这些镜像

kolla-build --profile magnum

或者将以下行放在 kolla-build.conf 文件的 DEFAULT 部分

[DEFAULT]
profile = magnum

kolla-build 默认使用 kolla 作为 Docker 命名空间。这可以通过 -n 命令行选项控制。要将镜像推送到名为 mykollarepo 的 Dockerhub 仓库

kolla-build -n mykollarepo --push

要将镜像推送到本地仓库，请使用 --registry 标志

kolla-build --registry 172.22.2.81:4000 --push

从源代码构建 OpenStack¶

OpenStack 源代码的位置在 kolla-build.conf 中编写。源代码的 type 支持 url、git 和 local。 local 类型的源代码的 location 可以指向包含源代码的目录或源代码的 tarball。 local 源代码类型允许充分利用 Docker 缓存。可以通过将 enabled 设置为 False 来禁用源代码。

kolla-build.conf 文件可能如下所示

[horizon]
type = url
location = https://tarballs.openstack.org/horizon/horizon-master.tar.gz

[keystone-base]
type = git
location = https://opendev.org/openstack/keystone
reference = stable/mitaka

[heat-base]
type = local
location = /home/kolla/src/heat

[ironic-base]
type = local
location = /tmp/ironic.tar.gz
enabled = False

注意

请注意，节的名称应与您尝试更改源代码位置的镜像名称完全匹配。

如果使用 local 源代码类型，可以使用 --locals-base 标志定义路径前缀，您可以在配置中引用该前缀。

[DEFAULTS]
locals_base = /home/kolla/src

[heat-base]
type = local
location = $locals_base/heat

Dockerfile 自定义¶

kolla-build 工具提供了一种基于 Jinja2 的机制，允许操作员自定义用于生成 Kolla 镜像的 Dockerfile。

这提供了很大的灵活性来构建镜像，例如：在构建过程中安装额外的软件包、调整设置或安装插件。这些示例在下面详细描述。

注意

每个镜像的 Docker 文件 Jinja2 模板都位于包含在 kolla 包中的 docker 目录的子目录中。

使用不同的基础镜像¶

可以使用 --base-image 指定基础镜像

kolla-build --base-image <image-identifier>

image-identifier 接受 Docker 在引用镜像时接受的任何格式。

通用自定义¶

Kolla 模板的设计使得每个 Docker 文件都有逻辑部分，由 Jinja2 的命名 block 部分指令表示。Kolla 用户可以随意覆盖这些部分。以下是一个操作员如何修改 Horizon Dockerfile 中设置步骤的示例。

首先，创建一个文件来包含自定义内容，例如： template-overrides.j2。用以下内容填充它

{% extends parent_template %}

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

然后使用命令行重新构建 horizon 镜像，传递 --template-override 参数

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

注意

上面的示例将替换原始块的所有内容。因此，您可能需要在修改之前复制原始块的内容。请注意，这会使自定义内容忽略 Kolla 上游的更改。

我们建议用户使用更具体的自定义功能，例如删除/追加软件包条目。这些其他自定义内容在以下部分中描述。

两个块系列特别有趣，并且可以安全地覆盖，因为它们的设计为空。每个 Dockerfile 的顶部都包含 <image_name>_header 块，可用于进行早期自定义，例如稍后描述的 RHN 注册。每个 Dockerfile 的底部都包含 <image_name>_footer 块，用于图像特定的修改。请注意使用图像的下划线名称，即用下划线替换破折号。所有叶 Dockerfile，即用于直接使用的那些，还具有一个 footer 块，该块在图像配方链的末尾保证存在一次。

软件包自定义¶

作为镜像构建的一部分安装的软件包可以被覆盖、追加和删除。以 Horizon 为例，以下软件包是软件包安装的一部分（其中包括）

gettext
locales

要将软件包添加到此列表，例如 iproute，首先创建一个文件，例如 template-overrides.j2。在其中放置以下内容

{% extends parent_template %}

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

然后使用命令行重新构建 horizon 镜像，传递 --template-override 参数

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

或者 template_override 可以在 kolla-build.conf 中设置。

上述示例中的 append 后缀具有特殊意义。它表示对软件包列表执行的操作。以下是可用的操作的完整列表

override: 使用自定义列表替换默认软件包。
append: 将软件包添加到默认列表中。
删除: 从默认列表中删除软件包。

要从该列表中删除软件包，例如 locales，您将执行

{% extends parent_template %}

# Horizon
{% set horizon_packages_remove = ['locales'] %}

一个例子是 Grafana 插件，如下一节所述。

Grafana 插件¶

可以通过将插件名称添加到 grafana_plugins_append 列表中安装额外的 Grafana 插件。也可以通过将插件名称添加到 grafana_plugins_remove 列表中删除插件。此外，可以通过设置 grafana_plugins_override 变量来覆盖整个列表。

grafana_plugins_append:
   - grafana-piechart-panel
   - vonage-status-panel

补丁自定义¶

Kolla 提供了在构建过程中将补丁应用于 Docker 镜像的功能。这允许用户修改现有文件或在镜像创建过程中添加新文件。

您需要在 /etc/kolla/kolla-build.conf 的 [DEFAULT] 部分中定义一个 patches_path。此目录将用于存储镜像的补丁。

[DEFAULT]
patches_path = /path/to/your/patches

为要修补的每个镜像创建一个目录，遵循类似于 Debian 补丁 quilt 格式的目录结构。有关更多详细信息，请参阅 quilt 文档。

<patches_path>/image_name/：特定镜像的目录。
<patches_path>/image_name/some-patch：包含补丁内容。
<patches_path>/image_name/another-patch：包含补丁内容。
<patches_path>/image_name/series：列出应用补丁的顺序。

例如，如果您想修补 nova-api 镜像，则结构如下所示

/path/to/your/patches/nova-api/some-patch
/path/to/your/patches/nova-api/another-patch
/path/to/your/patches/nova-api/series

series 文件应列出应用补丁的顺序

some-patch
another-patch

当使用 kolla-build 构建镜像时，patches_path 中定义的补丁将自动应用于相应的镜像。

应用补丁后，Kolla 会在 /etc/kolla/patched 中存储有关应用补丁的信息。补丁文件本身存储在镜像内的 /patches 目录中。这允许您跟踪已应用于每个镜像的补丁，以便进行调试或验证。

Python 软件包构建选项¶

base Dockerfile 中的 base_pip_conf 块可用于通过标准的环境变量（如 PIP_INDEX_URL、PIP_TRUSTED_HOST 等）提供 PyPI 构建自定义选项。

要覆盖所有 OpenStack 镜像的 PYPI 上限约束，您可以在 kolla-build.conf 中定义 openstack-base 的源位置。

openstack-base (requirements) 仓库的上游有一个上限约束文件。

创建一个分支或克隆仓库，然后自定义 upper-constraints.txt，并在 kolla_build.conf 中定义 openstack-base 的位置。

# These examples use upstream openstack-base as a demonstration
# To use custom openstack-base, make changes accordingly

# Using git source
[openstack-base]
type = git
location = https://opendev.org/openstack/requirements
reference = master

# Using URL source
[openstack-base]
type = url
location = https://tarballs.opendev.org/openstack/requirements/requirements-master.tar.gz

# Using local source
[openstack-base]
type = local
location = /home/kolla/src/requirements

要删除或更改 openstack-base 上限约束中的特定 Python 软件包，您可以使用模板文件中的 openstack_base_override_upper_constraints 块，例如 template-overrides.j2

{% block openstack_base_override_upper_constraints %}
RUN {{ macros.upper_constraints_version_change("sqlparse", "0.4.4", "0.5.0") }}
RUN {{ macros.upper_constraints_remove("reno") }}
{% endblock %}

kolla-toolbox 镜像需要不同的方法，因为它不使用 openstack-base 作为基础镜像。在 kolla-toolbox 的 Dockerfile 中设置了一个变量 UPPER_CONSTRAINTS_FILE。要更改变量，请将以下内容添加到模板文件中的 kolla_toolbox_pip_conf 块中，例如 template-overrides.j2

{% block kolla_toolbox_pip_conf %}
ENV UPPER_CONSTRAINTS_FILE=https://releases.openstack.org/constraints/upper/master
{% endblock %}

注意

UPPER_CONSTRAINTS_FILE 必须是文件的有效 URL

插件功能¶

Dockerfile 自定义机制对于将/安装插件添加到服务非常有用。一个例子是 Neutron 的第三方 L2 驱动程序。

例如，要将 networking-cisco 插件添加到 neutron_server 镜像，您可能会尝试将以下内容添加到 template-override 文件

警告

不要这样做。继续阅读原因。

{% extends parent_template %}

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

一些读者可能会注意到这里有一个问题。假设 Dockerfile 在一段时间内没有变化，上述 RUN 语句会被 Docker 缓存，这意味着添加到 Git 仓库的新提交可能会在后续构建中被忽略。为了解决这个问题，kolla-build 工具也支持在构建时克隆额外的仓库，这些仓库将自动提供给构建，并存储在一个名为 plugins-archive 的归档文件中。

要使用此功能，请将以下格式的部分添加到 kolla-build.conf 中

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

其中 <image-name> 是应将插件安装到的镜像的连字符名称，<plugin-name> 是所选插件标识符。

继续上面的例子，可以将以下内容添加到 kolla-build.conf 中

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

构建将克隆仓库，从而产生以下归档结构

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

模板现在变为

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

有些插件默认安装。对于具有默认插件的镜像，Dockerfile 已经将 plugins-archive 复制到镜像中，并在构建时安装可用的插件。可以通过在 kolla-build.conf 中相关插件源配置部分将 enabled 设置为 False 来禁用这些默认插件。

Neutron 插件¶

一个拥有许多可用插件的服务示例是 Neutron。 neutron-base 镜像 Dockerfile 已经启用了插件归档的复制和安装。在 Kolla 的 contrib 目录中（如仓库、tarball 或安装目标的 share 目录中可用），有一个 neutron-plugins 目录，其中包含 Neutron 插件定义的示例。其中一些插件曾经默认启用，但由于其发布特性，已被排除在默认构建之外。请阅读包含的 README.rst 以了解如何应用它们。

附加功能¶

Dockerfile 定制机制对于向镜像添加/安装附加内容非常有用。例如，将您的 jenkins 作业构建元数据（例如，格式化为 jenkins.json 文件）添加到镜像中。

与插件机制类似，Kolla 构建工具也支持在构建时克隆额外的仓库，这些仓库将自动提供给构建，并存储在一个名为 additions-archive 的归档文件中。 plugins-archive 和 additions-archive 的主要区别在于，plugins-archive 会自动复制到许多镜像中并处理以安装可用的插件，而 additions-archive 的处理完全由 Kolla 用户负责。

要使用此功能，请将以下格式的部分添加到 kolla-build.conf 中

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

其中 <image-name> 是应将附加内容复制到的镜像的连字符名称，<additions-name> 是所选附加内容标识符。

例如，可以将以下内容添加到 kolla-build.conf 文件中

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

构建将复制目录，从而产生以下归档结构

additions-archive.tar
|__ additions
    |__jenkins

模板现在变为

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

自定义 docker 模板¶

为了统一管理 OpenStack 相关项目的过程，Kolla 提供了一种为外部“非内置”项目构建镜像的方法。

如果“非内置”项目的模板符合 Kolla 模板标准，则操作员可以通过 --docker-dir CLI 选项（可以多次指定）提供一个包含模板的根目录。

所有 Kolla 的 jinja2 宏都应与内置项目一样可用，但有一些注意事项

configure_user 宏。由于 Kolla 不知道“非内置”用户，因此没有默认的用户 ID 和组 ID 值可供使用。要使用此宏，操作员应使用 <custom_user_name>-user 配置部分指定“非默认”用户详细信息，并至少包含 uid 和 gid 信息。

让我们看看操作员如何使用 openstack/releases 项目使用 Kolla 构建内部项目的镜像。

首先，为该项目创建一个 Dockerfile.j2 模板。

FROM {{ namespace }}/{{ image_prefix }}openstack-base:{{ tag }}

{% block labels %}
LABEL maintainer="{{ maintainer }}" name="{{ image_name }}" build-date="{{ build_date }}"
{% endblock %}

{% block releaser_header %}{% endblock %}

{% import "macros.j2" as macros with context %}

{{ macros.configure_user(name='releaser') }}

RUN ln -s releaser-source/* /releaser \
    && {{ macros.install_pip(['/releaser-source']  | customizable("pip_packages")) }} \
    && mkdir -p /etc/releaser \
    && chown -R releaser: /etc/releaser \
    && chmod 750 /etc/sudoers.d \
    && touch /usr/local/bin/kolla_releaser_extend_start \
    && chmod 644 /usr/local/bin/kolla_extend_start /usr/local/bin/kolla_releaser_extend_start

{% block footer %}{% endblock %}

建议的目录结构

custom-kolla-docker-templates
|__ releaser
    |__ Dockerfile.j2

然后，修改 Kolla 的配置，以便引擎可以下载源代码并配置用户。

[releaser]
type = git
location = https://opendev.org/openstack/releases
reference = master

[releaser-user]
uid = 53001
gid = 53001

在构建新镜像之前的最后预检 - 确保 Kolla 可以看到新的模板

$ kolla-build --list-images --docker-dir custom-kolla-docker-templates "^releaser$"
: base
: releaser
: openstack-base

最后，构建 releaser 镜像，并传递 --docker-dir 参数

kolla-build --docker-dir custom-kolla-docker-templates "^releaser$"

我可以使用 --template-override 选项覆盖自定义模板吗？是的！

自定义仓库¶

Red Hat¶

Kolla 允许操作员使用自定义仓库构建容器。仓库以逗号分隔的列表形式接受，可以是 .repo、.rpm 或 url。

如果指定 .repo 文件，则每个 .repo 文件都需要存在于与基本 Dockerfile (kolla/docker/base) 相同的目录中，或者您需要指定一个 url

rpm_setup_config = epel.repo,https://remote-server.com/your-repo.repo

Debian / Ubuntu¶

对于基于 Debian 的镜像，可以按如下方式将其他 apt 源添加到构建中

apt_sources_list = custom.list

在代理后构建¶

我们可以在镜像中插入 http_proxy 设置以在构建期间获取软件包，然后在最后取消设置它们，以避免将它们传递到最终镜像的环境中。但是，请注意，使用此方法无法完全删除信息；它仍然可见于镜像的层中。

要设置代理设置，我们可以将此添加到模板的标题块

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

要取消设置代理设置，我们可以将此添加到模板的页脚块

ENV http_proxy=""
ENV https_proxy=""

除了这些配置选项外，脚本还会自动读取这些环境变量。如果主机系统代理参数与将要使用的参数匹配，则不需要其他输入参数。这些是将被从用户环境中获取的变量

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

这些变量也可以使用 --build-args 覆盖，后者具有优先级。

交叉编译¶

可以交叉编译容器镜像，以便例如，在 x86_64 机器上构建 aarch64 镜像。

要在 x86_64 平台上构建 ARM 镜像，请传递 --base-arch 和 --platform 参数

kolla-build --platform linux/arm64 --base-arch aarch64

注意

要在 x86_64 平台上使其工作，可以使用诸如 qemu-user-static 或 binfmt 之类的工具。

要在 Apple Silicon 上使其工作，可以使用 Docker Desktop 或 Podman Desktop 构建 x86_64 或原生 ARM 镜像。

已知问题¶

镜像不可靠。

Kolla 使用的一些镜像可能不可靠。因此，有时一些容器构建失败。为了纠正构建问题，如果第一次构建失败，构建工具将自动尝试三次重试构建操作。重试次数通过 --retries 选项修改。

构建容器镜像

构建容器镜像¶

构建 kolla 镜像¶

从源代码构建 OpenStack¶

Dockerfile 自定义¶

使用不同的基础镜像¶

通用自定义¶

软件包自定义¶

Grafana 插件¶

补丁自定义¶

Python 软件包构建选项¶

插件功能¶

Neutron 插件¶

附加功能¶

自定义 docker 模板¶

自定义仓库¶

Red Hat¶

Debian / Ubuntu¶

在代理后构建¶

交叉编译¶

已知问题¶

kolla 21.0.1.dev4

页面内容