Ansible 构建器指南

Red Hat Ansible Automation Platform 2.1

执行环境构建器，为您的 Red Hat Ansible Automation Platform 创建一致且可重复生成的自动化执行环境。

Red Hat Customer Content Services

摘要

提供反馈：
如果您对本文档有任何改进建议，或发现错误，请联系技术支持 https://access.redhat.com，使用 Docs组件在 Ansible Automation PlatformJIRA 项目中创建一个问题。

前言

使用 Ansible Builder 为您的 Red Hat Ansible Automation Platform 需求创建一致且可重复生成的自动化环境。

使开源包含更多

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。我们从这四个术语开始：master、slave、黑名单和白名单。由于此项工作十分艰巨，这些更改将在即将推出的几个发行版本中逐步实施。有关更多详情，请参阅我们的首席技术官 Chris Wright 提供的消息。

第 1 章 Ansible Builder 简介

1.1. 关于 Ansible Builder

Ansible Builder（Ansible 构建器）是一个命令行工具，它通过使用各种 Ansible Collections 中定义的元数据以及用户自动构建自动化执行环境的过程。

1.1.1. 为什么使用 Ansible Builder？

在开发 Ansible Builder 之前，Automation Platform 用户在试图创建自定义虚拟环境或容器（它们所需要的依赖项已安装）时，可以会遇到依赖项问题以及多个错误消息。

现在，Ansible Builder 通过使用可轻松自定义的定义文件来安装 Ansible，指定集合及其所有依赖项，从而可以完全满足运行作业所需的所有要求。

第 2 章 使用 Ansible Builder

2.1. 安装 Ansible Builder

您可以使用 Red Hat Subscription Management (RHSM) 安装 Ansible Builder 来附加 Red Hat Ansible Automation Platform 订阅。附加 Red Hat Ansible Automation Platform 订阅 可让您访问安装 ansible-builder 所需的仅订阅资源。附加订阅后，会自动启用 ansible-builder 所需的存储库。

注意

在安装 ansible-builder 之前，您必须在主机上附加了有效的订阅。

流程

  1. 在终端中，运行以下命令来激活 Ansible Automation Platform 仓库： 

    $ dnf config-manager --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms

  2. 然后输入以下命令来安装 Ansible Builder： 

    $ dnf install ansible-builder

2.2. 构建定义文件

安装 Ansible Builder 后，我们需要创建一个定义文件，Ansible Builder 将使用该定义文件创建您的自动化执行环境镜像。构建自动化执行环境文件的高级别流程是 Ansible Builder 读取和验证您的定义文件，然后创建一个 Continerfile，最后将 Containerfile 传递给 Podman，然后打包并创建自动化执行环境文件。我们为 Ansible Builder 创建的定义文件采用 yaml 格式，包含我们将进一步详细讨论的不同部分。

以下是定义文件的示例：

例 2.1. 定义文件

version: 1

build_arg_defaults: 1
  ANSIBLE_GALAXY_CLI_COLLECTION_OPTS: "-v"

ansible_config: 'ansible.cfg' 2

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

additional_build_steps: 4
  prepend: |
    RUN whoami
    RUN cat /etc/os-release
  append:
    - RUN echo This is a post-install command!
    - RUN ls -la /etc
1
列出构建参数的默认值
2
指定 ansible.cfg 文件路径
3
指定各种要求文件的位置
4
用于其他自定义构建步骤的命令

有关这些定义文件参数的更多信息，请参阅本节。

2.3. 执行构建和创建命令

先决条件

  • 您已创建了定义文件

流程

要构建自动化执行环境镜像，请运行： 

$ ansible-builder build

默认情况下，Ansible Builder 将查找名为 execution-environment.yml 的定义文件，但可以通过 -f 标志将不同的文件路径指定为参数： 

$ ansible-builder build -f definition-file-name.yml

其中 definition-file-name 指定您的定义文件的名称。

2.4. 定义文件内容的分类

使用 Ansible Builder 构建自动化执行环境时需要定义文件，因为它指定了自动化执行环境容器镜像中包含的内容。

以下小节细分了定义文件的不同部分。

2.4.1. 构建参数和基础镜像

定义文件的 build_arg_defaults 部分是一个字典，其键可为 Ansible Builder 的参数提供默认值。下表列出了 build_arg_defaults 中可以使用的值：

值描述

ANSIBLE_GALAXY_CLI_COLLECTION_OPTS

  • 允许用户传递 –pre 标记来启用预发布集合的安装。
  • -c 与将 verify_ssl 设置为 false 相同

EE_BASE_IMAGE

指定自动化执行环境的父镜像，启用基于已存在的镜像构建的新镜像

EE_BUILDER_IMAGE

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

build_arg_defaults 中指定的值将硬编码到 Containerfile 中，因此这些值将在手动调用 podman build 时保留。

注意

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

2.4.2. Ansible 配置文件路径

当使用 ansible.cfg 文件将私有帐户的令牌和其他设置传递给自动化中心服务器时，请将配置文件路径（相对于定义文件所在的位置）作为字符串，在构建的初始阶段将其启用为构建参数。

ansible.cfg 文件的格式应当类似以下示例：

例 2.2. ansible.cfg 文件

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=my_ah_token

有关如何从自动化中心下载集合的更多信息，请参阅相关的 Ansible 文档页面。

2.4.3. 依赖项

2.4.3.1. Galaxy

galaxy 条目指向 ansible-galaxy collection install -r …​ 命令创建。

条目 requirements.yml 可以是对于自动化执行环境定义的文件夹目录的相对路径，也可以是绝对路径。

requirements.yml 文件的内容可能类似如下：

例 2.3. Galaxy 的 requirements.yml 文件

collections:
  - geerlingguy.java
  - kubernetes.core

2.4.3.2. Python

定义文件中的 python 条目指向 pip install -r …​ 命令所需的文件。

条目 requirements.txt 是一个文件，它会在集合已列出的 Python 依赖项之上安装额外的 Python 要求。它可以是对于自动化执行环境定义的文件夹目录的相对路径，也可以是绝对路径。requirements.txt 文件的内容应该类似以下示例，类似于 pip freeze 命令的标准输出：

例 2.4. Python 的 requirements.txt 文件

boto>=2.49.0
botocore>=1.12.249
pytz
python-dateutil>=2.7.0
awxkit
packaging
requests>=2.4.2
xmltodict
azure-cli-core==2.11.1
python_version >= '2.7'
collection community.vmware
google-auth
openshift>=0.6.2
requests-oauthlib
openstacksdk>=0.13
ovirt-engine-sdk-python>=4.4.10

2.4.3.3. System

定义中的 system 条目指向一个 bindep 要求文件，该文件将安装集合中已存在的系统级依赖项。它可以是对于自动化执行环境定义的文件夹目录的相对路径，也可以是绝对路径。

要演示这一点，以下是 bindep.txt 文件示例，该文件将 libxml2 和 subversion 软件包添加到容器中：

例 2.5. bindep.txt 文件

libxml2-devel [platform:rpm]
subversion [platform:rpm]

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

prepend 和 append 命令可以在 additional_build_steps 部分中指定。这些将添加命令到 Containerfile，该文件将在执行主要构建步骤之前或之后运行。

additional_build_steps 的语法必须是以下之一：

  • 一个多行的字符串

    例 2.6. 一个多行的字符串条目

    RUN whoami
RUN cat /etc/os-release

  • 一个列表

    例 2.7. 一个列表条目

    - RUN echo This is a post-install command!
- RUN ls -la /etc

2.5. 可选的 build 命令参数

-t 标志将为您的自动化执行环境镜像指定一个特定名称。例如，以下命令将构建名为 my_first_ee_image 的镜像： 

$ ansible-builder build -t my_first_ee_image

如果有多个定义文件，您可以使用 -f 标志指定要使用的文件： 

$ ansible-builder build -f another-definition-file.yml -t another_ee_image

在上例中，Ansible Builder 将使用文件 another-definition-file.yml 中提供的规格，而不是默认的 execution-environment.yml 来构建名为 another_ee_image 的自动化执行环境镜像。

有关可以与 build 命令一起使用的其他规格和标志，请输入 ansible-builder build --help 来查看附加选项列表。

2.6. 在不构建镜像的情况下创建容器文件

要创建可共享 Containerfile 但不从其中构建镜像，请运行： 

$ ansible-builder create

第 3 章 发布自动化执行环境

3.1. 将执行环境容器镜像推送到自动化中心

前提条件

  • 在自动化中心中具有执行环境权限，供您创建新容器或推送到现有容器。

容器 registry 是用于存储容器镜像的存储库。构建自动化执行环境镜像后，您将准备好将该容器镜像推送到自动化中心实例的 registry 部分。

使用您的自动化中心 URL，运行以下命令登录到 Podman，替换用户名、密码和自动化中心 URL： 

$ podman login -u=username -p=password automation-hub-url

登录到 Podman 后，运行以下命令将容器镜像推送到自动化中心上的容器 registry 中： 

$ podman push automation-hub-url/ee-image-name
注意

自动化执行环境镜像名称通过 -t 参数指定给 ansible-builder build 命令。如果没有使用 -t 标志指定自定义镜像名称，则默认镜像标签为 ansible-execution-env:latest。

3.2. 从受保护的 registry 中拉取

要从密码或令牌保护的 registry 中拉取容器镜像，请在自动化控制器中创建凭证：

流程

  1. 进入自动化控制器。
  2. 在侧边栏中，点 Resources → Credentials。
  3. 点 Add 以创建新凭据。
  4. 提供授权 URL、用户名和密码。点击 Save。

如需更多信息，请参阅执行环境文档中保护 registry 一节中的 Pulling。

第 4 章 从 Red Hat Ansible Automation Platform 提供的现有基本 EE 构建

4.1. 收集系统级别的依赖项

bindep 格式提供了一种指定跨平台要求的方法。至少，集合会为 [platform:rpm] 指定必要的要求。

以下是有效 bindep.txt 文件中的内容示例：

例 4.1. bindep.txt 文件

python38-devel [platform:rpm compile]
subversion [platform:rpm]
git-lfs [platform:rpm]

来自多个集合的条目将合并到一个文件中。这将通过 bindep 进行处理，然后传递到 dnf。镜像中仅会安装没有配置集或无运行时要求的要求。

4.2. 自定义现有执行环境镜像

Ansible Controller 附带三个默认执行环境：

  • Ansible 2.9 - 不安装 Controller 模块以外的集合
  • minimal - 包含最新的 Ansible 2.12 版本以及 Ansible Runner，但不包含集合或其他额外内容
  • EE Supported - 包含所有红帽支持的内容

虽然这些环境涵盖了许多自动化用例，但您可以添加额外的项目来自定义这些容器，以满足您的特定需求。以下流程将 kubernetes.core 集合添加到 ee-minimal 默认镜像中：

流程

  1. 通过 Podman 登录到 registry.redhat.io： 

    $ podman login -u="[username]" -p="[token/hash]" registry.redhat.io

  2. 拉取自动化执行环境镜像 

    podman pull registry.redhat.io/ansible-automation-platform-21/ee-minimal-rhel8:latest

  3. 配置 Ansible Builder 文件，以指定要添加到基于 ee-minimal 的新执行环境镜像的任何额外内容。

    1. 例如，要将来自 Galaxy 的 Kubernetes Core Collection 添加到镜像中，请填写 requirements.yml 文件，如下所示： 

      collections:
  - kubernetes.core
    2. 如需有关定义文件及其内容的更多信息，请参阅定义文件分类部分。

  4. 在执行环境定义文件中，通过 EE_BASE_IMAGE 字段指定到 originalee-minimal 容器的文件路径。这样，您的最终 execute-environment.yml 文件将类似如下：

    例 4.2. 自定义 execution-environment.yml 文件

    version: 1

build_arg_defaults:
  EE_BASE_IMAGE: 'example.registry.com/my-base-ee'

dependencies:
  galaxy: requirements.yml
    注意

    由于本例使用 kubernetes.core 的社区版本，而不是来自自动化中心的认证集合，因此我们不需要创建 ansible.cfg，也不在定义文件中引用。

  5. 使用以下命令构建新执行环境镜像： 

    $ ansible-builder build -t registry.redhat.io/[username]/new-ee

    其中 [username] 指定您的用户名，new-ee 指定新容器镜像的名称。

    1. 使用 podman images 命令确认您的新容器镜像在该列表中：

      例 4.3. 使用镜像 new-ee 的 podman images 命令的输出

      REPOSITORY          TAG     IMAGE ID      CREATED        SIZE
localhost/new-ee    latest  f5509587efbb  3 minutes ago  769 MB
  6. 通过 Ansible Navigator 验证新创建的执行环境镜像

  7. 标记在自动化中心中使用的镜像： 

    $ podman tag registry.redhat.io/_[username]_/_new-ee_ [automation-hub-IP-address]/_[username]_/_new-ee_

  8. 使用 Podman 登录到您的自动化 hub:

    注意

    您必须具有 Automation hub 的 admin 或适当的容器存储库权限才能推送容器。如需更多信息，请参阅 Red Hat Ansible Automation Platform 文档中的在私有自动化中心管理容器。 

    $ podman login -u="[username]" -p="[token/hash]" [automation-hub-IP-address]

  9. 将镜像推送到自动化 hub 中的容器 registry 中： 

    $ podman push [automation-hub-IP-address]/_[username]_/_new-ee_

  10. 将新镜像拉取(pull)到自动化控制器实例中：

    1. 进入自动化控制器。
    2. 在侧面导航栏中，点 Administration → Execution Environments。
    3. 点击 Add。

    4. 输入适当的信息，然后点 Save 以拉取新镜像。

      注意

      如果您的自动化中心实例受密码或令牌保护，请确保设置了适当的容器 registry 凭证。

法律通告

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.