21.2. 配置选项
在定义文件中使用以下配置 YAML 键。
Ansible Builder 3.x 执行环境定义文件接受七个顶级部分：
21.2.1. additional_build_files
构建文件指定要添加到构建上下文目录中的内容。然后，可以在任何构建阶段通过 additional_build_steps 引用或复制它们。
格式是字典值的列表，每个值都有一个 src 和 dest 键和值。
每个列表项都必须是一个字典，其中包含以下所需键：
| src | 指定要复制到构建上下文目录中的源文件。
这可以是绝对路径，例如 |
| dest |
指定构建上下文目录的
这不能是绝对路径，也不能包含 注意
当使用 |
21.2.2. additional_build_steps
构建步骤为任何构建阶段指定自定义构建命令。这些命令直接插入到容器运行时的 build 指令文件中，如 Containerfile 或 Dockerfile。命令必须符合容器化工具所需的任何规则。
您可以在镜像创建过程的任何阶段之前或之后添加构建步骤。例如，如果在安装依赖项前需要安装 git，您可以在基本构建阶段添加构建步骤。
以下是有效的密钥。分别支持多行字符串或字符串列表。
| append_base | 构建基础镜像后插入的命令。 |
| append_builder | 构建构建器镜像后要插入的命令。 |
| append_final | 构建最终镜像后要插入的命令。 |
| append_galaxy | 构建 galaxy 镜像后插入的命令。 |
| prepend_base | 在构建基础镜像前插入的命令。 |
| prepend_builder | 在构建构建器镜像前插入的命令。 |
| prepend_final | 在构建最终镜像前插入的命令。 |
| prepend_galaxy | 在构建 galaxy 镜像前插入的命令。 |
21.2.3. build_arg_defaults
这将构建参数的默认值指定为字典。
这是使用- build-arg CLI 标志的替代选择。
Ansible Builder 使用以下构建参数：
| ANSIBLE_GALAXY_CLI_COLLECTION_OPTS |
允许用户传递 |
| ANSIBLE_GALAXY_CLI_ROLE_OPTS |
这可让用户将任何标记（如 |
| PKGMGR_PRESERVE_CACHE | 这控制在镜像构建过程中清除软件包管理器缓存的频率。
如果没有设置这个值（这是默认值），则缓存会被频繁清除。如果 |
在 build_arg_defaults 中给出的 Ansible Builder 硬编码值，以便在手动运行容器构建时保留它们。
如果您在定义中指定相同的变量，且在命令行中使用 CLI build-arg 标志，CLI 值会覆盖定义中的值。
21.2.4. 依赖项
指定要安装到最终镜像的依赖项，包括 ansible-core、ansible-runner、Python 软件包、系统软件包和集合。Ansible Builder 会自动安装您安装的任何 Ansible 集合的依赖项。
通常，您可以使用标准语法来约束软件包版本。使用您传递给 dnf、pip、ansible-galaxy 或任何其他软件包管理工具的语法。您还可以在单独的文件中定义软件包或集合，并在定义文件的 dependencies 部分中引用这些文件。
以下键有效：
| ansible_core |
要安装
这个值是一个字典，其中包含一个键 ansible_core:
package_pip: ansible-core
ansible_core:
package_pip: ansible-core==2.14.3
ansible_core:
package_pip: https://github.com/example_user/ansible/archive/refs/heads/ansible.tar.gz
|
| ansible_runner | 要安装的 Ansible Runner Python 软件包的版本。
这个值是一个字典，其中包含一个键 ansible_runner:
package_pip: ansible-runner
ansible_runner:
package_pip: ansible-runner==2.3.2
ansible_runner:
package_pip: https://github.com/example_user/ansible-runner/archive/refs/heads/ansible-runner.tar.gz
|
| galaxy | 要从 Ansible Galaxy 安装的集合。
这可以是 Ansible Galaxy |
| python | Python 安装要求。
这可以是文件名，也可以是要求列表。Ansible Builder 使用 此库支持复杂的语法，包括对其他文件的引用。如果很多集合需要相同的 软件包名称，Ansible Builder 会将它们合并到一个条目中，并组合了约束。
Ansible Builder 排除 Python 依赖项组合文件中的一些软件包，即使集合将它们列为依赖项。其中包括提供 Ansible 本身的测试软件包和软件包。完整列表可以在
如果您需要包含其中一个排除的软件包名称，请使用 introspection 命令的 以这种方式提供的软件包不会针对排除的 Python 软件包列表进行处理。 |
| python_interpreter |
定义 dnf 要安装的 Python 系统软件包名称的字典( |
| system | 要安装的系统软件包，采用 bindep 格式。这可以是文件名或要求列表。 有关 bindep 的更多信息，请参阅 OpenDev 文档。
对于系统软件包，使用 |
以下示例使用包含各种依赖项的文件名：
dependencies:
python: requirements.txt
system: bindep.txt
galaxy: requirements.yml
ansible_core:
package_pip: ansible-core==2.14.2
ansible_runner:
package_pip: ansible-runner==2.3.1
python_interpreter:
package_system: "python310"
python_path: "/usr/bin/python3.10"这个示例使用内联值：
dependencies:
python:
- pywinrm
system:
- iputils [platform:rpm]
galaxy:
collections:
- name: community.windows
- name: ansible.utils
version: 2.10.1
ansible_core:
package_pip: ansible-core==2.14.2
ansible_runner:
package_pip: ansible-runner==2.3.1
python_interpreter:
package_system: "python310"
python_path: "/usr/bin/python3.10"
如果这些依赖项文件(requirements.txt、bindep.txt 和 requirements.yml)位于集合的 build_ignore 中，则构建会失败。
集合维护器可以使用 introspection 命令验证 ansible-builder 是否可以识别他们期望的要求：
ansible-builder introspect --sanitize ~/.ansible/collections/
--sanitize 选项查看所有集合要求并删除重复项。它还会删除通常排除的任何 Python 要求（请参阅 python 依赖项）。
使用 -v3 选项 内省，以查看关于被排除的要求的消息。
21.2.5. images
指定要使用的基础镜像。至少，您必须为基础镜像指定源、镜像和标签。基础镜像提供操作系统，也可以提供一些软件包。使用标准 host/namespace/container:tag 语法来指定镜像。您可以使用 Podman 或 Docker 快捷方式语法，但完整定义更为可靠和可移植。
本节的有效键包括：
| base_image | 定义执行环境的父镜像的字典。
必须为要使用的容器镜像提供 |
21.2.6. 镜像验证
如果使用 podman 容器运行时，您可以验证签名的容器镜像。
设置 container-policy CLI 选项，以控制与容器镜像签名验证相关的 Podman policy.json 文件。
-
ignore_all策略：在构建上下文目录 <context> 中生成一个policy.json文件，但没有执行签名验证。 -
系统策略：使用标准系统位置中的预先存在的policy.json文件来执行签名验证。Ansible-builder不负责这些文件中的内容，并且用户对内容有完全的控制权。 -
signature_required策略：ansible-builder使用容器镜像定义在构建期间使用的构建上下文目录 <context>中生成policy.json文件来验证镜像。
21.2.7. options
影响运行时功能的关键字或选项的字典。
本节的有效键包括：
container_init: 带有键的字典，用于自定义容器
ENTRYPOINT和CMD指令（及相关行为）。自定义这些行为是一个高级任务，可能会导致无法调试失败。由于提供的默认值控制多个中间的行为，覆盖任何值都跳过此字典中的所有剩余默认值。有效键是：
-
cmd:
CMDContainerfile 指令的 Literal 值。默认值为["bash"]。 ENTRYPOINT:
ENTRYPOINTContainerfile 指令的 Literal 值。默认入口点行为处理到子进程的信号传播，并在运行时确保容器用户具有具有有效写入主目录（在 /etc/passwd 中代表）的正确环境（在/etc/passwd中表示），并将HOME环境变量设置为匹配。当无法适当调整用户运行时环境时，默认入口点脚本会向stderr发送警告。此行为可以忽略或提升为致命错误；请查阅entrypoint目标脚本的来源以了解更多详细信息。默认值为
["/opt/builder/bin/entrypoint", "dumb-init"]。package_pip ：使用 pip 进行入口点支持安装的软件包。此软件包安装在最终构建镜像中。
默认值为
dumb-init==1.2.5。
-
cmd:
-
package_manager_path: 字符串，带有要使用的软件包管理器(dnf 或 microdnf)的路径。默认为
/usr/bin/dnf。这个值用于安装 Python 解释器，如果在依赖项中指定，并在assemble脚本的构建阶段指定。 skip_ansible_check ：此布尔值控制检查在最终镜像上执行 Ansible 和 Ansible Runner 的安装。
将此值设置为
True以不执行此检查。默认值为
False。relax_passwd_permissions ：此布尔值控制
root组(GID 0)是否明确授予最终容器镜像中的/etc/passwd的写入权限。默认入口点脚本可以在某些容器运行时下尝试通过动态创建用户来更新/etc/passwd，以确保全功能 POSIX 用户环境和主目录。禁用此功能可能会导致软件功能失败，要求用户在/etc/passwd中列出具有有效且可写入的主目录，例如 ansible-core 中的async和~usernameshell 扩展。默认值为
True。WORKDIR ：在最终容器镜像下启动新进程的默认当前工作目录。有些容器运行时也将此值用作
root(GID 0)组中动态创建用户的HOME。当指定这个值时，如果目录不存在，则创建该目录，设置为root组所有权，并且rwx组权限会递归应用到其中。默认值为
/runner。用户 ：这会设置用户名或 UID，以用作最终容器镜像的默认用户。
默认值为
1000。
示例选项：
options:
container_init:
package_pip: dumb-init>=1.2.5
entrypoint: '["dumb-init"]'
cmd: '["csh"]'
package_manager_path: /usr/bin/microdnf
relax_password_permissions: false
skip_ansible_check: true
workdir: /myworkdir
user: bob
21.2.8. version
一个整数值，用于设置执行环境定义文件的 schema 版本。
默认为 1。
如果使用 Ansible Builder 3.x，则该值必须是 3。
