第 1 部分：Playbook 创建者的 Ansible.utils 集合

Ansible 的 ansible.utils 集合包含各种插件，这些插件有助于管理、操作和显示 Ansible playbook 开发人员的数据。此集合最常见的用例是在您想要处理 Ansible playbook、清单或模块返回的复杂数据结构时。请参阅每个插件的 文档 页面，了解如何将这些实用程序用于任务的详细示例。在本系列的两部分博客文章中，我们将概述第一部分中的此集合，并在第二部分中详细了解使用 utils 集合的示例用例。

ansible.utils 中的插件

插件是增强 Ansible 核心功能的代码。此代码在控制节点上执行，并为 Red Hat Ansible Automation Platform 的核心功能提供选项和扩展。此 ansible.utils 插件集合包括

• 过滤器插件
• 查找插件
• 测试插件
• 模块

过滤器插件

过滤器插件可以操作数据。使用正确的过滤器，您可以提取特定值，转换数据类型和格式，执行数学计算，分割和连接字符串，插入日期和时间等等。Ansible Automation Platform 使用 Jinja2 附带的 标准过滤器 并添加了一些专门的过滤器插件。您可以 创建自定义 Ansible 过滤器作为插件。有关更多信息，请参阅 文档。

ansible.utils 过滤器插件包括以下内容

• ansible.utils.from_xml - 将给定的 XML 字符串转换为本机 Python 字典。
• ansible.utils.get_path - 使用路径检索变量中的值
• ansible.utils.index_of - 查找列表中与某些条件匹配的项目的索引
• ansible.utils.param_list_compare - 生成组合/比较基本参数和提供的参数的最终参数列表。
• ansible.utils.to_paths - 将复杂对象展平为路径和值的字典
• ansible.utils.to_xml - 将给定的 JSON 字符串转换为 XML
• ansible.utils.usable_range - 展开可用的 IP 地址
• ansible.utils.validate - 使用提供的条件验证数据

查找插件

查找插件是 Jinja2 模板语言的 Ansible 特定扩展。您可以使用查找插件在 playbook 中访问外部来源（文件、数据库、键/值存储、API 和其他服务）的数据。与所有 模板 一样，查找在 Ansible Automation Platform 控制机器上执行和评估。Ansible 使用标准模板系统提供查找插件返回的数据。您可以使用查找插件加载包含外部来源信息的变量或模板。您还可以 创建自定义查找插件。有关更多信息，请参阅 文档。

ansible.utils 查找插件包括

• ansible.utils.get_path - 使用路径检索变量中的值
• ansible.utils.index_of - 查找列表中与某些条件匹配的项目的索引
• ansible.utils.to_paths - 将复杂对象展平为路径和值的字典
• ansible.utils.validate - 使用提供的条件验证数据

注意：在 ansible.utils 中，一些插件同时作为过滤器和查找插件实现，以便 playbook 开发人员根据其用例灵活选择。

测试插件

测试插件评估模板表达式并返回 True 或 False 值。使用测试插件，您可以创建 条件 来实现任务、块、剧本、playbook 和角色的逻辑。Ansible Automation Platform 使用作为 Jinja 一部分提供的标准测试，并添加了一些专门的测试插件。有关更多信息，请参阅 文档。

ansible.utils 测试插件包括

• ansible.utils.in_any_network - 测试 IP 或网络是否位于任何网络中
• ansible.utils.in_network - 测试 IP 地址是否位于网络中
• ansible.utils.in_one_network - 测试 IP 地址是否属于列表中的任何一个网络
• ansible.utils.ip - 测试 IP 地址或网络中的内容
• ansible.utils.ip_address - 测试 IP 地址中的内容
• ansible.utils.ipv4 - 测试内容是否为 IPv4 地址或网络
• ansible.utils.ipv4_address - 测试内容是否为 IPv4 地址
• ansible.utils.ipv4_hostmask - 测试地址是否为有效的宿主掩码
• ansible.utils.ipv4_netmask - 测试地址是否为有效的网络掩码
• ansible.utils.ipv6 - 测试内容是否为 IPv6 地址或网络
• ansible.utils.ipv6_address - 测试内容是否为 IPv6 地址
• ansible.utils.ipv6_ipv4_mapped - 测试内容是否似乎是映射的 IPv6 到 IPv4 映射地址
• ansible.utils.ipv6_sixtofour - 测试内容是否似乎是 6to4 地址
• ansible.utils.ipv6_teredo - 测试内容是否似乎是 IPv6 teredo 地址
• ansible.utils.loopback - 测试 IP 地址是否为环回地址
• ansible.utils.mac - 测试内容是否似乎是有效的 MAC 地址
• ansible.utils.multicast - 测试多播 IP 地址
• ansible.utils.private - 测试 IP 地址是否为私有地址
• ansible.utils.public - 测试 IP 地址是否为公有地址
• ansible.utils.reserved - 测试保留的 IP 地址
• ansible.utils.resolvable - 测试 IP 或名称是否可以通过 /etc/hosts 或 DNS 解析
• ansible.utils.subnet_of - 测试网络是否为另一个网络的子网
• ansible.utils.supernet_of - 测试网络是否为另一个网络的超网
• ansible.utils.unspecified - 测试未指定的 IP 地址
• ansible.utils.validate - 使用提供的条件验证数据

模块

模块是 Ansible playbook 的主要构建块。虽然我们通常不将“模块插件”一词，但模块是一种插件。有关模块与其他插件之间差异的以开发人员为中心的描述，请参阅 模块和插件：有什么区别？。有关更多信息，请参阅 文档。

ansible.utils 模块包括

• ansible.utils.cli_parse - 使用各种解析器解析 cli 输出或文本
• ansible.utils.fact_diff - 查找当前设置的事实之间的差异
• ansible.utils.update_fact - 更新当前设置的事实
• ansible.utils.validate - 使用提供的条件验证数据

访问和使用 ansible.utils 集合

要下载 utils 集合，请参阅 Automation Hub（完全支持，需要 Red Hat Ansible Automation Platform 订阅）或 Ansible Galaxy（上游）

• Automation Hub 集合：ansible.utils
• Ansible Galaxy 集合：ansible.utils

​​Ansible.utils 也可用于支持的执行环境以及其所需的 Python 库。有关执行环境的更多详细信息，请参阅 文档。

Utils 的不同用例

众所周知，ansible.utils 具有各种插件，并且具有各种用例。以下是 ansible.utils 最常见的用例

• 使用 validate 和 test 插件在推送配置之前验证业务逻辑
• 使用 test 插件审核架构沉积和布局
• 使用 get_path、to_path 插件管理 Ansible playbook 中的复杂数据结构

• 使用测试插件执行与网络地址相关的少量检查
• 使用 cli_parse 和 validate 插件进行运行状态评估

未来范围

以下是一些即将推出的 ansible.utils 功能

• Ipaddr 过滤器插件支持

  • Ipaddr 过滤器旨在在 Ansible 中提供对 netaddr Python 包的接口。
  • 它可以对字符串或项目列表进行操作，测试各种数据以检查它们是否为有效的 IP 地址，并操作输入数据以提取所需信息。
  • ipaddr() 支持各种形式的 IPv4 和 IPv6 地址。
  • 还有其他可用的函数可以操作 IP 子网和 MAC 地址。
  • 我们目前正在努力将 ipaddr 过滤器作为 ansible.utils 集合的一部分提供支持。

• 在 ansible.utils.validation 插件中支持更多数量的验证引擎

  • 目前，validate 插件仅支持 ansible.utils.jsonschema 验证引擎，但计划添加更多验证引擎。

• 支持不同的过滤器插件来操作输入数据

  • 递归插件：remove_keys、replace_keys、keep_keys

为该集合贡献代码

此集合适用于不特定于平台或学科的插件。简单的插件示例应具有通用性。更复杂的示例可以包含现实世界的平台模块，以演示插件在剧本中的实用性。

我们欢迎社区为该集合做出贡献。如果您发现问题，请在 ansible.utils 集合存储库 中打开一个 issue 或创建一个 PR。有关完整详细信息，请参阅 为 Ansible 托管的集合贡献代码。有关为 Ansible 贡献代码的详细信息，请参阅 Ansible 社区指南。

要点和下一步

• ansible.utils 插件使剧本编写体验变得简单流畅
• ansible.utils 插件的实现非常快，因为它们是在本地执行的
• 易于理解、编写、使用以及与其他模块集成
• 作为其插件生态系统，在 ansible.utils 中添加新插件非常容易

第二部分：使用 ansible.utils 集合进行运行状态评估的用例

在 ansible.utils 中，有各种插件可用于网络设备的运行状态评估。在本系列博文的第 1 部分中，我概述了 ansible.utils 集合。如果您尚未阅读第 1 部分，我建议您先阅读，因为我在第 2 部分中将以此信息为基础。我们将以一个用例为例，了解 ansible.utils 集合如何在运行状态评估中发挥作用。

一般来说，状态评估工作流程包含以下步骤

• 检索（真相来源）

  • 从远程主机收集当前运行状态。
  • 将其转换为规范化的结构化数据。结构化数据可以采用 json、yaml 格式或任何其他格式。
  • 存储在清单变量中。

• 验证

  • 以基于标准的格式定义所需状态标准，例如，在 json 模式格式中定义。
  • 在运行时检索运行状态。
  • 根据预定义的标准验证当前状态数据，以识别是否存在任何偏差。

• 修复

  • 实施所需的配置更改以纠正漂移。
  • 将更改报告为审计跟踪。

ansible.utils 集合如何帮助此工作流程？

ansible.utils 集合使检索和解析数据变得更容易，以便随后可以从结构化格式进一步评估它。

使用 Ansible.utils.cli_parse 以结构化格式检索运行状态

此模块作为 ansible.utils 集合的一部分提供。它具有各种解析器，有助于解析 CLI 输出或文本输出。它可以与多个远程主机（如网络、Linux 或 Windows）一起使用。它支持多个解析引擎，并且是可扩展的，这意味着您可以创建自己的解析引擎。它是一个运行命令、解析和设置事实的单一任务。

在 utils 集合可用之前，我们需要编写三个不同的任务来运行命令、解析命令输出并设置事实。但由于有了 cli_parse，我们只需要一个任务即可从“show 命令”输出中返回结构化数据。

让我们看看 ansible.utils.cli_parse 任务的示例

  tasks:

  - name:  Run a command and parse results
    ansible.utils.cli_parse:
        command: show interfaces
        parser:
            name: ansible.utils.xxxx
            set_fact: interfaces

在此任务中，我们需要提供将在设备上执行的命令。解析器（它是 cli_parse 的子插件），plugin.set_fact 将转换后的结构设置在 interfaces 键中。然后，我们可以在剧本中引用 interfaces 键。

上述任务将执行以下操作

• 在设备上运行命令
• 使用“xxxx”引擎解析
• 使用默认模板文件夹
• 将解析后的数据设置为事实
• 将命令输出作为 stdout 返回

目前，ansible.utils.cli_parse 插件具有以下解析器

• ansible.utils.textfsm：用于解析半格式化文本的 Python 模块
• ansible.utils.ttp：基于模板的解析，低正则表达式使用，类似 Jinja 的 DSL
• ansible.netcommon.native：内部 Jinja、正则表达式、yaml，无需额外的第三方库
• ansible.netcommon.ntc_templates：作为 Python 库打包的预定义 textfsm 模板
• ansible.netcommon.pyats：Cisco 测试自动化和验证解决方案（11 个操作系统/2500 个解析器）
• ansible.utils.from_xml：使用 xmltodict 将 XML 转换为 json

所有通用解析器都是 ansible.utils 集合的一部分，所有与网络相关的解析器都是 ansible.netcommon 集合的一部分。

使用 ansible.utils.validate 验证结构化数据并报告错误

Ansible.utils.validate 模块是一个新的模块，作为 ansible.utils 集合的一部分提供，适用于所有平台。它具有可扩展的引擎支持，目前与 jsonschema 验证引擎一起使用，该引擎在底层使用 jsonschema python 库。它是一个单一任务，读取结构化数据并根据任务中提供的模型对其进行验证。如果数据根据模式有效或无效，此任务将报告成功或错误。

让我们看看 ansible.utils.validate 任务的示例

tasks:

- name:  Validate structured data
   ansible.utils.validate:
       data: "{{ input_data }}"
       criteria:
       - "{{ lookup('file', './criteria.json') | from_json }}"
       engine: ansible.utils.xxxx

在此任务中，我们需要提供应该为结构化数据的 data。criteria 是标准列表。由于我们目前使用的是 jsonschema，因此我们以 json 格式提供 criteria。engine 是顶级 validate 插件的子插件。这里它是 ansible.utils.jsonschema。同样，您可以编写自己的引擎，因为它具有可扩展性。

上述任务将执行以下操作

• 读取输入 JSON 数据和数据标准（模式模式）
• 使用“xxxx”引擎验证
• 如果数据不符合模式标准，则返回错误列表

目前，ansible.utils.validate 插件支持以下验证引擎

• ansible.utils.jsonschema：Python 模块，用于根据模式验证 json 数据。

现在让我们使用 ansible.utils 中的上述插件来了解如何在实际场景中使用它们。在此示例中，我们将了解如何使用 ansible.utils 获取 BGP 运行状态数据，根据预定义的 json 模式对其进行验证，以及在检测到配置漂移时对其进行修复。

对于此场景，假设我们有三个正在运行 Cisco IOS XE 的 CSRv 路由器。它们彼此之间都是 BGP 邻居，并分别通告三个网络。

让我们检查与 BGP 相关的运行配置和运行状态数据。

让我们检查 CSRv1 节点。让我们执行命令 show running-config | section bgp。如您所见，它配置了两个邻居，其中两个邻居都具有相同的远程 AS，因此它们是 IBGP 邻居。这些邻居处于激活状态，并且在它们上面启用了入站软重新配置。此节点还通告了三个网络。

现在让我们执行命令 show bgp summary。

以上屏幕截图告诉我们与其他两个节点建立的邻居关系，以及当前节点从其他两个节点接收的 3 个前缀。

现在让我们使用路由表条目进行验证。让我们执行命令 show ip route bgp。

以上屏幕截图显示了节点 1 的路由表条目。如您所见，此节点知道六条路由，下一跳是分别通告它们的 BGP 邻居。

类似地，我们配置了 CSRv2 和 CSRv3。

现在让我们检查在此示例中使用的剧本以及详细步骤。

如果您想了解更多详细信息，请查看此 代码。

剧本分为两个部分

• 收集事实并将它们存储在 yaml 文件中作为真相来源 (SOT)
• 根据 SOT 验证结构化数据，并在检测到漂移时进行纠正

收集事实并将其存储在 yaml 文件中以用于 SOT

让我们检查 facts.yaml 的内容。

在第一个任务中，我们从目标设备收集 bgp_global 和 bgp_address_family 事实。在第二个任务中，我们将它们存储在 hostvars 目录下的平面文件中。这些文件将充当目标设备上 BGP 配置的 SOT（真相来源）。

让我们使用 ansible-navigator run playbooks/facts.yaml 命令运行上述剧本。有关更多详细信息，请参阅 ansible-navigator 文档。

执行剧本后，此数据是什么样子？让我们检查 playbooks/host_vars/csrv-1.yaml。

根据 SOT 验证结构化数据，并在检测到漂移时进行纠正

在此步骤中，我们将检查拓扑中所有节点的 BGP 运行状态数据，然后确定它们是否按预期运行或是否存在任何配置漂移。

现在让我们看看 playbooks/verify.yaml 剧本，它将验证并纠正存在的漂移。

在第一个任务中，我们使用了 ansible.utils.cli_parse 插件在目标设备上执行 show ip route bgp 命令，然后将此命令的输出传递给 pyats 解析器。

然后，pyats 解析器将输出转换为结构化数据，并将其存储在 result 变量中。

在下一个任务中，我们将 result 变量中的值以及预定义的模式传递给 ansible.utils.validate 插件。然后，插件使用 jsonschema 引擎将数据与模式或标准进行比较。每个节点都有一个模式文件，定义了它们从其他两个邻居接收的前缀范围。

正如我们从拓扑和 CLI 中看到的，这些节点应该从每个邻居节点接收六条路由（总共三条）。现在，这些前缀在模式中以模式表示，以及其他属性，如 source_protocol、route_preferences、metric 和 active 状态。

模式还将 additional properties 设置为 false，并将属性的最小值和最大值定义为六。这确保了根据模式进行验证始终会告诉我们设备是否正在接收它们应该接收的路由集，而不是其他路由。

以下是节点 CSRv1 的 模式文件 示例。

让我们进一步检查 verify.yaml 的任务

如果第二个任务中的模式验证失败，则剧本将进入 rescue 部分。在这里，我们使用了 BGP 资源模块来强制执行我们之前保存在目标设备上的 yaml 文件中的 SOT。最终结果将是修复导致运行状态验证失败的任何配置漂移。

如果我们使用ansible-navigator run playbooks/verify.yaml命令执行verify.yaml playbook，由于我们没有对任何目标设备进行更改，因此可以看到它们按预期工作并且模式验证通过。有关更多详细信息，请参阅ansible-navigator 文档。

让我们手动在所有设备上引入错误更改。然后我们将再次运行相同的 playbook 并查看它的行为。让我们删除路由以进行它们正在宣传的错误更改。

现在我们已对所有路由器进行了更改。让我们使用ansible-navigator run playbooks/verify.yaml再次运行 playbook。

这次模式验证失败。执行修复任务，并在所有三个节点上添加缺少前缀的事实。让我们详细了解一下。

第一个任务，像往常一样，获取 show 命令的输出并将其转换为结构化数据。

第二个任务失败，因为模式验证出现多个错误而失败。数据与模式中定义的约束不匹配。这会导致修复任务一个接一个地执行。

修复任务完成后，配置 BGP 任务没有显示任何更改，因为我们没有对 BGP 全局属性进行任何更改。

第二个任务是 BGP 地址族检测漂移并重新配置缺少的前缀的地方。

正如我们在所有目标设备发送的命令中看到的，playbook 会向已删除的路由添加事实。

如果我们再次运行此 playbook，它将是幂等的，并且不会报告任何更改，从而表明一切按预期工作。

在生产环境中，此 playbook 可以根据外部事件触发，也可以在 Red Hat Ansible Automation Platform 的 Automation Controller 中作为定期作业安排，以确保符合预期的运行状态。

要点和后续步骤

如上所示，ansible.utils 集合：

• 使运行状态评估更容易，补充了 Ansible Automation Platform 的配置管理功能。
• 充当收集整个清单的运行状态的单一入口点。
• 提供了一种标准化的方式来定义和验证作为结构化数据模型的运行标准。
• 在 Automation Controller 中将运行状态评估步骤添加为工作流模板，该模板可以触发其他事件，例如运行用于自动修复的 playbook 或向外部工具报告等。