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): 将参数转换为布尔值。

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

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

fail_json(msg, **kwargs): 从模块返回，并显示错误消息。

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，除非 ‘warning’ 则返回 None。

引发：:

Sysexit：如果 arg 未找到且 required=True（通过 fail_json）

is_executable(path)

给定路径是否可执行？

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

限制

不考虑 FSACL。
大多数时候，我们真正想知道的是“当前用户能否执行此文件”。此函数无法告知我们，只能告知是否有任何执行位被设置。

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

load_file_common_arguments(params, path=None)

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

允许通过提供 path 覆盖 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:: 用于更新 environ 变量的字典
Kw umask:: 运行命令时要使用的 umask。默认值 None
Kw encoding:: 由于我们返回的是原生字符串，因此在 python3 中我们需要知道要用来从字节转换为文本的编码。如果你希望始终返回字节，则使用 encoding=None。默认值为“utf-8”。这不会影响作为 args 给出的字符串的转换。
Kw errors:: 由于我们返回的是原生字符串，因此在 python3 中我们需要将 stdout 和 stderr 从字节转换为文本。如果字节在指定的encoding 中无法解码，那么使用此错误处理程序来处理它们。默认值为surrogate_or_strict，这意味着如果可用（在我们支持的所有 python3 版本中都可用），则字节将使用 surrogateescape 错误处理程序进行解码，否则将引发 UnicodeError 回溯。这不会影响作为 args 给出的字符串的转换。
Kw expand_user_and_vars:: 当use_unsafe_shell=False 时，此参数决定是否在运行命令之前扩展路径中的~ 并扩展环境变量。当True 时，诸如$SHELL 之类的字符串将被扩展，无论是否转义。当False 且use_unsafe_shell=False 时，不会进行任何路径或变量扩展。
Kw pass_fds:: 在 Python 3 上运行时，此参数决定哪些文件描述符应该传递给底层的Popen 构造函数。在 Python 2 上，这将把close_fds 设置为 False。
Kw before_communicate_callback:: 此函数将在创建Popen 对象后但与进程通信之前调用。（Popen 对象将作为第一个参数传递给回调）
Kw ignore_invalid_cwd:: 此标志表示是否应该忽略无效的cwd（不存在或不是目录），或者应该引发异常。
Kw handle_exceptions:: 此标志表示是否应该在内联处理异常并发出 failed_json，或者调用者应该处理它。
返回值：:: 返回代码（整数）、stdout（原生字符串）和 stderr（原生字符串）的 3 元组。在 python2 中，stdout 和 stderr 都是字节字符串。在 python3 中，stdout 和 stderr 是根据 encoding 和 errors 参数转换的文本字符串。如果你想要在 python3 中获取字节字符串，则使用 encoding=None 来关闭解码为文本。

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

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

基本

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

ansible.module_utils.basic.get_all_subclasses(cls): 已弃用：使用 ansible.module_utils.common._utils.get_all_subclasses 代替

ansible.module_utils.basic.get_platform()

已弃用 直接使用platform.system()。

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

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

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

ansible.module_utils.basic.load_platform_subclass(cls, *args, **kwargs): 已弃用：使用 ansible.module_utils.common.sys_info.get_platform_subclass 代替

参数规范

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

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: AnsibleValidationErrorMultiple 包含所有 AnsibleValidationError 对象（如果有），这些对象在验证期间出现故障。

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

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

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

参数

ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS: dict 类型名称，例如 'str'，以及用于检查该类型的默认函数，在本例中为 check_type_str()。

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

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

从值中删除 no_log_strings 中的字符串。

如果值是容器类型，则删除更多内容。

使用 deferred_removals 而不是纯递归解决方案，是因为处理大量数据时可能会遇到最大递归深度（请参阅问题 #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 – 一组不应清理的键的字符串值。

返回值：:

具有清理后的键的对象。

验证

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

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)

检查参数规范中的所有参数，并返回在参数中不存在的必需参数列表。

如果检查失败，则引发 TypeError。

参数：:

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

返回值：:

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

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

对于要求中的每个键，检查相应的列表以查看它们是否存在于参数中。

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

参数：:

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 属性包含一个字典列表。每个字典是评估要求中的每个项目的结果。每个返回值字典包含以下键

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)

验证 value 是字典，或将其转换为字典并返回它。

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

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

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

验证 value 是浮点数，或将其转换为浮点数并返回它。

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

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

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

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

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

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

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

返回一个 json 化的字符串。有时控制器会将 json 字符串转换为字典/列表，因此在此处将其转换回 json。

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

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

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

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

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

ansible.module_utils.common.validation.check_type_path(value): 验证提供的 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 – 参数字典

返回值：:

提供字典中 term 值出现的次数的整数。

错误

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: list of AnsibleValidationError objects

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

property messages: list of each error message in errors.

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): 提供了不支持的参数