执行环境定义

您在 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.gz
ansible_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.gz
galaxy

要从 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 文件来进行容器镜像签名验证。

  • ignore_all 策略：在构建 上下文目录 中生成一个 policy.json 文件，其中不执行任何签名验证。

  • system 策略：使用标准系统位置中预先存在的 policy.json 文件执行签名验证。ansible-builder 对这些文件中的内容不承担任何责任，用户可以完全控制内容。

  • signature_required 策略：ansible-builder 将使用此处的容器镜像定义在构建 上下文目录 中生成一个 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。