Windows 模块开发流程

在本节中，我们将逐步介绍如何开发、测试和调试 Ansible Windows 模块。

由于 Windows 模块是用 Powershell 编写的，并且需要在 Windows 主机上运行，因此本指南与通常的开发流程指南有所不同。

本节内容

Windows 环境设置

与可以在运行 Ansible 的主机上运行的 Python 模块开发不同，Windows 模块需要为 Windows 主机编写和测试。虽然可以从 Microsoft 下载 Windows 的评估版，但这些映像通常在没有进一步修改的情况下无法被 Ansible 使用。设置 Windows 主机以便它可以被 Ansible 使用的最简单方法是使用 Vagrant 设置虚拟机。Vagrant 可用于下载称为“盒子”的现有操作系统映像，然后将这些映像部署到诸如 VirtualBox 之类的虚拟化程序中。这些盒子可以离线创建和存储，也可以从称为 Vagrant Cloud 的中央存储库下载。

本指南将使用由 packer-windoze 存储库创建的 Vagrant 盒子，这些盒子也已上传到 Vagrant Cloud。要了解有关如何创建这些映像的更多信息，请访问 GitHub 存储库并查看 README 文件。

在开始之前，必须安装以下程序（有关安装说明，请参阅 Vagrant 和 VirtualBox 文档）

  • Vagrant

  • VirtualBox

在虚拟机中创建 Windows 服务器

要创建一个 Windows Server 2016 实例，请运行以下命令：

vagrant init jborean93/WindowsServer2016
vagrant up

这将从 Vagrant Cloud 下载 Vagrant 盒子，并将其添加到主机上的本地盒子中，然后在 VirtualBox 中启动该实例。首次启动时，Windows 虚拟机将运行 sysprep 过程，然后自动创建一个 HTTP 和 HTTPS WinRM 侦听器。Vagrant 将在侦听器上线后完成其过程，之后 Ansible 可以使用该虚拟机。

创建 Ansible 清单

以下 Ansible 清单文件可用于连接到新创建的 Windows 虚拟机：

[windows]
WindowsServer  ansible_host=127.0.0.1

[windows:vars]
ansible_user=vagrant
ansible_password=vagrant
ansible_port=55986
ansible_connection=winrm
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore

注意

端口 55986 由 Vagrant 自动转发到创建的 Windows 主机，如果它与现有的本地端口冲突，则 Vagrant 将自动随机使用另一个端口并在输出中显示。

创建的操作系统基于映像集。可以使用以下映像：

当主机联机时，可以通过 127.0.0.1:3389 上的 RDP 访问它，但端口可能会因是否存在冲突而有所不同。要删除主机，请运行 vagrant destroy --force，Vagrant 将自动删除虚拟机以及与该虚拟机关联的任何其他文件。

虽然这在单个 Windows 实例上测试模块时很有用，但这些主机在不进行修改的情况下无法与基于域的模块一起使用。位于 ansible-windows 的 Vagrantfile 可用于创建要在 Ansible 中使用的测试域环境。此存储库包含三个文件，Ansible 和 Vagrant 都使用这些文件在域环境中创建多个 Windows 主机。这些文件是：

  • Vagrantfile：读取 inventory.yml 的清单设置并配置所需主机的 Vagrant 文件

  • inventory.yml：包含所需主机和其他连接信息，例如 IP 地址和转发端口

  • main.yml：Vagrant 调用的 Ansible playbook，用于配置域控制节点并将子主机加入域

默认情况下，这些文件将创建以下环境：

  • 在 Windows Server 2016 上运行的单个 AD 域控制器

  • 五个加入该域的每个主要 Windows Server 版本的子主机

  • DNS 名称为 domain.local 的域

  • 每个主机上的本地管理员帐户，用户名为 vagrant，密码为 vagrant

  • 域管理员帐户 [email protected]，密码为 VagrantPass1

如果需要，可以通过更改 inventory.yml 文件中的变量 domain_* 来修改域名称和帐户。还可以通过更改 domain_children 键下定义的主机来修改清单文件以配置更多或更少的服务器。主机变量 ansible_host 是将分配给 VirtualBox 主机专用网络适配器的私有 IP，而 vagrant_box 是将用于创建虚拟机的盒子。

配置环境

要按原样配置环境，请运行以下命令：

git clone https://github.com/jborean93/ansible-windows.git
cd vagrant
vagrant up

注意

Vagrant 按顺序配置每个主机，因此这可能需要一些时间才能完成。如果在设置域的 Ansible 阶段发生任何错误，请运行 vagrant provision 以重新运行该步骤。

与使用 Vagrant 设置单个 Windows 实例不同，这些主机也可以使用 IP 地址直接访问，以及通过转发端口访问。通过主机专用网络适配器访问它更容易，因为使用了正常的协议端口，例如 RDP 仍然通过 3389。在无法使用主机专用网络 IP 解析主机的情况下，可以使用以下协议通过 127.0.0.1 访问这些转发端口：

  • RDP：295xx

  • SSH：296xx

  • WinRM HTTP：297xx

  • WinRM HTTPS：298xx

  • SMB：299xx

将 xx 替换为清单文件中域控制器的条目编号，域控制器从 00 开始，并从此递增。例如，在默认的 inventory.yml 文件中，SERVER2012R2 的 WinRM 通过 HTTPS 在端口 29804 上转发，因为它在 domain_children 中是第四个条目。

Windows 模块新开发

创建新模块时，需要注意以下几点

  • 模块代码位于 Powershell (.ps1) 文件中，而文档则包含在同名的 Python (.py) 文件中

  • 避免在模块中使用 Write-Host/Debug/Verbose/Error，并将需要返回的内容添加到 $module.Result 变量中

  • 要使模块失败，请调用 $module.FailJson("failure message here")，可以将异常或 ErrorRecord 设置为第二个参数以获得更详细的错误消息

  • 您可以将异常或 ErrorRecord 作为第二个参数传递给 FailJson("failure", $_) 以获得更详细的输出

  • 大多数新模块在合并到 Ansible 主代码库之前都需要检查模式和集成测试

  • 避免在大型代码块上使用 try/catch 语句，而是在单个调用中使用它们，以便错误消息更具描述性

  • 在使用 try/catch 语句时，尝试捕获特定的异常

  • 除非必要，否则避免使用 PSCustomObjects

  • 在 ./lib/ansible/module_utils/powershell/ 中查找常用函数，并使用其中的代码，而不是重复工作。这些可以通过添加行 #Requires -Module * 来导入，其中 * 是要导入的文件名，并在通过 Ansible 运行时自动包含在发送到 Windows 目标的模块代码中

  • 除了 PowerShell 模块实用程序之外，C# 模块实用程序还存储在 ./lib/ansible/module_utils/csharp/ 中，如果存在行 #AnsibleRequires -CSharpUtil *，则会在模块执行期间自动导入

  • C# 和 PowerShell 模块实用程序实现了相同目标，但 C# 允许开发人员实现低级任务，例如调用 Win32 API，并且在某些情况下速度更快

  • 确保代码在 Windows Server 2016 及更高版本上运行在 Powershell v5.1 及更高版本下；如果需要更高的最低 Powershell 或操作系统版本，请确保文档清楚地反映这一点

  • Ansible 在严格模式版本 2.0 下运行模块。请确保通过在开发脚本的顶部放置 Set-StrictMode -Version 2.0 来启用该功能进行测试

  • 如果可能，优先使用本地 Powershell cmdlet 而不是可执行文件调用

  • 使用完整的 cmdlet 名称而不是别名，例如 Remove-Item 而不是 rm

  • 使用带 cmdlet 的命名参数，例如 Remove-Item -Path C:\temp 而不是 Remove-Item C:\temp

一个非常基本的 Powershell 模块 win_environment 集成了 Powershell 模块的最佳实践。它演示了如何实现检查模式和差异支持，还显示了在满足特定条件时向用户显示的警告。

一个稍微高级一点的模块是 win_uri，它还展示了如何使用不同的参数类型（bool、str、int、list、dict、path）和参数的选择，如何使模块失败以及如何处理异常。

作为新的 AnsibleModule 包装器的一部分，输入参数是根据参数规范定义和验证的。以下选项可以在参数规范的根级别设置

  • mutually_exclusive：列表的列表，其中内部列表包含不能一起设置的模块选项

  • no_log：停止模块向 Windows 事件日志发出任何日志

  • options：字典，其中键是模块选项，值是该选项的规范

  • required_by：字典，其中如果键指定的选项也已设置，则值指定的选项必须设置

  • required_if：列表的列表，其中内部列表包含 3 或 4 个元素；

    • 第一个元素是要检查其值的模块选项

    • 第二个元素是第一个元素指定的选项的值，如果匹配，则运行 required if 检查

    • 第三个元素是在上述匹配时所需的模块选项列表

    • 可选的第四个元素是一个布尔值，表示第三个元素中的所有模块选项是否都必需（默认值：$false）或仅一个（$true）

  • required_one_of：列表的列表，其中内部列表包含必须至少设置一个的模块选项

  • required_together：列表的列表，其中内部列表包含必须一起设置的模块选项

  • supports_check_mode：模块是否支持检查模式，默认情况下为 $false

模块的实际输入选项在 options 值中作为字典设置。此字典的键是模块选项名称，而值是该模块选项的规范。每个规范都可以设置以下选项

  • aliases：模块选项的别名列表

  • choices：模块选项的有效值列表，如果 type=list，则每个列表值都针对选项进行验证，而不是列表本身

  • default：如果未设置，则为模块选项的默认值

  • deprecated_aliases：哈希表的列表，定义已弃用的别名以及将在其中删除的版本。每个条目都必须包含键 name 和 collection_name，以及 version 或 date

  • elements：当 type=list 时，这将设置每个列表值的类型，这些值与 type 相同

  • no_log：在 module_invocation 返回值中返回之前，将对输入值进行清理

  • removed_in_version：说明何时删除已弃用的模块选项，如果设置，则会向最终用户显示警告

  • removed_at_date：说明已弃用的模块选项将被删除的日期 (YYYY-MM-DD)，如果设置，则会向最终用户显示警告

  • removed_from_collection：说明将从哪个集合中删除已弃用的模块选项；如果指定了 removed_in_version 和 removed_at_date 中的一个，则必须指定此选项

  • required：当未设置模块选项时将失败

  • type：模块选项的类型，如果未设置，则默认为 str。有效类型为；

    • bool：布尔值

    • dict：字典值，如果输入是 JSON 或 key=value 字符串，则将其转换为字典

    • float：浮点数或 Single 值

    • int：Int32 值

    • json：字符串，如果输入是字典，则将值转换为 JSON 字符串

    • list：值列表，elements=<type> 可以转换单个列表值类型（如果设置）。如果 elements=dict，则定义 options，值将针对参数规范进行验证。当输入是字符串时，字符串将以 , 分隔，并且任何空格都将被修剪

    • path：字符串，其中类似 %TEMP% 的值根据环境值扩展。如果输入值以 \\?\ 开头，则不运行扩展

    • raw: Ansible 传入的值不会进行任何转换

    • sid: 会将 Windows 安全标识符值或 Windows 帐户名称转换为 SecurityIdentifier 值

    • str: 该值将转换为字符串

当 type=dict 或 type=list 且 elements=dict 时，还可以为该模块选项设置以下键

  • apply_defaults: 如果 True，则该值基于该键的 options 规范默认值；如果 False，则为 null。仅当用户未定义模块选项且 type=dict 时有效。

  • mutually_exclusive: 与根级别的 mutually_exclusive 相同，但针对子字典中的值进行验证

  • options: 与根级别的 options 相同，但包含子选项的有效选项

  • required_if: 与根级别的 required_if 相同，但针对子字典中的值进行验证

  • required_by: 与根级别的 required_by 相同，但针对子字典中的值进行验证

  • required_together: 与根级别的 required_together 相同，但针对子字典中的值进行验证

  • required_one_of: 与根级别的 required_one_of 相同，但针对子字典中的值进行验证

模块类型也可以是一个委托函数，它将值转换为模块选项所需的任何内容。例如，以下代码片段显示了如何创建自定义类型以创建 UInt64 值

$spec = @{
    uint64_type = @{ type = [Func[[Object], [UInt64]]]{ [System.UInt64]::Parse($args[0]) } }
}
$uint64_type = $module.Params.uint64_type

如有疑问，请查看一些其他核心模块，并了解如何在其中实现这些功能。

有时，Windows 提供了多种完成任务的方法；编写模块时，应优先考虑以下顺序

  • 本机 PowerShell cmdlet，例如 Remove-Item -Path C:\temp -Recurse

  • .NET 类，例如 [System.IO.Path]::GetRandomFileName()

  • 通过 New-CimInstance cmdlet 的 WMI 对象

  • 通过 New-Object -ComObject cmdlet 的 COM 对象

  • 对本机可执行文件的调用，例如 Secedit.exe

PowerShell 模块支持 PowerShell 中内置的 #Requires 选项的一个小子集，以及由 #AnsibleRequires 指定的一些 Ansible 特定要求。这些语句可以放在脚本中的任何位置，但最常见的是靠近顶部。它们用于更轻松地声明模块的要求，而无需编写任何检查。每个 requires 语句必须位于自己的行上，但一个脚本中可以有多个 requires 语句。

这些是在 Ansible 模块中可以使用检查

  • #Requires -Module Ansible.ModuleUtils.<module_util>: 在 Ansible 2.4 中添加，指定要为模块执行加载的 module_util。

  • #Requires -Version x.y: 在 Ansible 2.5 中添加，指定模块所需 PowerShell 的版本。如果未满足此要求，则模块将失败。

  • #AnsibleRequires -PowerShell <module_util>: 在 Ansible 2.8 中添加，类似于 #Requires -Module，它指定要为模块执行加载的 module_util。

  • #AnsibleRequires -CSharpUtil <module_util>: 在 Ansible 2.8 中添加，指定要为模块执行加载的 C# module_util。

  • #AnsibleRequires -OSVersion x.y: 在 Ansible 2.5 中添加，指定模块所需的 OS 构建版本，如果不满足此要求，则模块将失败。实际的 OS 版本来自 [Environment]::OSVersion.Version。

  • #AnsibleRequires -Become: 在 Ansible 2.5 中添加，强制 exec 运行器使用 become 运行模块，这主要用于绕过 WinRM 限制。如果未指定 ansible_become_user，则使用 SYSTEM 帐户。

The #AnsibleRequires -PowerShell 和 #AnsibleRequires -CSharpUtil 支持更多功能，例如

  • 导入集合中包含的 util（在 Ansible 2.9 中添加）

  • 通过相对名称导入 util（在 Ansible 2.10 中添加）

  • 通过在导入声明中添加 -Optional 来指定 util 是可选的（在 Ansible 2.12 中添加）。

有关更多详细信息，请参阅以下示例

# Imports the PowerShell Ansible.ModuleUtils.Legacy provided by Ansible itself
#AnsibleRequires -PowerShell Ansible.ModuleUtils.Legacy

# Imports the PowerShell my_util in the my_namesapce.my_name collection
#AnsibleRequires -PowerShell ansible_collections.my_namespace.my_name.plugins.module_utils.my_util

# Imports the PowerShell my_util that exists in the same collection as the current module
#AnsibleRequires -PowerShell ..module_utils.my_util

# Imports the PowerShell Ansible.ModuleUtils.Optional provided by Ansible if it exists.
# If it does not exist then it will do nothing.
#AnsibleRequires -PowerShell Ansible.ModuleUtils.Optional -Optional

# Imports the C# Ansible.Process provided by Ansible itself
#AnsibleRequires -CSharpUtil Ansible.Process

# Imports the C# my_util in the my_namespace.my_name collection
#AnsibleRequires -CSharpUtil ansible_collections.my_namespace.my_name.plugins.module_utils.my_util

# Imports the C# my_util that exists in the same collection as the current module
#AnsibleRequires -CSharpUtil ..module_utils.my_util

# Imports the C# Ansible.Optional provided by Ansible if it exists.
# If it does not exist then it will do nothing.
#AnsibleRequires -CSharpUtil Ansible.Optional -Optional

对于可选的 require 语句，模块代码需要在尝试使用 util 之前验证是否已导入 util。这可以通过检查 util 提供的函数或类型是否存在来完成。

虽然 #Requires -Module 和 #AnsibleRequires -PowerShell 都可以用来加载 PowerShell 模块，但建议使用 #AnsibleRequires。这是因为 #AnsibleRequires 支持集合模块 util、通过相对 util 名称导入以及可选的 util 导入。

C# 模块 util 可以通过在脚本顶部的所有其他 using 语句中添加行 using Ansible.<module_util>; 来引用其他 C# util。

Windows 模块实用程序

与 Python 模块类似，PowerShell 模块还提供许多模块实用程序，这些实用程序在 PowerShell 中提供辅助函数。这些 module_utils 可以通过在 PowerShell 模块中添加以下行来导入

#Requires -Module Ansible.ModuleUtils.Legacy

这将导入位于 ./lib/ansible/module_utils/powershell/Ansible.ModuleUtils.Legacy.psm1 的 module_util，并启用对其所有函数的调用。从 Ansible 2.8 开始，Windows 模块 util 也可以用 C# 编写，并存储在 lib/ansible/module_utils/csharp 中。这些 module_utils 可以通过在 PowerShell 模块中添加以下行来导入

#AnsibleRequires -CSharpUtil Ansible.Basic

这将导入位于 ./lib/ansible/module_utils/csharp/Ansible.Basic.cs 的 module_util，并自动加载正在执行进程中的类型。C# 模块 util 可以相互引用并通过在 util 顶部的 using 语句中添加以下行来一起加载

using Ansible.Become;

可以在 C# 文件中设置一些特殊的注释，用于控制编译参数。以下注释可以添加到脚本中；

  • //AssemblyReference -Name <assembly dll> [-CLR [Core|Framework]]: 编译期间要引用的程序集 DLL，可选的 -CLR 标志也可用于说明在 .NET Core、Framework 或两者下运行时是否要引用（如果省略）

  • //NoWarn -Name <error id> [-CLR [Core|Framework]]: 在编译代码时要忽略的编译器警告 ID，可选的 -CLR 与上面一样。可以在 编译器错误 中找到警告列表

此外，还定义了以下预处理器符号；

  • CORECLR: 当 PowerShell 通过 .NET Core 运行时，此符号存在

  • WINDOWS: 当 PowerShell 在 Windows 上运行时，此符号存在

  • UNIX: 当 PowerShell 在 Unix 上运行时，此符号存在

这些标志的组合有助于使模块 util 在 .NET Framework 和 .NET Core 上都能够互操作，以下是一个示例

#if CORECLR
using Newtonsoft.Json;
#else
using System.Web.Script.Serialization;
#endif

//AssemblyReference -Name Newtonsoft.Json.dll -CLR Core
//AssemblyReference -Name System.Web.Extensions.dll -CLR Framework

// Ignore error CS1702 for all .NET types
//NoWarn -Name CS1702

// Ignore error CS1956 only for .NET Framework
//NoWarn -Name CS1956 -CLR Framework

以下是与 Ansible 打包的 module_utils 列表以及它们的功能概述

  • ArgvParser: 用于将参数列表转换为符合 Windows 参数解析规则的转义字符串的实用程序。

  • CamelConversion: 用于将 camelCase 字符串/列表/字典转换为 snake_case 的实用程序。

  • CommandUtil: 用于执行 Windows 进程并将 stdout/stderr 和 rc 作为单独的对象返回的实用程序。

  • FileUtil: 扩展了 Get-ChildItem 和 Test-Path 以处理特殊文件（如 C:\pagefile.sys）的实用程序。

  • Legacy: Ansible 模块的一般定义和辅助实用程序。

  • LinkUtil: 用于创建、删除和获取符号链接、联接点和硬链接信息的实用程序。

  • SID: 用于将用户或组转换为 Windows SID 反之亦然的实用程序。

有关任何特定模块实用程序及其要求的更多详细信息，请参阅 Ansible 模块实用程序源代码。

PowerShell 模块实用程序可以存储在 Ansible 标准发行版之外，用于自定义模块。自定义 module_utils 放在名为 module_utils 的文件夹中，该文件夹位于剧本或角色目录的根文件夹中。

C# 模块实用程序也可以存储在标准 Ansible 发行版之外，用于自定义模块。与 PowerShell 实用程序类似，它们存储在名为 module_utils 的文件夹中，并且文件名必须以扩展名 .cs 结尾，以 Ansible. 开头，并以实用程序中定义的命名空间命名。

以下示例是一个角色结构，其中包含两个名为 Ansible.ModuleUtils.ModuleUtil1 和 Ansible.ModuleUtils.ModuleUtil2 的 PowerShell 自定义 module_utils，以及一个包含命名空间 Ansible.CustomUtil 的 C# 实用程序。

meta/
  main.yml
defaults/
  main.yml
module_utils/
  Ansible.ModuleUtils.ModuleUtil1.psm1
  Ansible.ModuleUtils.ModuleUtil2.psm1
  Ansible.CustomUtil.cs
tasks/
  main.yml

每个 PowerShell module_util 必须包含至少一个已使用 Export-ModuleMember 在文件末尾导出的函数。例如

Export-ModuleMember -Function Invoke-CustomUtil, Get-CustomInfo

公开共享模块选项

PowerShell 模块实用程序可以轻松公开模块在构建其参数规范时可以使用的常用模块选项。这允许将常用功能存储和维护在一个位置，并让多个模块以最小的努力使用这些功能。然后，添加到这些实用程序之一的任何新功能或错误修复都会被调用该实用程序的各个模块自动使用。

例如，可以有一个处理 API 身份验证和通信的模块实用程序。多个模块可以使用此实用程序来公开一组通用的模块选项，例如 API 端点、用户名、密码、超时、证书验证等，而无需将这些选项添加到每个模块规范中。

具有共享参数规范的模块实用程序的标准约定将具有

  • 一个 Get-<namespace.name.util name>Spec 函数，该函数输出模块的通用规范

    • 强烈建议使此函数名称对模块唯一，以避免与可以加载的其他实用程序发生任何冲突

    • 输出规范的格式与用于普通模块的 $spec 格式相同的哈希表

  • 一个接收 AnsibleModule 对象的函数，该对象在 -Module 参数下被调用，它可以使用该参数获取共享选项

由于这些选项可以在各种模块之间共享，因此强烈建议在共享规范中尽可能具体地保留模块选项名称和别名。例如，不要使用名为 password 的实用程序选项，而应在其前面加上唯一的名称，例如 acme_password。

警告

如果选项名称或别名不唯一，则可能会阻止实用程序被也使用这些名称或别名作为其自身选项的模块使用。

以下是名为 ServiceAuth.psm1 的示例模块实用程序，它位于一个集合中，并实现了模块与服务进行身份验证的常用方法。

Invoke-MyServiceResource {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory=$true)]
        [ValidateScript({ $_.GetType().FullName -eq 'Ansible.Basic.AnsibleModule' })]
        $Module,

        [Parameter(Mandatory=$true)]
        [String]
        $ResourceId,

        [String]
        $State = 'present'
    )

    # Process the common module options known to the util
    $params = @{
        ServerUri = $Module.Params.my_service_url
    }
    if ($Module.Params.my_service_username) {
        $params.Credential = Get-MyServiceCredential
    }

    if ($State -eq 'absent') {
        Remove-MyService @params -ResourceId $ResourceId
    } else {
        New-MyService @params -ResourceId $ResourceId
    }
}

Get-MyNamespaceMyCollectionServiceAuthSpec {
    # Output the util spec
    @{
        options = @{
            my_service_url = @{ type = 'str'; required = $true }
            my_service_username = @{ type = 'str' }
            my_service_password = @{ type = 'str'; no_log = $true }
        }

        required_together = @(
            ,@('my_service_username', 'my_service_password')
        )
    }
}

$exportMembers = @{
    Function = 'Get-MyNamespaceMyCollectionServiceAuthSpec', 'Invoke-MyServiceResource'
}
Export-ModuleMember @exportMembers

对于要利用此通用参数规范的模块，可以将其设置为

#!powershell

# Include the module util ServiceAuth.psm1 from the my_namespace.my_collection collection
#AnsibleRequires -PowerShell ansible_collections.my_namespace.my_collection.plugins.module_utils.ServiceAuth

# Create the module spec like normal
$spec = @{
    options = @{
        resource_id = @{ type = 'str'; required = $true }
        state = @{ type = 'str'; choices = 'absent', 'present' }
    }
}

# Create the module from the module spec but also include the util spec to merge into our own.
$module = [Ansible.Basic.AnsibleModule]::Create($args, $spec, @(Get-MyNamespaceMyCollectionServiceAuthSpec))

# Call the ServiceAuth module util and pass in the module object so it can access the module options.
Invoke-MyServiceResource -Module $module -ResourceId $module.Params.resource_id -State $module.params.state

$module.ExitJson()

注意

在模块规范中定义的选项将始终优先于实用程序规范。实用程序规范中相同键下的任何列表值都将附加到该相同键的模块规范中。字典值将添加模块规范中缺少的任何键，并合并任何为列表或字典的值。这类似于文档片段插件在扩展模块文档时的工作方式。

要为模块记录这些共享的实用程序选项，请创建一个记录模块实用程序实现的选项的文档片段插件，并扩展实现该实用程序的每个模块的模块文档，以将其文档中的该片段包含在内。

Windows playbook 模块测试

可以使用 Ansible playbook 测试模块。例如

  • 在任何目录中创建一个 playbook touch testmodule.yml。

  • 在同一目录中创建一个清单文件 touch hosts。

  • 使用连接到 Windows 主机所需的变量填充清单文件。

  • 将以下内容添加到新的 playbook 文件中

---
- name: test out windows module
  hosts: windows
  tasks:
  - name: test out module
    win_module:
      name: test name

  • 运行 playbook ansible-playbook -i hosts testmodule.yml

这对于查看 Ansible 如何端到端运行新模块很有用。下面显示了测试模块的其他可能方法。

Windows 调试

目前只能在 Windows 主机上调试模块。这在开发新模块或实施错误修复时很有用。以下是一些设置此功能需要遵循的步骤

  • 将模块脚本复制到 Windows 服务器

  • 将文件夹 ./lib/ansible/module_utils/powershell 和 ./lib/ansible/module_utils/csharp 复制到上述脚本所在的同一目录

  • 在模块代码中任何 #Requires -Module 行的开头添加额外的 #，这仅适用于以 #Requires -Module 开头的任何行

  • 将以下内容添加到复制到服务器的模块脚本的开头

# Set $ErrorActionPreference to what's set during Ansible execution
$ErrorActionPreference = "Stop"

# Set the first argument as the path to a JSON file that contains the module args
$args = @("$($pwd.Path)\args.json")

# Or instead of an args file, set $complex_args to the pre-processed module args
$complex_args = @{
    _ansible_check_mode = $false
    _ansible_diff = $false
    path = "C:\temp"
    state = "present"
}

# Import any C# utils referenced with '#AnsibleRequires -CSharpUtil' or 'using Ansible.;
# The $_csharp_utils entries should be the context of the C# util files and not the path
Import-Module -Name "$($pwd.Path)\powershell\Ansible.ModuleUtils.AddType.psm1"
$_csharp_utils = @(
    [System.IO.File]::ReadAllText("$($pwd.Path)\csharp\Ansible.Basic.cs")
)
Add-CSharpType -References $_csharp_utils -IncludeDebugInfo

# Import any PowerShell modules referenced with '#Requires -Module`
Import-Module -Name "$($pwd.Path)\powershell\Ansible.ModuleUtils.Legacy.psm1"

# End of the setup code and start of the module code
#!powershell

可以根据模块需要向 $complex_args 添加更多参数，或者通过具有以下结构的 JSON 文件定义模块选项

{
    "ANSIBLE_MODULE_ARGS": {
        "_ansible_check_mode": false,
        "_ansible_diff": false,
        "path": "C:\\temp",
        "state": "present"
    }
}

可以使用多种 IDE 来调试 Powershell 脚本，其中两个最流行的是

为了能够查看 Ansible 传递给模块的参数，请遵循以下步骤。

  • 在 Ansible 命令前加上 ANSIBLE_KEEP_REMOTE_FILES=1 以指定 Ansible 应保留服务器上的执行文件。

  • 使用 Ansible 用于执行模块的同一用户帐户登录到 Windows 服务器。

  • 导航到 %TEMP%\..。它应该包含一个以 ansible-tmp- 开头的文件夹。

  • 在此文件夹中，打开模块的 PowerShell 脚本。

  • 在此脚本中，$json_raw 下有一个原始 JSON 脚本，其中包含 module_args 下的模块参数。这些参数可以手动分配给在调试脚本中定义的 $complex_args 变量，或放入 args.json 文件中。

Windows 单元测试

目前没有机制可以在 Ansible CI 下为 Powershell 模块运行单元测试。

Windows 集成测试

Ansible 模块的集成测试通常编写为 Ansible 角色。这些测试角色位于 ./test/integration/targets 中。您必须首先设置测试环境，并为 Ansible 配置一个测试清单以连接。

在此示例中，我们将设置一个测试清单以连接到两个主机并运行 win_stat 的集成测试

  • 运行命令 source ./hacking/env-setup 以准备环境。

  • 创建 ./test/integration/inventory.winrm.template 的副本，并将其命名为 inventory.winrm。

  • 填写 [windows] 下的条目，并设置连接到主机所需的变量。

  • 安装所需的 Python 模块 以支持 WinRM 和已配置的身份验证方法。

  • 要执行集成测试，请运行 ansible-test windows-integration win_stat；您可以用要测试的角色替换 win_stat。

这将执行当前为此角色定义的所有测试。您可以使用 -v 参数设置详细程度级别，就像使用 ansible-playbook 一样。

在为新模块开发测试时，建议在检查模式下测试一次，在非检查模式下测试两次。这确保了检查模式不会进行任何更改，但会报告更改，以及第二次运行是幂等的，并且不会报告更改。例如

- name: remove a file (check mode)
  win_file:
    path: C:\temp
    state: absent
  register: remove_file_check
  check_mode: true

- name: get result of remove a file (check mode)
  win_command: powershell.exe "if (Test-Path -Path 'C:\temp') { 'true' } else { 'false' }"
  register: remove_file_actual_check

- name: assert remove a file (check mode)
  assert:
    that:
    - remove_file_check is changed
    - remove_file_actual_check.stdout == 'true\r\n'

- name: remove a file
  win_file:
    path: C:\temp
    state: absent
  register: remove_file

- name: get result of remove a file
  win_command: powershell.exe "if (Test-Path -Path 'C:\temp') { 'true' } else { 'false' }"
  register: remove_file_actual

- name: assert remove a file
  assert:
    that:
    - remove_file is changed
    - remove_file_actual.stdout == 'false\r\n'

- name: remove a file (idempotent)
  win_file:
    path: C:\temp
    state: absent
  register: remove_file_again

- name: assert remove a file (idempotent)
  assert:
    that:
    - not remove_file_again is changed

Windows 通信和开发支持

加入 Ansible 论坛 并使用 windows 标签讨论有关 Windows Ansible 开发的问题。