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) → NoReturn

从模块返回，无错误。

fail_json(msg, **kwargs) → NoReturn

从模块返回，并显示错误消息。

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。

引发：

Sysexit：如果找不到 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)

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

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

md5(filename)

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

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

  1. 可选向后兼容性

  2. 与第三方协议的兼容性

此函数不适用于符合 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)

执行命令，返回返回值、标准输出和标准错误。

此方法读取标准输出和标准错误的机制与CPython subprocess.Popen.communicate不同，此方法会在生成的命令退出且标准输出和标准错误已被使用后停止读取，而不是等到标准输出/标准错误关闭。当考虑到派生的或后台进程可能比生成的命令保持标准输出或标准错误打开更长时间时，这可能是一个重要的区别。

参数：

args – 要运行的命令 * 如果args是列表，则命令将使用shell=False运行。 * 如果args是字符串且use_unsafe_shell=False，它会将args分割成列表并使用shell=False运行 * 如果args是字符串且use_unsafe_shell=True，则它将使用shell=True运行。

关键字 check_rc：

如果返回值非零，是否调用fail_json。默认为False

关键字 close_fds：

参见subprocess.Popen()的文档。默认为True

关键字 executable：

参见subprocess.Popen()的文档。默认为None

关键字 data：

如果给出，则写入命令的标准输入的信息

关键字 binary_data：

如果为False，则在数据末尾追加换行符。默认为False

关键字 path_prefix：

如果给出，则查找命令的附加路径。这会添加到PATH环境变量中，以便也可以找到同一目录中的辅助命令

关键字 cwd：

如果给出，则在其中运行命令的工作目录

关键字 use_unsafe_shell：

参见args参数。默认为False

关键字 prompt_regex：

正则表达式字符串（不是已编译的正则表达式），可用于检测标准输出中的提示符，否则这些提示符会导致执行挂起（尤其是在未指定输入数据的情况下）

关键字 environ_update：

用于更新环境变量的字典

关键字 umask：

运行命令时要使用的umask。默认为None

关键字 encoding：

由于我们返回原生字符串，所以在python3中，我们需要知道要使用的编码才能将字节转换为文本。如果你想始终获取字节数据，请使用encoding=None。默认为“utf-8”。这不会影响作为args给出的字符串的转换。

关键字 errors：

由于我们返回原生字符串，所以在python3中，我们需要将标准输出和标准错误从字节转换为文本。如果字节在指定的encoding中无法解码，则使用此错误处理程序来处理它们。默认为surrogate_or_strict，这意味着如果可用，字节将使用surrogateescape错误处理程序解码（在我们支持的所有python3版本上都可用），否则将引发UnicodeError回溯。这不会影响作为args给出的字符串的转换。

关键字 expand_user_and_vars：

当use_unsafe_shell=False时，此参数决定是否在运行命令之前展开路径中的~以及展开环境变量。当True时，例如$SHELL这样的字符串将被展开，而不管转义如何。当False且use_unsafe_shell=False时，不会进行路径或变量展开。

关键字 pass_fds：

在Python 3上运行时，此参数决定应将哪些文件描述符传递给底层的Popen构造函数。在Python 2上，这会将close_fds设置为False。

关键字 before_communicate_callback：

创建Popen对象后但在与进程通信之前，将调用此函数。（Popen对象将作为第一个参数传递给回调函数）

关键字 ignore_invalid_cwd：

此标志指示是否应忽略无效的cwd（不存在或不是目录）或引发异常。

关键字 handle_exceptions：

此标志指示是否应内联处理异常并发出failed_json，或者调用者是否应处理它。

返回：

一个包含返回值（整数）、标准输出（原生字符串）和标准错误（原生字符串）的3元组。在python2中，标准输出和标准错误都是字节字符串。在python3中，标准输出和标准错误是根据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

包含所有AnsibleValidationError对象的AnsibleValidationErrorMultiple，如果验证过程中有任何失败。

property validated_parameters

已验证和强制转换的参数。

property unsupported_parameters

不支持的参数名称的set。

property error_messages

list，包含errors中每个异常的所有错误消息。

参数

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)

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

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

使用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 – 不需要清理的键的一组字符串值。

返回：

一个带有已清理键的对象。

验证

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

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中的所有参数，并返回参数中必需但不存在的参数列表。

如果检查失败，则引发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中每个项目的结果。每个返回的字典包含以下键

键缺失：

所需但缺少的参数列表

键需要：

“any”或“all”

键参数：

具有要求的参数名称

键值：

参数的原始值

键需求：

原始所需参数

示例：

[
    {
        '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=v2, k2=v2 或 k1=v2 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 化的字符串。有时控制器会将 JSON 字符串转换为字典/列表，因此在此处将其转换回 JSON。

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

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 值的出现次数。

错误

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 对象

property msg

errors 中第一个错误的第一个消息。

property messages

list of 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)

提供了不支持的参数