Ansible 参考：模块工具

本页面记录了在用 Python 编写 Ansible 模块时有助于开发的工具。

AnsibleModule

要使用此功能，请在模块中包含 from ansible.module_utils.basic import AnsibleModule。

class ansible.module_utils.basic.AnsibleModule(argument_spec, bypass_checks=False, no_log=False, mutually_exclusive=None, required_together=None, required_one_of=None, add_file_common_args=False, supports_check_mode=False, required_if=None, required_by=None)

用于在 Python 中快速构建 Ansible 模块的通用代码（尽管你可以用任何能返回 JSON 的语言编写模块）。

请参阅开发模块了解一般介绍，并参阅Ansible 模块架构了解更详细的说明。

add_path_info(kwargs): 对于结果是文件的情况，在返回路径中补充关于文件路径的统计信息。

atomic_move(src, dest, unsafe_writes=False, keep_dest_attrs=True): 将 src 原子地移动到 dest，并从 dest 复制属性。成功时返回 True。它使用 os.rename 来确保操作的原子性，函数其余部分用于处理限制、边界情况并确保在可能的情况下保存 SELinux 上下文。

backup_local(fn): 为指定文件创建带有日期标记的备份，成功或失败时分别返回 True 或 False。

boolean(arg): 将参数转换为布尔值。

deprecate(msg: str, version: str | None = None, date: str | None = None, collection_name: str | None = None, *, deprecator: PluginInfo | None = None, help_text: str | None = None) → None: 记录一个弃用警告，随模块结果返回。大多数调用者不需要提供 collection_name 或 deprecator —— 如果需要，仅提供其中一个。指定 version 或 date，但不要同时指定两者。如果 date 是字符串，则必须采用 YYYY-MM-DD 格式。

digest_from_file(filename, algorithm): 返回本地文件的十六进制摘要，摘要方法由名称指定，如果文件不存在则返回 None。

error_as_warning(msg: str | None, exception: BaseException, *, help_text: str | None = None) → None: 将异常显示为警告。

exit_json(**kwargs) → NoReturn: 从模块返回，无错误。

fail_json(msg: str, *, exception: BaseException | str | None = <object object>, **kwargs) → NoReturn

从模块返回错误消息和可选的异常/回溯详细信息。仅当启用了错误回溯捕获时，回溯才会包含在结果中。

当 exception 是异常对象时，其消息链将自动与 msg 合并以创建最终的错误消息。消息链包括异常本身的消息以及任何 __cause__ 异常的消息。来自 exception 的回溯将用于格式化的回溯。

当 exception 是字符串时，它将被用作格式化的回溯。

当 exception 设置为 None 时，当前的调用栈将用于格式化的回溯。

当未指定 exception 时，将从当前异常中获取格式化的回溯。如果没有挂起的异常，则使用当前的调用栈。

find_mount_point(path)

接收一个路径并返回其挂载点。

参数:: path – 具有文件系统路径的字符串类型。
返回值:: 作为文本类型的挂载点路径。

get_bin_path(arg, required=False, opt_dirs=None)

在 PATH 中查找系统可执行文件。

参数:

arg – 要查找的可执行文件。
required – 如果找不到可执行文件且 required 为 True，则调用 fail_json。
opt_dirs – 除了 PATH 之外，可选的搜索目录列表。

返回值:

如果找到则返回完整路径；否则返回原始 arg，除非标记为“警告”，此时返回 None。

引发:

系统退出：如果找不到 arg 且 required=True（通过 fail_json）。

is_executable(path)

给定的路径是否可执行？

参数:: path – 要检查的文件路径。

限制

不考虑 FSACL。
大多数时候我们真正想知道的是“当前用户能否执行此文件”。此函数不提供该信息，仅说明是否设置了任何执行位。

is_special_selinux_path(path): 如果给定路径位于 NFS 或其他“特殊”文件系统挂载点上，则返回包含 (True, selinux_context) 的元组，否则返回 (False, None)。

load_file_common_arguments(params, path=None)

许多模块处理文件，这封装了 file 模块接受的常用选项，以便所有模块都可以直接使用并共享代码。

允许通过提供 path 来覆盖路径/dest 模块参数。

md5(filename)

使用 digest_from_file() 返回本地文件的 MD5 十六进制摘要。

除非别无选择，否则不要使用此函数，例如：

可选的向后兼容性。
与第三方协议的兼容性。

此函数在符合 FIPS-140-2 的系统上无法工作。

该函数的大多数用法可以用 module.sha1 函数替代。

preserved_copy(src, dest): 复制文件并保留所有权、权限和上下文。

run_command(args, check_rc=False, close_fds=True, executable=None, data=None, binary_data=False, path_prefix=None, cwd=None, use_unsafe_shell=False, prompt_regex=None, environ_update=None, umask=None, encoding='utf-8', errors='surrogate_or_strict', expand_user_and_vars=True, pass_fds=None, before_communicate_callback=None, ignore_invalid_cwd=True, handle_exceptions=True)

执行命令，返回 rc、stdout 和 stderr。

此方法读取 stdout 和 stderr 的机制与 CPython 的 subprocess.Popen.communicate 不同，因为该方法在产生的命令退出且 stdout 和 stderr 被消耗后就会停止读取，而不是等到 stdout/stderr 关闭。当考虑到派生或后台进程可能持有 stdout 或 stderr 的时间比产生的命令更长时，这可能是一个重要的区别。

参数:: args – 是要运行的命令。* 如果 args 是列表，则命令将以 shell=False 运行。* 如果 args 是字符串且 use_unsafe_shell=False，它会将 args 分割成列表并以 shell=False 运行。* 如果 args 是字符串且 use_unsafe_shell=True，它将以 shell=True 运行。
Kw check_rc:: 如果 RC 非零，是否调用 fail_json。默认值为 False。
Kw close_fds:: 请参阅 subprocess.Popen() 的文档。默认值为 True。
Kw executable:: 请参阅 subprocess.Popen() 的文档。默认值为 None。
Kw data:: 如果提供，则写入命令 stdin 的信息。
Kw binary_data:: 如果为 False，则在数据末尾附加换行符。默认值为 False。
Kw path_prefix:: 如果提供，则为查找命令的额外路径。这会添加到 PATH 环境变量中，以便也能找到同一目录下的辅助命令。
Kw cwd:: 如果提供，则为运行命令的工作目录。
Kw use_unsafe_shell:: 请参阅 args 参数。默认值为 False。
Kw prompt_regex:: 正则表达式字符串（不是编译后的正则表达式），可用于检测 stdout 中的提示符，否则会导致执行挂起（特别是在未指定输入数据的情况下）。
Kw environ_update:: 用于更新环境变量的字典。
Kw umask:: 运行命令时使用的 Umask。默认值为 None。
Kw encoding:: 由于我们返回字符串，我们需要知道用于将字节转换为文本的编码。如果您始终想获取字节，请使用 encoding=None。默认值为“utf-8”。这不会影响作为 args 给出的字符串的转换。
Kw errors:: 由于我们返回字符串，我们需要将 stdout 和 stderr 从字节转换为文本。如果字节在指定的 encoding 中不可解码，则使用此错误处理器来处理它们。默认值为 surrogate_or_strict，这意味着如果可用（我们支持的所有 Python 版本均可用），字节将使用 surrogateescape 错误处理器进行解码，否则将引发 UnicodeError 回溯。这不会影响作为 args 给出的字符串的转换。
Kw expand_user_and_vars:: 当 use_unsafe_shell=False 时，此参数决定在运行命令之前是否扩展路径中的 ~ 以及环境变量。当为 True 时，无论转义与否，像 $SHELL 这样的字符串都将被扩展。当为 False 且 use_unsafe_shell=False 时，不会进行路径或变量扩展。
Kw pass_fds:: 此参数决定应该传递给底层 Popen 构造函数的文件描述符。
Kw before_communicate_callback:: 此函数将在创建 Popen 对象之后、但在与进程通信之前被调用。（Popen 对象将作为第一个参数传递给回调）。
Kw ignore_invalid_cwd:: 此标志指示是否应忽略无效的 cwd（不存在或不是目录），或者是否应引发异常。
Kw handle_exceptions:: 此标志指示异常是应内联处理并触发 failed_json，还是应由调用者处理。
返回值:: 包含返回代码 (int)、stdout (str) 和 stderr (str) 的三元组。stdout 和 stderr 是根据 encoding 和 errors 参数转换的文本字符串。如果您想要字节字符串，请使用 encoding=None 来关闭文本解码。

sha1(filename): 使用 digest_from_file() 返回本地文件的 SHA1 十六进制摘要。

sha256(filename): 使用 digest_from_file() 返回本地文件的 SHA-256 十六进制摘要。

基础 (Basic)

要使用此功能，请在模块中包含 import ansible.module_utils.basic。

ansible.module_utils.basic.get_platform()

返回值:: 以原生字符串表示的模块运行所在平台名称。

返回标注平台的原生字符串（“Linux”、“Solaris”等）。目前，这是调用 platform.system() 的结果。

ansible.module_utils.basic.heuristic_log_sanitize(data, no_log_values=None): 从日志消息中移除看起来像密码的字符串。

参数规范

用于根据参数规范验证参数的类和函数。

ArgumentSpecValidator

class ansible.module_utils.common.arg_spec.ArgumentSpecValidator(argument_spec, mutually_exclusive=None, required_together=None, required_one_of=None, required_if=None, required_by=None)

参数规范验证类。

根据 argument_spec 创建一个验证器，可用于使用 validate() 方法验证多个参数。

参数:

argument_spec (dict[str, dict]) – 有效参数及其类型的规范。可能包含嵌套的参数规范。
mutually_exclusive (list[str] or list[list[str]]) – 不应同时提供的项的列表或列表的列表。
required_together (list[list[str]]) – 必须一起提供的项的列表的列表。
required_one_of (list[list[str]]) – 项的列表的列表，每个列表中必须至少有一个被提供。
required_if (list) – [parameter, value, [parameters]] 列表的列表，如果 parameter == value，则 [parameters] 中的一个参数是必需的。
required_by (dict[str, list[str]]) – 参数名称的字典，包含字典中每个键所必需的参数列表。

validate(parameters, *args, **kwargs)

根据参数规范验证 parameters。

ValidationResult 中的错误消息可能包含 no_log 值，在记录或显示之前应使用 sanitize_keys() 进行清理。

参数:

parameters (dict[str, dict]) – 要根据参数规范验证的参数。

返回值:

包含已验证参数的 ValidationResult。

简单示例:

argument_spec = {
    'name': {'type': 'str'},
    'age': {'type': 'int'},
}

parameters = {
    'name': 'bo',
    'age': '42',
}

validator = ArgumentSpecValidator(argument_spec)
result = validator.validate(parameters)

if result.error_messages:
    sys.exit("Validation failed: {0}".format(", ".join(result.error_messages))

valid_params = result.validated_parameters

ValidationResult

class ansible.module_utils.common.arg_spec.ValidationResult(parameters)

参数规范验证的结果。

这是 ArgumentSpecValidator.validate() 返回的对象，包含已验证的参数和任何错误。

参数:: parameters (dict) – 要验证并强制转换为正确类型的项。

errors: 如果验证期间有任何失败，则包含所有 AnsibleValidationError 对象的 AnsibleValidationErrorMultiple。

property validated_parameters: 已验证并强制转换的参数。

property unsupported_parameters: 不受支持的参数名称的 set。

property error_messages: errors 中每个异常的所有错误消息的 list。

参数 (Parameters)

ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS: 类型名称（如 'str'）与用于检查该类型的默认函数的 dict，在这种情况下为 check_type_str()。

ansible.module_utils.common.parameters.env_fallback(*args, **kwargs): 从环境变量加载值。

ansible.module_utils.common.parameters.remove_values(value, no_log_strings)

从 value 中移除 no_log_strings 中的字符串。

如果 value 是容器类型，则移除更多内容。

使用 deferred_removals 而不是纯递归解决方案，是为了避免在处理大量数据时达到最大递归深度（参见 issue #24560）。

ansible.module_utils.common.parameters.sanitize_keys(obj, no_log_strings, ignore_keys=frozenset({}))

通过从键名中移除 no_log 值来清理容器对象中的键。

这是 remove_values() 函数的辅助函数。与该函数类似，我们利用 deferred_removals 来避免在处理大型数据结构时达到最大递归深度。

参数:

obj – 要清理的容器对象。非容器对象将原样返回。
no_log_strings – 我们不想记录的字符串值集。
ignore_keys – 不应清理的键字符串值集。

返回值:

具有清理后键的对象。

验证 (Validation)

用于验证各种参数类型的独立函数。

ansible.module_utils.common.validation.check_missing_parameters(parameters, required_parameters=None)

此函数用于检查必需参数，当我们无法通过 argspec 进行检查（因为我们需要的信息不仅 argspec 中给出）时使用。

如果缺少任何必需参数，则引发 TypeError。

参数:

parameters – 参数字典。
required_parameters – 要在给定参数中查找的参数列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_mutually_exclusive(terms, parameters, options_context=None)

针对参数检查互斥的项。

接受单个列表或列表的列表，这些是应该彼此互斥的项组。

参数:

terms – 互斥参数列表。
parameters – 参数字典。
options_context – 如果 terms 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_required_arguments(argument_spec, parameters, options_context=None)

检查 argument_spec 中的所有参数，并返回必需但未出现在 parameters 中的参数列表。

如果检查失败，引发 TypeError。

参数:

argument_spec – 包含所有参数及其规范的参数规范字典。
parameters – 参数字典。
options_context – 如果 argument_spec 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_required_by(requirements, parameters, options_context=None)

对于 requirements 中的每个键，检查对应的列表以查看它们是否存在于 parameters 中。

接受每个键的单个字符串或值列表。

参数:

requirements – 需求字典。
parameters – 参数字典。
options_context – 如果 requirements 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空字典，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_required_if(requirements, parameters, options_context=None)

检查条件必需的参数。

如果检查失败，引发 TypeError。

参数:: requirements – 列表的列表，指定参数、值、当给定参数为指定值时必需的参数，以及可选的布尔值，指示是否必需任意或所有参数。
示例:

required_if=[
    ['state', 'present', ('path',), True],
    ['someint', 99, ('bool_param', 'string_param')],
]

参数:

parameters – 参数字典。
options_context – 如果 requirements 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。异常的 results 属性包含字典列表。每个字典是评估 requirements 中每个项的结果。每个返回的字典包含以下键：

key missing:
必需但缺失的参数列表。

key requires:
’any’ 或 ‘all’。

key parameter:
具有该需求的参数名称。

key value:
参数的原始值。

key requirements:
原始必需参数。

示例:

[
    {
        'parameter': 'someint',
        'value': 99
        'requirements': ('bool_param', 'string_param'),
        'missing': ['string_param'],
        'requires': 'all',
    }
]

ansible.module_utils.common.validation.check_required_one_of(terms, parameters, options_context=None)

检查每个项列表，确保给定的模块参数中至少存在一个。

接受列表的列表或元组。

参数:

terms – 要检查的项的列表的列表。对于每个项列表，至少需要一个。
parameters – 参数字典。
options_context – 如果 terms 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_required_together(terms, parameters, options_context=None)

检查每个项列表，确保每个列表中的每个参数都存在于给定的参数中。

接受列表的列表或元组。

参数:

terms – 要检查的项的列表的列表。当在参数中至少指定一个参数时，每个列表应包含所有必需的参数。
parameters – 参数字典。
options_context – 如果 terms 位于子规范中，则为父键名称字符串的列表。

返回值:

返回空列表，或如果检查失败，则引发 TypeError。

ansible.module_utils.common.validation.check_type_bits(value)

将人类可读的字符串位值转换为整数位。

示例：check_type_bits('1Mb') 返回整数 1048576。

如果无法转换该值，则引发 TypeError。

ansible.module_utils.common.validation.check_type_bool(value)

验证值是否为布尔值，或者将其转换为布尔值并返回。

如果无法转换为布尔值，则引发 TypeError。

参数:: value – 要转换为布尔值的字符串、整数或浮点数。有效的布尔值包括：‘1’, ‘on’, 1, ‘0’, 0, ‘n’, ‘f’, ‘false’, ‘true’, ‘y’, ‘t’, ‘yes’, ‘no’, ‘off’。
返回值:: 布尔值 True 或 False。

ansible.module_utils.common.validation.check_type_bytes(value)

将人类可读的字符串值转换为字节。

如果无法转换该值，则引发 TypeError。

ansible.module_utils.common.validation.check_type_dict(value)

验证值是否为字典，或者将其转换为字典并返回。

如果无法转换为字典，则引发 TypeError。

参数:: value – 要转换为字典的字典或字符串。接受 k1=v1, k2=v2 或 k1=v1 k2=v2。
返回值:: 转换为字典后的值。

ansible.module_utils.common.validation.check_type_float(value)

验证值是否为浮点数，或者将其转换为浮点数并返回。

如果无法转换为浮点数，则引发 TypeError。

参数:: value – 要验证或转换并返回的浮点数、整数、字符串或字节。
返回值:: 给定值的浮点数。

ansible.module_utils.common.validation.check_type_int(value)

验证值是否为整数并返回，或者将该值转换为整数并返回。

如果无法转换为整数，则引发 TypeError。

参数:: value – 要转换或验证的字符串或整数。
返回值:: 给定值的整数。

ansible.module_utils.common.validation.check_type_jsonarg(value): JSON 序列化字典/列表/元组，去掉字符串和字节。之前在 Ansible/Jinja 经典模式字面量评估过程中可能会意外反序列化对象的情况下需要这样做。

ansible.module_utils.common.validation.check_type_list(value)

验证值是否为列表，或者将其转换为列表。

逗号分隔的字符串将被拆分为列表。如果无法转换为列表，则引发 TypeError。

参数:: value – 要验证或转换为列表的值。
返回值:: 如果已经是列表，则为原始值；如果是浮点数、整数或没有逗号的字符串，则为单项列表；如果是逗号分隔的字符串，则为多项列表。

ansible.module_utils.common.validation.check_type_path(value): 验证提供的值是否为字符串，或者将其转换为字符串，然后返回扩展后的路径。

ansible.module_utils.common.validation.check_type_raw(value): 返回原始值。

ansible.module_utils.common.validation.check_type_str(value, allow_conversion=True, param=None, prefix='')

验证值是否为字符串，或者将其转换为字符串。

由于转换为字符串时有时会发生意外更改，allow_conversion 控制是否转换该值，或者如果该值不是字符串且将会被转换，是否引发 TypeError。

参数:

value – 要验证或转换为字符串的值。
allow_conversion – 是否转换字符串并返回，或者引发 TypeError。

返回值:

如果已经是字符串则为原始值，如果 allow_conversion=True 则为转换为字符串后的值，如果 allow_conversion=False 则引发 TypeError。

ansible.module_utils.common.validation.count_terms(terms, parameters)

计算给定字典中某个键出现的次数。

参数:

terms – 要检查的字符串或值迭代对象。
parameters – 参数字典。

返回值:

一个整数，表示在提供的字典中 terms 值出现的次数。

错误 (Errors)

exception ansible.module_utils.errors.AnsibleFallbackNotFound: 未找到回退验证器。

exception ansible.module_utils.errors.AnsibleValidationError(message)

单个参数规范验证错误。

error_message: 引发异常时传递的错误消息。

property msg: 引发异常时传递的错误消息。

exception ansible.module_utils.errors.AnsibleValidationErrorMultiple(errors=None)

多个参数规范验证错误。

errors: AnsibleValidationError 对象的 list。

property msg: errors 中第一个错误的第一条消息。

property messages: errors 中每条错误消息的 list。

append(error)

将新错误追加到 self.errors。

应仅添加 AnsibleValidationError。

extend(errors): 将 errors 中的每一项追加到 self.errors。应仅添加 AnsibleValidationError。

exception ansible.module_utils.errors.AliasError(message): 别名处理错误。

exception ansible.module_utils.errors.ArgumentTypeError(message): 参数类型错误。

exception ansible.module_utils.errors.ArgumentValueError(message): 参数值错误。

exception ansible.module_utils.errors.DeprecationError(message): 参数弃用处理错误。

exception ansible.module_utils.errors.ElementError(message): 验证元素时出错。

exception ansible.module_utils.errors.MutuallyExclusiveError(message): 提供了互斥的参数。

exception ansible.module_utils.errors.NoLogError(message): 转换 no_log 值时出错。

exception ansible.module_utils.errors.RequiredByError(message): 其他参数必需的参数出错。

exception ansible.module_utils.errors.RequiredDefaultError(message): 必需参数被分配了默认值。

exception ansible.module_utils.errors.RequiredError(message): 缺少必需参数。

exception ansible.module_utils.errors.RequiredIfError(message): 条件必需参数出错。

exception ansible.module_utils.errors.RequiredOneOfError(message): 至少需要一个参数的错误。

exception ansible.module_utils.errors.RequiredTogetherError(message): 必须一起使用的参数出错。

exception ansible.module_utils.errors.SubParameterTypeError(message): 子参数类型不正确。

exception ansible.module_utils.errors.UnsupportedError(message): 提供了不支持的参数。