执行环境定义
您在 YAML 文件中定义执行环境的内容。默认情况下,此文件名为 execution-environment.yml
或 execution-environment.yaml
。此文件告诉 Ansible Builder 如何创建构建指令文件(对于 Podman 为 Containerfile
,对于 Docker 为 Dockerfile
)以及容器镜像的构建上下文。
注意
此页面记录了 Ansible Builder 3.x 的定义模式。如果您正在运行较旧版本的 Ansible Builder,则需要较旧的模式版本。有关更多信息,请参阅较旧版本的文档。我们建议使用版本 3,它比以前的版本更具可配置性和功能性。
概述
Ansible Builder 3.x 执行环境定义文件接受七个顶级部分
additional_build_files
additional_build_steps
build_arg_defaults
dependencies
images
options
version
版本 3 示例文件
这是一个版本 3 EE 文件示例。要使用 Ansible Builder 3.x,必须指定模式版本。如果您的 EE 文件未指定 version: 3
,则 Ansible Builder 将假定您想要版本 1。
---
version: 3
build_arg_defaults:
ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: '--pre'
dependencies:
ansible_core:
package_pip: ansible-core==2.14.4
ansible_runner:
package_pip: ansible-runner
galaxy: requirements.yml
python:
- six
- psutil
system: bindep.txt
exclude:
python:
- docker
system:
- python3-Cython
images:
base_image:
name: docker.io/redhat/ubi9:latest
# Other available base images:
# - quay.io/rockylinux/rockylinux:9
# - quay.io/centos/centos:stream9
# - registry.fedoraproject.org/fedora:38
# - registry.redhat.io/ansible-automation-platform-23/ee-minimal-rhel8:latest
# (needs an account)
# Custom package manager path for the RHEL based images
# options:
# package_manager_path: /usr/bin/microdnf
additional_build_files:
- src: files/ansible.cfg
dest: configs
additional_build_steps:
prepend_base:
- RUN echo This is a prepend base command!
# Enable Non-default stream before packages provided by it can be installed. (optional)
# - RUN $PKGMGR module enable postgresql:15 -y
# - RUN $PKGMGR install -y postgresql
prepend_galaxy:
- COPY _build/configs/ansible.cfg /etc/ansible/ansible.cfg
prepend_final: |
RUN whoami
RUN cat /etc/os-release
append_final:
- RUN echo This is a post-install command!
- RUN ls -la /etc
配置选项
您可以在 v3 执行环境定义文件中使用此处列出的配置 YAML 密钥。
additional_build_files
指定要添加到构建上下文目录的文件。然后,这些文件可以在任何构建阶段由 additional_build_steps 引用或复制。格式为字典值的列表,每个字典都包含 src
和 dest
密钥和值。
每个列表项必须是一个包含以下(非可选)密钥的字典
src
指定要复制到构建上下文目录的源文件。这可以是绝对路径(例如,
/home/user/.ansible.cfg
),也可以是相对于执行环境文件的路径。相对路径可以是匹配一个或多个文件的 glob 表达式(例如files/*.cfg
)。请注意,绝对路径不能包含正则表达式。如果src
是一个目录,则该目录的整个内容将复制到dest
。dest
指定构建上下文目录的
_build
子目录下的子目录路径,该路径应包含源文件(例如,files/configs
)。这不能是绝对路径或在路径中包含..
。如果此目录不存在,则将为您创建此目录。
additional_build_steps
为任何构建阶段指定自定义构建命令。这些命令将直接插入容器运行时的构建指令文件(例如,Containerfile 或 Dockerfile)中。这些命令必须符合容器化工具所需的任何规则。
您可以在镜像创建过程的任何阶段之前或之后添加构建步骤。例如,如果您需要在安装依赖项之前安装 git
,则可以在 base
构建阶段的末尾添加构建步骤。
以下是此部分的有效密钥。每个都支持多行字符串或字符串列表。
prepend_base
在构建基础镜像之前插入的命令。
append_base
在构建基础镜像之后插入的命令。
prepend_galaxy
在构建 Galaxy 镜像之前插入的命令。
append_galaxy
在构建 Galaxy 镜像之后插入的命令。
prepend_builder
在构建构建器镜像之前插入的命令。
append_builder
在构建构建器镜像之后插入的命令。
prepend_final
在构建最终镜像之前插入的命令。
append_final
在构建最终镜像之后插入的命令。
注意
请确保您不要在这些构建步骤中指定 USER 指令。这可能导致在构建镜像时发生错误。如果您想覆盖 USER 设置,请考虑使用下面提到的 options.user 设置。
build_arg_defaults
将构建参数的默认值指定为字典。这是一种替代使用 --build-arg CLI 标志的方法。
ansible-builder
使用的构建参数如下
ANSIBLE_GALAXY_CLI_COLLECTION_OPTS
这允许用户传递 –pre 标志(或其他标志)以启用预发布集合的安装。
ANSIBLE_GALAXY_CLI_ROLE_OPTS
这允许用户将任何标志(例如 –no-deps)传递给角色安装。
PKGMGR_PRESERVE_CACHE
这控制在镜像构建过程中清除包管理器缓存的频率。如果未设置此值(这是默认值),则会频繁清除缓存。如果将其设置为字符串 always,则永远不会清除缓存。任何其他值都会强制仅在最终构建阶段安装系统依赖项后清除缓存。
Ansible Builder 将 build_arg_defaults
内部的给定值硬编码到构建指令文件中,因此如果您手动运行容器构建,它们将保留。
如果您在执行环境定义和命令行中使用 CLI --build-arg 标志指定了相同的变量,则 CLI 值将具有更高的优先级(CLI 值将覆盖执行环境定义中的值)。
dependencies
指定要安装到最终镜像中的依赖项,包括 ansible-core
、ansible-runner
、Python 包、系统包和 Ansible 集合。Ansible Builder 会自动安装您安装的任何 Ansible 集合的依赖项。
通常,您可以使用标准语法来约束包版本。使用您传递给 dnf
、pip
、ansible-galaxy
或任何其他包管理实用程序的相同语法。您也可以在单独的文件中定义您的包或集合,并在执行环境定义文件的 dependencies
部分中引用这些文件。
此部分的有效密钥如下
ansible_core
要安装的
ansible-core
Python 包的版本。此值为一个字典,其中包含一个密钥package_pip
。package_pip
值直接传递给 pip 以进行安装,并且可以采用 pip 支持的任何格式。以下是一些示例值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.gzansible_runner
要安装的 Ansible Runner Python 包的版本。此值为一个字典,其中包含一个密钥
package_pip
。package_pip
值直接传递给 pip 以进行安装,并且可以采用 pip 支持的任何格式。以下是一些示例值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.gzgalaxy
要从 Galaxy 安装的 Ansible 集合。这可以是文件名、字典或 Ansible Galaxy
requirements.yml
文件的多行字符串表示形式(请参阅下面的示例)。在 Galaxy 用户指南 中了解更多关于需求文件格式的信息。
python
Python 安装要求。这可以是文件名,也可以是要求列表(请参阅下面的示例)。
注意
预计 Python 需求规范将仅限于 PEP 508 中定义的功能。井号注释将始终允许。任何偏离此规范的行为都将未经验证且未经修改地传递给 pip,尽管这被认为是未定义且不受支持的行为。不建议您依赖此行为。
python_interpreter
一个字典,定义要由
dnf
安装的 Python 系统包名称 (package_system
) 和/或要使用的 Python 解释器的路径 (python_path
)。system
要安装的系统包,采用 bindep 格式。这可以是文件名,也可以是要求列表(请参阅下面的示例)。
exclude
一个字典,定义要从引用的集合的顶级依赖项要求中排除的 Python 或系统要求。这些排除不适用于用户提供的 Python 或系统依赖项,也不适用于依赖项的依赖项(仅限顶级)。
此部分的有效密钥如下
python
- 要排除的 Python 依赖项列表。
system
- 要排除的系统依赖项列表。
all_from_collections
- 如果要从一个或多个集合中排除所有 Python 和系统依赖项,请在此密钥下提供集合名称列表。排除功能支持两种匹配形式
简单的名称匹配。
使用正则表达式的高级名称匹配。
对于简单的名称匹配,您只需提供要匹配的要求/集合的名称即可。所有值都将以不区分大小写的方式进行比较。
对于高级名称匹配,请在排除字符串的开头使用波浪号 (
~
) 字符,以指示字符串的剩余部分是一个正则表达式,用于匹配需求/集合名称。正则表达式应被视为不区分大小写。注意
正则表达式必须与完整的需求/集合名称匹配。例如,
~foo.
不会完全匹配名称foobar
,但~foo.+
会。对于这两种匹配形式,排除字符串都将与任何 Python 或系统需求的 *简单* 名称进行比较。例如,如果您需要排除包含集合中以
foo [!platform:gentoo]
形式出现的系统需求,则您的排除字符串应为foo
。要排除 Python 需求bar == 1.0.0
,则您的排除字符串应为bar
。使用简单和高级匹配的示例
dependencies: exclude: python: - docker system: - python3-Cython all_from_collections: # Regular expression to exclude all from community collections - ~community\..+注意
exclude
选项需要ansible-builder
版本3.1
或更高版本。
以下示例使用包含各种依赖项的文件名
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"
镜像
指定要使用的基础镜像。至少您*必须*为基础镜像指定源、镜像和标签。基础镜像提供操作系统,也可能提供一些软件包。我们建议使用标准 host/namespace/container:tag
语法来指定镜像。您可以改用 Podman 或 Docker 快捷语法,但完整定义更可靠且更具可移植性。
此部分的有效键为
base_image
定义执行环境父镜像的字典。必须提供一个
name
键,其中包含要使用的容器镜像。如果镜像在您的存储库中进行了镜像,但使用原始镜像的签名密钥进行签名,请使用signature_original_name
键。
镜像验证
如果您使用 podman
容器运行时,则可以验证已签名的容器镜像。设置 --container-policy CLI 选项以控制如何使用此数据以及 Podman policy.json 文件来进行容器镜像签名验证。
选项
一个包含关键字/选项的字典,这些关键字/选项可以影响构建器运行时功能。此部分的有效键为
container_init
一个包含键的字典,这些键允许自定义容器
ENTRYPOINT
和CMD
指令(以及相关行为)。自定义这些行为是一项高级任务,可能会导致难以调试的细微故障。由于此部分提供的默认值控制着几个相互关联的行为,因此覆盖任何值都将跳过此字典中所有剩余的默认值。有效键为
cmd
CMD
Containerfile 指令的字面值。默认值为["bash"]
。entrypoint
ENTRYPOINT
Containerfile 指令的字面值。默认的入口点行为处理信号传播到子进程,以及尝试在运行时确保容器用户具有适当的环境,其中包含一个有效的可写主目录,在/etc/passwd
中表示,并将HOME
envvar 设置为匹配。默认的入口点脚本可能会在无法适当地调整用户运行时环境的情况下向stderr
发出警告。此行为可以忽略或提升为致命错误;请参阅entrypoint
目标脚本的源代码以获取更多详细信息。默认值为["/opt/builder/bin/entrypoint", "dumb-init"]
。package_pip
通过 pip 安装的软件包,用于入口点支持。此软件包将安装在最终构建镜像中。默认值为
dumb-init==1.2.5
。package_manager_path
包含软件包管理器路径的字符串(例如 -
dnf
或microdnf
)。默认为/usr/bin/dnf
。此值将用于安装 Python 解释器(如果在dependencies
中指定),并在构建阶段由assemble
脚本使用。skip_ansible_check
此布尔值控制是否在最终镜像上执行 Ansible 和 Ansible Runner 安装检查。将此值设置为
True
以不执行此检查。默认为False
。skip_pip_install
此布尔值控制我们是否尝试将 pip 安装到基础镜像中。Pip 对于 Python 需求安装等操作是必要的。如果您当前的 pip 安装方法不起作用,您可以选择禁用此步骤并手动处理 pip 的安装。默认为
False
。relax_passwd_permissions
此布尔值控制是否在最终容器镜像中明确授予
root
组(GID 0)对/etc/passwd
的写权限。默认的入口点脚本可能会尝试在某些容器运行时下使用动态创建的用户更新/etc/passwd
,以确保完全功能的 POSIX 用户环境和主目录。禁用此功能会导致需要在/etc/passwd
中列出用户且具有有效且可写的主目录(例如,ansible-core 中的async
以及~username
shell 展开)的软件功能出现故障。默认为True
。workdir
在最终容器镜像下启动的新进程的默认当前工作目录。某些容器运行时还将此值用作
HOME
,用于root
(GID 0)组中动态创建的用户。当指定此值时,将创建该目录(如果不存在),将其设置为root
组所有权,并递归地将其应用于其rwx
组权限。默认值为/runner
。user
这将设置用户名或 UID,作为最终容器镜像的默认用户。默认值为
1000
。tags
指定如果构建过程成功完成则分配给结果镜像的名称。默认值为
ansible-execution-env:latest
。
options
部分示例
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
tags:
- ee_development:latest
版本
一个整数,用于设置执行环境定义文件的模式版本。默认为 1
。如果您使用的是 Ansible Builder 3.x,则必须为 3
。