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 – Путь к файлу для проверки.

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

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

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.

Большинство случаев использования этой функции могут использовать функцию модуля.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 в случае ненулевого RC. По умолчанию 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:
	словарь для обновления os.environ
Kw umask:	Umask, используемый при выполнении команды. По умолчанию None
Kw encoding:	Поскольку мы возвращаем нативные строки, в python3 нам нужно знать кодировку, используемую для преобразования из байтов в текст. Если вы хотите всегда получать байты, используйте encoding=None. По умолчанию «utf-8». Это не влияет на преобразование строк, переданных в качестве аргументов.
Kw errors:	Поскольку мы возвращаем нативные строки, в python3 нам нужно преобразовать stdout и stderr из байтов в текст. Если байты не могут быть декодированы в указанной encoding, тогда используйте этот обработчик ошибок для обработки. По умолчанию surrogate_or_strict, что означает, что байты будут декодированы с помощью обработчика ошибок surrogateescape, если он доступен (доступен во всех версиях python3, которые мы поддерживаем), в противном случае будет вызвано исключение UnicodeError. Это не влияет на преобразования строк, переданных в качестве аргументов.
Kw expand_user_and_vars:
	Когда use_unsafe_shell=False, этот аргумент определяет, расширяются ли ~ в путях и расширяются ли переменные окружения перед выполнением команды. Когда True, строка типа $SHELL будет расширена независимо от экранирования. Когда False и use_unsafe_shell=False расширение путей или переменных не будет выполнено.
Kw pass_fds:	При выполнении на python3 этот аргумент определяет, какие дескрипторы файлов должны быть переданы подлежащему конструктору Popen.
Kw before_communicate_callback:
	Эта функция будет вызываться после того, как объект Popen будет создан, но перед обменом с процессом. (Объект Popen будет передан в обратный вызов в качестве первого аргумента)
Возвращает:	Кортеж из 3 элементов: код возврата (целое число), stdout (нативная строка) и stderr (нативная строка). В python2 stdout и stderr — это строковые байты. В python3 stdout и stderr — это строковые значения, преобразованные в соответствии с параметрами encoding и errors. Если вы хотите байтовые строки в python3, используйте encoding=None, чтобы отключить преобразование в текст.

sha1(filename)

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

sha256(filename)

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

Базовые

Для использования этой функциональности, включите 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 – Множество строковых значений ключей, которые не нужно очищать.
Возвращает:	Объект с очищенными ключами.