Documentation

15. 执行环境设置参考

本节包含与设置和构建 execution environments 相关的参考信息。

15.1. 执行环境定义

定义文件是为 execution environment 构建镜像所需的 .yml 文件。execution environment 定义架构示例如下:

---
version: 1

build_arg_defaults:
  EE_BASE_IMAGE: 'quay.io/ansible/ansible-runner:stable-2.10-devel'

ansible_config: 'ansible.cfg'

dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt

additional_build_steps:
  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc

15.1.1. 构建参数和基础镜像

构建参数的默认值可以作为字典在 default_build_args 部分中的定义文件中指定。这是使用 --build-arg CLI 标志的替代选择。

ansible-builder 使用的构建参数如下:

  • ANSIBLE_GALAXY_CLI_COLLECTION_OPTS 允许用户传递 –pre 标记来启用预发布集合的安装。

  • EE_BASE_IMAGE 指定 execution environment 的父镜像。

  • EE_BUILDER_IMAGE 指定用于编译类型任务的镜像。

default_build_args 内部给出的值将硬编码到 Containerfile 中,因此如果手动调用 podman build,这些值将被保留。

如果在 CLI --build-arg 标志中指定同一变量,CLI 值将具有更高的优先级。

15.1.2. Ansible 配置文件路径

当使用 ansible.cfg 文件将私有帐户的令牌和其他设置传递给 Automation Hub 服务器时,在此列出配置文件路径(作为字符串)将启用它作为构建初始阶段的构建参数。

15.1.3. Ansible Galaxy 依赖项

galaxy 条目指向 ansible-galaxy collection install -r ... 命令的有效要求文件。

条目 requirements.yml 可以是 execution environment 定义文件夹的目录的相对路径,也可以是绝对路径。

15.1.4. Python 依赖项

python 条目指向 pip install -r ... 命令的有效要求文件。

条目 requirements.txt 可以是 execution environment 定义文件夹的目录的相对路径,也可以是绝对路径。

15.1.5. 系统级依赖项

system 条目指向一个 bindep 要求文件。这由 bindep 处理,然后传递到 dnf,其他平台尚不受支持。有关 bindep 的更多信息,请参阅 OpenDev documentation

15.1.6. 额外的自定义构建步骤

其他命令可以在 additional_build_steps 部分中指定,可在主要构建步骤之前(prepend),或之后(append)指定。语法需要是以下之一:

  • 一个多行字符串(例如,上面的 prepend 部分显示)

  • 一个字典(经过 append 显示)

15.2. ansible-builder 构建选项

以下选项可与 ansible-builder build 命令一起使用:

标记

语法

描述

--tag

$ ansible-builder build --tag=my-custom-ee

自定义要应用到构建的镜像的带标签的名称。

--file

$ ansible-builder build --file=my-ee.yml

使用一个名称不是 execution-environment.yml 的定义文件。

--context

$ ansible-builder build --context=/path/to/dir

指定在当前工作目录中创建的名为 context 的默认目录以外的位置。

--build-arg

$ ansible-builder build --build-arg FOO=bar

要使用 Podman 或 Docker 的构建时变量,请使用与 podman builddocker build 相同的方式指定。默认情况下,Containerfile 或 Dockerfile 包含一个构建参数 EE_BASE_IMAGE,,可让您在不修改文件的情况下重建。

--build-arg

$ ansible-builder build --build-arg EE_BASE_IMAGE=registry.example.com/another-ee

使用一个自定义基础镜像,替换之前停用的 --base-image 选项。

--container-runtime

$ ansible-builder build --container-runtime=docker

使用 Docker 而不是默认的 Podman 构建镜像。

--verbosity

$ ansible-builder build --verbosity 2

自定义详细程度。

15.2.1. 示例

test/data/pytz 中的示例需要 execution environment 定义中的 awx.awx 集合。查找插件 awx.awx.tower_schedule_rrule 需要 PyPI pytz 和另一个库才能正常工作。如果为 ansible-builder build 命令提供了 test/data/pytz/execution-environment.yml 文件,那么它将在镜像中安装集合,读取集合中的 requirements.txt 文件,然后将 pytz 安装到镜像中。

生成的镜像可以通过将这些变量放在专用数据目录的 env/settings 文件中来使用 ansible-runner 项目。

---
container_image: image-name
process_isolation_executable: podman # or docker
process_isolation: true

awx.awx 集合是默认 AWX execution environment 中包含的内容子集。更多详情可在 awx-ee repository 中找到。

15.3. 集合一级的元数据

一个 execution environment 条目的 galaxy 条目中的集合将为镜像提供它们的 Python 和系统要求。

可以通过以下方式识别集合中的要求:

  • meta/execution-environment.yml 文件引用 Python 和/或 bindep 要求文件

  • 名为 requirements.txt 的文件处于集合的根级别

  • 名为 bindep.txt 的文件处于集合的根级别

如果有任何文件位于集合的 build_ignore 中,则无法正常工作。

集合维护者可以使用 introspect 命令来验证 ansible-builder 是否可以识别他们所期望的要求,例如:

ansible-builder introspect --sanitize ~/.ansible/collections/

15.3.1. Python 依赖项

Python 要求文件使用 requirements-parser 库合并到一个文件中,以支持复杂的语法,如引用其他文件。

提供相同软件包名称的独立集合中的条目将合并到同一条目中,限制合并在一起。

有几个软件包名称会被 ansible-builder 特别*忽略*,这意味着如果集合列表包括了它们,它们将不会包括在组合的文件中。这些软件包包括测试软件包以及提供 Ansible 本身的软件包。完整的列表可在 ansible_builder.requirements 模块的 EXCLUDE_REQUIREMENTS 中找到。

15.3.2. 系统级依赖项

bindep 格式提供了一种指定跨平台要求的方法。最低预期是,集合指定了 [platform:rpm] 的必要要求。

多个集合中的条目将合并到一个文件中。只有无配置文件(运行时要求)的要求才会安装到镜像中。对多个集合的尝试可以合并到合并文件中。