执行环境定义

您在 YAML 文件中定义执行环境的内容。默认情况下，此文件名为 execution-environment.yml 或 execution-environment.yaml。此文件告诉 Ansible Builder 如何创建构建指令文件（Containerfile 用于 Podman，Dockerfile 用于 Docker）和容器镜像的构建上下文。

注意

此页面记录了 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

在构建 builder 镜像之前插入的命令。

append_builder

在构建 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"

images

指定要使用的基本镜像。您至少必须为基本镜像指定源、镜像和标签。基本镜像提供操作系统，也可能提供一些软件包。我们建议使用标准的 host/namespace/container:tag 语法来指定镜像。您可以使用 Podman 或 Docker 快捷语法，但完整的定义更可靠且可移植。

本节的有效键为

base_image

定义执行环境父镜像的字典。必须提供一个 name 键，其中包含要使用的容器镜像。如果镜像在您的存储库中镜像，但使用原始镜像的签名密钥签名，请使用 signature_original_name 键。

image verification

如果您使用的是 podman 容器运行时，您可以验证已签名的容器镜像。设置 --container-policy CLI 选项以控制如何使用此数据以及 Podman policy.json 文件来验证容器镜像签名。

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

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

  • signature_required 策略： ansible-builder 将使用此处的容器镜像定义在构建 上下文目录 中生成一个 policy.json 文件，该文件将在构建过程中用于验证镜像。

options

可以影响构建器运行时功能的关键字/选项字典。本节的有效键为

container_init

一个包含键的字典，允许自定义容器 ENTRYPOINT 和 CMD 指令（以及相关行为）。自定义这些行为是一项高级任务，可能会导致难以调试的细微错误。由于本节提供的默认值控制着几个相互关联的行为，因此覆盖任何值将跳过该字典中所有剩余的默认值。有效键为

cmd

CMD Containerfile 指令的字面值。默认值为 ["bash"]。

entrypoint

ENTRYPOINT Containerfile 指令的字面值。默认入口点行为处理信号传播到子进程，以及在运行时尝试确保容器用户拥有一个功能齐全的可写主目录，该目录在 /etc/passwd 中表示，并将 HOME 环境变量设置为与之匹配。默认入口点脚本可能会在无法适当地调整用户运行时环境的情况下向 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_passwd_permissions: false
    skip_ansible_check: true
    workdir: /myworkdir
    user: bob
    tags:
      - ee_development:latest

version

一个整数值，用于设置执行环境定义文件的模式版本。默认为 1。如果您使用的是 Ansible Builder 3.x，则必须为 3。