Ansible Справочник: Модульные Утилиты

На этой странице документированы утилиты, предназначенные для помощи при написании модулей Ansible на Python.

AnsibleModule

Для использования этой функциональности, включите from ansible.module_utils.basic import AnsibleModule в ваш модуль.

class ansible.module_utils.basic.AnsibleModule(argument_spec, bypass_checks=False, no_log=False, check_invalid_arguments=None, 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)

Общий код для быстрого создания модуля ansible на Python (хотя вы можете написать модули с использованием всего, что может вернуть JSON).

См. Разработка модулей Ansible: начало работы для общего введения и Архитектура модулей Ansible для более подробного объяснения.

add_path_info(kwargs)

для результатов, которые являются файлами, дополняет информацию о пути к файлу статистикой о пути к файлу.

atomic_move(src, dest, unsafe_writes=False)

Атомарное перемещение src в dest, копируя атрибуты из dest, возвращает true при успехе. Использует os.rename для обеспечения атомарности операции, остальная часть функции предназначена для работы с ограничениями, особыми случаями и гарантирует сохранение контекста selinux, если это возможно.

backup_local(fn)

создаёт резервную копию указанного файла с меткой даты, возвращает True или False в случае успеха или неудачи.

boolean(arg)

Преобразует аргумент в булево значение.

digest_from_file(filename, algorithm)

Возвращает шестнадцатеричное значение дайджеста локального файла для метода дайджеста, указанного по имени, или None, если файл отсутствует.

exit_json(**kwargs)

возвращение из модуля без ошибок.

fail_json(**kwargs)

возвращение из модуля с сообщением об ошибке.

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

Находит системную исполняемую программу в PATH.

Параметры:	arg – Исполняемая программа для поиска. required – если исполняемая программа не найдена и required – True, fail_json opt_dirs – необязательный список каталогов для поиска помимо PATH
Возвращает:	если найдено, возвращает полный путь; в противном случае возвращает None

is_executable(path)

является ли данный путь исполняемым?

Параметры:	path – Путь к файлу для проверки.

Ограничения:

• Не учитывает FSACLs.
• В большинстве случаев мы хотим узнать «Может ли текущий пользователь выполнить этот файл». Эта функция не сообщает нам об этом, а только о том, установлены ли какие-либо биты разрешения на выполнение.

is_special_selinux_path(path)

Возвращает кортеж, содержащий (True, selinux_context), если данный путь находится на монтировании NFS или другом «специальном» точке монтирования, в противном случае возвращается (False, None).

load_file_common_arguments(params)

многие модули работают с файлами, эта оболочка содержит общие параметры, которые принимает модуль файлов, таким образом, он непосредственно доступен для всех модулей, и они могут совместно использовать код.

md5(filename)

Возвращает шестнадцатеричное значение дайджеста MD5 локального файла с помощью digest_from_file().

Не используйте эту функцию, если у вас нет другого выбора для:

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)

Выполняет команду, возвращает rc, stdout и stderr.

Параметры:	args – команда для выполнения * Если args – список, команда будет выполнена с shell=False. * Если args – строка и use_unsafe_shell=False, args будет разделен на список и выполнен с shell=False * Если args – строка и use_unsafe_shell=True, выполняется с shell=True.
Kw check_rc:	Нужно ли вызывать fail_json в случае ненулевого кода возврата. По умолчанию False
Kw close_fds:	См. документацию для subprocess.Popen(). По умолчанию True
Kw executable:	См. документацию для subprocess.Popen(). По умолчанию None
Kw data:	Если задано, информация для записи в стандартный ввод команды
Kw binary_data:	Если False, добавляет символ новой строки к данным. По умолчанию False
Kw path_prefix:	Если задано, дополнительный путь для поиска команды. Это добавляется к переменной окружения PATH, так что вспомогательные команды в том же каталоге также могут быть найдены
Kw cwd:	Если задано, рабочая директория для выполнения команды внутри неё
Kw use_unsafe_shell:
	См. параметр args. По умолчанию False
Kw prompt_regex:
	Строка регулярного выражения (не скомпилированное регулярное выражение), которая может использоваться для обнаружения подсказок в stdout, которые в противном случае приведут к зависанию выполнения (особенно если данные ввода не указаны)
Kw environ_update:
	словарь для обновления os.environ
Kw umask:	Umask, который будет использоваться при выполнении команды. По умолчанию None
Kw encoding:	Поскольку мы возвращаем собственные строки, в Python 3 нам нужно знать кодировку, чтобы преобразовать байты в текст. Если вы хотите всегда получать байты, используйте encoding=None. По умолчанию «utf-8». Это не влияет на преобразование строк, переданных как args.
Kw errors:	Поскольку мы возвращаем собственные строки, в Python 3 нам нужно преобразовать stdout и stderr из байтов в текст. Если байты не могут быть декодированы в указанной кодировке encoding, используйте этот обработчик ошибок, чтобы обработать их. По умолчанию surrogate_or_strict, что означает, что байты будут декодированы с помощью обработчика ошибок surrogateescape, если он доступен (доступен во всех поддерживаемых версиях Python 3), в противном случае будет поднята ошибка 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 будет передан в обратный вызов в качестве первого аргумента)
Возвращает:	Кортеж из 3 элементов: код возврата (целое число), stdout (собственная строка) и stderr (собственная строка). В Python 2 stdout и stderr – байтовые строки. В Python 3 stdout и stderr – текстовые строки, преобразованные в соответствии с параметрами encoding и errors. Если вы хотите байтовые строки в Python 3, используйте encoding=None, чтобы отключить декодирование в текст.

sha1(filename)

Возвращает шестнадцатеричное значение дайджеста SHA1 локального файла с помощью digest_from_file().

sha256(filename)

Возвращает шестнадцатеричное значение дайджеста SHA-256 локального файла с помощью digest_from_file().

Basic

Для использования этой функциональности, включите import ansible.module_utils.basic в ваш модуль.

exception ansible.module_utils.basic.AnsibleFallbackNotFound

ansible.module_utils.basic.env_fallback(*args, **kwargs)

Загрузка значения из среды.

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 вместо этого

ansible.module_utils.basic.remove_values(value, no_log_strings)

Удаляет строки из no_log_strings из значения. Если значение является контейнерным типом, то удаляет намного больше.

Использование deferred_removals вместо чисто рекурсивного решения связано с потенциальной проблемой достижения максимальной глубины рекурсии при работе с большими объемами данных (см. вопрос #24560).

ansible.module_utils.basic.sanitize_keys(obj, no_log_strings, ignore_keys=frozenset())

Очищает ключи в контейнерном объекте, удаляя значения no_log из имён ключей.

Это вспомогательная функция для функции remove_values(). Подобно этой функции, мы используем deferred_removals, чтобы избежать достижения максимальной глубины рекурсии в случаях с большими структурами данных.

Параметры:	obj – Контейнерный объект для очистки. Объекты, не являющиеся контейнерами, возвращаются без изменений. no_log_strings – Множество строковых значений, которые не должны записываться в журнал. ignore_keys – Множество строковых значений ключей, которые не нужно очищать.
Возвращает:	Объект с очищенными ключами.