Red Hat Ansible Automation Platform Creator 指南

Red Hat Ansible Automation Platform 2.1

本指南面向希望了解如何在创建自动化内容时使用 Ansible 的开发人员。

Red Hat Customer Content Services

摘要

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

使开源包含更多

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

第 1 章 前言

使用自动化执行环境在 Red Hat Ansible Automation Platform 中自动化内容

您可以将执行环境用作可重复生成的、可移植、一致和可共享的容器镜像。它们以集合的形式从系统依赖项、Python 依赖项、Ansible 版本和 Ansible 内容控制 Ansible Automation Platform 作业运行时环境的所有依赖项。

第 2 章 内容创建器工作流和自动化执行环境简介

2.1. 关于内容工作流

在 Red Hat Ansible Automation Platform 2.0 之前,自动化内容开发人员可能需要多个 Python 虚拟环境来管理它们。为降低这种复杂性,Ansible Automation Platform 2.0 正在脱离虚拟环境并使用容器(称为自动化执行环境),因为它们易于构建和管理,并且更容易在团队和机构间共享。

随着自动化控制器转变为使用自动化执行环境,Automation 内容导航器和 Ansible Builder 等工具将确保您可以在您自己的开发系统中本地利用这些自动化执行环境。

2.2. 架构概述

下表显示了 Ansible Automation Platform 2.0 上可用的工具的安排和使用,以及如何使用它们:

  • 今天,自动化内容在 Ansible Automation Platform 1.2 中使用。
  • 自动化内容导航器 + 下载的自动化执行环境 - 直接在笔记本电脑/工作站上使用
  • 自动化内容导航器 + 下载的自动化执行环境 + 自动化控制器 - 用于本地推送/执行 → 远程
  • 自动化内容导航器 + 自动化控制器 + Ansible Builder + 分层自定义 EE - 提供对所用内容的更多控制,以用于如何执行自动化作业

第 3 章 了解 Ansible 概念

作为自动化开发人员,请在开始 Ansible 开发项目之前,回顾以下 Ansible 概念以创建成功的 Ansible playbook 和自动化执行环境。

3.1. 先决条件

  • Ansible 已经安装。有关安装 Ansible 的详情,请参考 Ansible 文档中的安装 Ansible

3.2. 关于 Ansible Playbook

Playbook 是使用 YAML 编写的文件,其中包含特定组人类可读的指令或 "plays",供您发送到在单个目标或目标组上运行。

Playbook 可用于管理远程机器的配置和部署,以及涉及滚动更新的多层部署顺序。使用 playbook 将操作委派给其他主机,并在此过程中与监控服务器和负载平衡器交互。编写完 playbook 后,您可以在企业内重复使用 playbook 实现自动化。

3.3. 关于 Ansible 角色

角色是 Ansible 捆绑自动化内容的方式,以及利用已知文件结构自动加载相关的变量、文件、任务、处理程序和其他工件。除了创建具有数百个任务的大型 playbook 外,您可以使用角色将任务划分为更小、离散且可组合的工作单元。

您可以查找用于调配基础架构、部署应用以及 Ansible Galaxy 上每天执行的所有任务的角色。根据 Type 过滤您的搜索并选择 Role。找到您需要的角色后,可以使用 Ansible 捆绑的 ansible-galaxy 命令下载该角色:

$ ansible-galaxy role install username.rolename

3.4. 关于内容集合

Ansible 内容集合是用于自动化的现成工具包。它包括多种类型的内容,如 playbook、角色、模块和插件。下图显示了集合的基本结构:

collection/
├── docs/
├── galaxy.yml
├── meta/
│   └── runtime.yml
├── plugins/
│   ├── modules/
│   │   └── module1.py
│   ├── inventory/
│   ├── lookup/
│   ├── filter/
│   └── .../
├── README.md
├── roles/
│   ├── role1/
│   ├── role2/
│   └── .../
├── playbooks/
│   ├── files/
│   ├── vars/
│   ├── templates/
│   ├── playbook1.yml
│   └── tasks/
└── tests/
    ├── integration/
    └── unit/

在 Red Hat Ansible Automation Platform 中,自动化中心充当 Ansible 认证内容集合的来源。

3.5. 关于执行环境

自动化执行环境是一致且可共享的容器镜像,充当 Ansible 控制节点。自动化执行环境减少了共享具有外部依赖项的 Ansible 内容的挑战。

自动化执行环境包括:

  • Ansible 内核
  • Ansible Runner
  • Ansible Collections
  • Python 库
  • 系统依赖项
  • 自定义用户需求

您可以使用 Ansible Builder 定义并创建自动化执行环境。

第 4 章 工具和组件

了解更多有关您在创建自动化执行环境中使用的红帽 Ansible 自动化平台工具和组件。

4.1. 关于 Ansible Builder

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

4.2. 使用自动化内容导航器

自动化内容导航器是一种命令行以内容创建者为导向的工具,具有基于文本的用户界面。您可以使用 Automation content navigator 进行以下操作:

  • 启动和观察作业和 playbook。
  • 以 JSON 格式共享存储、完成的 playbook 和作业运行工件。
  • 浏览和内省自动化执行环境.
  • 浏览基于文件的清单。
  • 呈现 Ansible 模块文档,并提取您可以在 playbook 中使用的示例。

您无法在自动化执行环境等容器中执行属于 Ansible 核心的 Ansible 命令,如 ansible-playbook。使用自动化内容浏览器,其中包含一组与自动化执行环境兼容的 Ansible CLI 命令。自动化内容导航器还在其基于文本的用户界面中包含更详细的输出。

4.3. 关于自动化中心

Automation Hub 为红帽订阅的用户提供了一个途径,以便快速找到并使用红帽及我们的技术合作伙伴支持的内容,以便为最需要的环境提供额外的保证。

在高级别上,Automation Hub 为所有合作伙伴提供参与和提供经认证、受支持的内容的概述。

从中央视图中,用户可以深入了解每个合作伙伴并签出集合。

此外,也可搜索所有可用集合的概述。

4.4. 关于 Ansible 命令行界面

在命令行中使用 Ansible 是执行您不经常重复的任务的有用方法;对于重复的任务,建议编写 playbook。

命令行中 Ansible 的临时命令遵循以下结构:

$ ansible [pattern] -m [module] -a "[module options]"

4.5. 其他资源

第 5 章 设置您的开发环境

您可以按照本节中的步骤设置开发环境,以创建自动化执行环境。

5.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

5.2. 从 RPM 安装 RHEL 上的自动化内容导航器

您可以从 RPM 在 Red Hat Enterprise Linux (RHEL) 上安装自动化内容导航程序。

先决条件

  • 已安装 RHEL 8 或更高版本。
  • 使用 Red Hat Subscription Manager 注册了您的系统。

流程

  1. 附加 Red Hat Ansible Automation Platform SKU。

    $ subscription-manager attach --pool=<sku-pool-id>
  2. 为 RHEL 8 启用存储库。

    $ sudo subscription-manager repos --enable ansible-automation-platform-2.1-for-rhel-8-x86_64-rpms
  3. 安装自动化内容导航器.

    $ dnf install ansible-navigator

验证

  • 验证自动化内容导航器安装:

    $ ansible-navigator --help

以下示例演示了成功安装:

自动化内容导航器成功安装

5.3. 下载基本自动化执行环境

AAP 2.0 附带的基础镜像托管在红帽生态系统目录 (registry.redhat.io) 上。

先决条件

  • 您有有效的 Red Hat Ansible Automation Platform 订阅。

流程

  1. 登录到 registry.redhat.io

    $ podman login registry.redhat.com
  2. 从 registry 中拉取基础镜像

    $ podman pull registry.redhat.io/aap/<image name>

第 6 章 创建内容

使用创建器指南一节中的指南,了解更多有关开发 Red Hat Ansible Automation Platform 中使用的内容的信息。

6.1. 创建 playbook

Playbook 包含一个或多个 play。基本 play 包括以下部分:

  • Name:对 playbook 整体功能的简短描述,有助于保持所有用户的可读性和组织性。
  • Hosts:识别要针对 Ansible 运行的目标。
  • Become 声明:这个可选声明可以被设置为 true/yes 来使用一个 become 插件 (如 sudo, su, pfexec, doas, pbrun, dzdo, ksu) 进行权限升级。
  • Tasks:这是对 play 中每一主机执行的列表操作。

playbook 示例

- name: Set Up a Project and Job Template
  hosts: host.name.ip
  become: true

  tasks:
    - name: Create a Project
      awx.awx.project:
        name: Job Template Test Project
        state: present
        scm_type: git
        scm_url: https://github.com/ansible/ansible-tower-samples.git

    - name: Create a Job Template
      awx.awx.job_template:
        name: my-job-1
        project: Job Template Test Project
        inventory: Demo Inventory
        playbook: hello_world.yml
        job_type: run
        state: present

6.2. 创建集合

您可以使用 Ansible Galaxy CLI 工具在本地创建自己的集合。所有特定于集合的命令都可使用 collection 子命令激活。

先决条件

  • 开发环境中安装了 Ansible 版本 2.9 或更新版本。

流程

  1. 在终端中,导航到您希望命名空间根目录的位置。为简单起见,这应当是 COLLECTIONS_PATH 中的路径,但这不是必须的。
  2. 运行以下命令,将 my_namespacemy_collection_name 替换为您选择的值:

    $ ansible-galaxy collection init <my_namespace>.<my_collection_name>
    注意

    在 galaxy.ansible.com 或 cloud.redhat.com/ansible/automation-hub 的"My Content" 标签页下检查,确保您具有上传到命名空间的适当权限

以上命令将从上述命名空间参数(如果尚未存在)创建名为 的目录,然后在 下创建具有集合名称的目录。该目录内为默认值或"框架"集合。在这里,您可以添加角色或插件,并开始开发自己的集合。

对于执行环境,集合开发人员可以通过 Ansible Builder 提供适当的元数据来声明其内容的要求。

集合的要求可以通过以下方法识别:

  • 文件 meta/execution-environment.yml 引用 Python 和/或 bindep 要求文件
  • 名为 requirements.txt 的文件,其中包含有关 Python 依赖项的信息,有时可以在集合的根目录中找到
  • 名为 bindep.txt 的文件,其中包含系统级别的依赖项,有时可以在集合的根目录中找到
  • 如果其中任何文件位于 Collection 的 build_ignore 中,Ansible Builder 将不会在这些中提取,因为本节用于过滤构建工件中不应包含的任何文件或目录。

集合维护器可以使用 introspect 命令验证 ansible-builder 是否识别他们期望的要求:

$ ansible-builder introspect --sanitize ~/.ansible/collections/

其他资源

  • 如需有关创建集合的更多信息,请参阅 Ansible 开发人员指南中的创建集合

6.3. 创建角色

您可以使用 Ansible Galaxy CLI 工具创建角色。角色相关命令可以从 roles 子命令访问。

ansible-galaxy role init <role_name>

仍然支持集合外的独立角色,但应在集合内创建新的角色,以利用 Ansible Automation Platform 必须提供的所有功能。

流程

  1. 在终端中,前往集合内的 roles 目录。
  2. 在前面创建的集合中创建名为 role_name 的角色:

    $ ansible-galaxy role init my_role

    该集合现在在 roles 目录中包含一个名为 my_role 的角色:

    ~/.ansible/collections/ansible_collections/<my_namespace>/<my_collection_name>
    ...
    └── roles/
        └── my_role/
            ├── .travis.yml
            ├── README.md
            ├── defaults/
            │   └── main.yml
            ├── files/
            ├── handlers/
            │   └── main.yml
            ├── meta/
            │   └── main.yml
            ├── tasks/
            │   └── main.yml
            ├── templates/
            ├── tests/
            │   ├── inventory
            │   └── test.yml
            └── vars/
                └── main.yml
  3. 可以使用 --role-skeleton 参数提供自定义角色框架目录。这使得组织能够为新角色创建标准化模板,以满足其需求。

    ansible-galaxy role init my_role --role-skeleton ~/role_skeleton

这将通过将 ~/role_skeleton 的内容复制到 my _role 来创建名为 my_role 的角色。role_skeleton 的内容可以是在角色目录中有效的任何文件或文件夹。

其他资源

  • 如需有关创建角色的更多信息,请参阅 Ansible Galaxy 文档中的创建角色

6.4. 创建自动化执行环境

自动化执行环境定义文件将指定
  • Ansible 版本
  • Python 版本(默认为系统 Python)
  • 组所需的 Python 库
  • 零个或多个内容集合(可选)
  • 这些特定集合的 Python 依赖项

为环境指定一组集合的概念是解析并安装其依赖项。不需要将集合本身安装到您要在其上生成自动化执行环境的机器上。

从此定义构建自动化执行环境,生成容器镜像。请阅读 Ansible Builder 文档,以了解创建这些镜像涉及的步骤。

第 7 章 迁移现有内容

以下小节了解如何在升级到 Red Hat Ansible Automation Platform 2.0 和自动化控制器 4.0 后,使用 awx-manage 命令协助迁移过程中的其他步骤。此外,了解更多关于在 Ansible 版本间迁移的信息。

7.1. 将虚拟环境迁移到自动化执行环境

升级到 Red Hat Ansible Automation Platform 2.0 和自动化控制器 4.0 后,请使用以下部分协助迁移过程中的其他步骤。

7.1.1. 列出自定义虚拟环境

您可以使用 awx-manage 命令列出自动化控制器实例上的虚拟环境。

流程

  1. SSH 到自动化控制器实例并运行:

    $ awx-manage list_custom_venvs

这时将显示已发现的虚拟环境列表。

# Discovered virtual environments:
/var/lib/awx/venv/testing
/var/lib/venv/new_env

To export the contents of a virtual environment, re-run while supplying the path as an argument:
awx-manage export_custom_venv /path/to/venv

7.1.2. 查看与自定义虚拟环境关联的对象

使用 awx-manage 命令,查看与自定义虚拟环境关联的组织、作业和清单源。

流程

  1. SSH 到自动化控制器实例并运行:

    $ awx-manage custom_venv_associations /path/to/venv

这时将显示相关对象的列表。

inventory_sources:
- id: 15
  name: celery
job_templates:
- id: 9
  name: Demo Job Template @ 2:40:47 PM
- id: 13
  name: elephant
organizations
- id: 3
  name: alternating_bongo_meow
- id: 1
  name: Default
projects: []

7.1.3. 选择要导出的自定义虚拟环境

选择您要使用 awx-manage export_custom_venv 命令导出的自定义虚拟环境。

流程

  1. SSH 到自动化控制器实例并运行:

    $ awx-manage export_custom_venv /path/to/venv

此命令的输出将显示在指定虚拟环境中的 pip freeze 状态。此信息可复制到 Ansible Builder 的 requirements.txt 文件中,用于创建新的自动化执行环境镜像

numpy==1.20.2
pandas==1.2.4
python-dateutil==2.8.1
pytz==2021.1
six==1.16.0

To list all available custom virtual environments run:
awx-manage list_custom_venvs
注意

在运行 awx-manage list_custom_venvs 时传递 -q 标志来减少输出。

7.2. 在 Ansible 内核版本间迁移

在 Ansible 核心版本之间迁移需要您更新 playbook、插件和 Ansible 基础架构的其他部分,以确保它们使用最新版本。此过程要求根据对每个连续版本的 Ansible Core 所做的更新来验证更改。如果要从 Ansible 2.9 迁移到 Ansible 2.11,您首先需要验证是否满足 Ansible 2.10 的要求,并从那里对 2.11 进行更新。

7.2.1. Ansible 移植指南

Ansible 移植指南是一系列文档,提供关于连续 Ansible 版本之间行为更改的信息。从 Ansible 版本迁移到较新版本时,请参考指南。

7.2.2. 其他资源

  • 如需 Ansible 2.8 和 Ansible 2.9 之间的行为更改,请参阅 Ansible 2.9
  • 如需 Ansible 2.9 和 Ansible 2.10 之间的行为更改,请参阅 Ansible 2.10

第 8 章 使用自动化内容导航器执行您的内容

现在您已构建了自动化执行环境,您可以使用 Ansible 内容导航器来验证内容是否会以与自动化控制器运行它相同的方式运行。

8.1. 使用自动化内容导航器运行 Ansible playbook

作为内容创建者,您可以使用自动化内容导航器并以交互方式执行 Ansible playbook,以交互方式查看各个 play 的结果,以及验证或排查 playbook 的任务。您还可以在执行环境中执行 Ansible playbook,且无需执行环境,以比较和排除任何问题。

8.1.1. 从 Automation 内容导航器执行 playbook

您可以使用自动化内容导航器基于文本的用户界面运行 Ansible playbook,以跟踪任务的执行,并获取每个任务的结果。

先决条件

  • 一个 playbook。
  • 有效的清单文件(如果没有使用 localhost)或清单插件。

流程

  1. 启动自动化内容导航器

    $ ansible-navigator
  2. 运行 playbook。

    $ :run
  3. 可选:键入 ansible-navigator run simple-playbook.yml -i inventory.yml 以运行 playbook。
  4. 验证或添加清单以及任何其他命令行参数。

    INVENTORY OR PLAYBOOK NOT FOUND, PLEASE CONFIRM THE FOLLOWING
    ─────────────────────────────────────────────────────────────────────────
       Path to playbook: /home/ansible-navigator_demo/simple_playbook.yml
       Inventory source: /home/ansible-navigator-demo/inventory.yml
      Additional command line parameters: Please provide a value (optional)
    ──────────────────────────────────────────────────────────────────────────
                                                               Submit Cancel
  5. Submit 并按回车。您应该会看到任务正在执行。

    执行 playbook 任务
  6. 输入 play 旁边的数字以进入 play 结果,或者如果大于 9, 键入 :<number>

    任务列表

    如果您为 Automation 内容导航器启用了颜色,则失败的任务以红色显示。

  7. 键入要查看任务结果的任务旁边的数字,或者如果大于 9,键入 :<number>

    失败的任务结果
  8. 可选: type:doc 调出任务中使用的模块或插件文档,以帮助进行故障排除。

    ANSIBLE.BUILTIN.PACKAGE_FACTS (MODULE)
      0│---
      1│doc:
      2│  author:
      3│  - Matthew Jones (@matburt)
      4│  - Brian Coca (@bcoca)
      5│  - Adam Miller (@maxamillion)
      6│  collection: ansible.builtin
      7│  description:
      8│  - Return information about installed packages as facts.
    <... output omitted ...>
     11│  module: package_facts
     12│  notes:
     13│  - Supports C(check_mode).
     14│  options:
     15│    manager:
     16│      choices:
     17│      - auto
     18│      - rpm
     19│      - apt
     20│      - portage
     21│      - pkg
     22│      - pacman
    
    <... output truncated ...>

8.1.2. 检查 playbook 结果,其中包含自动化内容导航器工件文件

自动化内容导航器将 playbook 运行的结果保存到 JSON 构件文件中。您可以使用此文件与其他人共享 playbook 结果,出于安全或合规性的原因将其保存,或者稍后进行检查和故障排除。您只需要构件文件即可查看 playbook 运行。您不需要访问 playbook 本身或清单访问权限。

先决条件

  • 从 playbook 运行中自动化内容导航器构件 JSON 文件。

流程

  • 使用工件文件启动自动化内容导航器。

    $ ansible-navigator replay simple_playbook_artifact.json
    1. 检查 playbook 运行时的 playbook 结果。

      Playbook 结果

现在,您可以键入 play 和任务旁边的数字,以逐一检查结果,如执行 playbook 后一样。

第 9 章 总结

现在,您应能够根据特定的自动化需求自定义自动化执行环境,并通过容器 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.