Ansible Reference: Модульные утилиты

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

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)

Общий код для быстрого создания модуля 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(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.

Возвращает

если найдено, возвращает полный путь; в противном случае возвращает None.

is_executable(path)

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

Параметры

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

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

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

is_special_selinux_path(path)

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

load_file_common_arguments(params, path=None)

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

Позволяет перезаписать аргумент модуля path/dest, предоставив path.

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, ignore_invalid_cwd=True)

Выполнение команды, возвращает 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

При выполнении на Python 3 этот аргумент определяет, какие дескрипторы файлов должны передаваться конструктору основного Popen. В Python 2 это установит close_fds в False.

Kw before_communicate_callback

Эта функция вызывается после создания объекта Popen, но перед общением с процессом. (Объект Popen передается в функцию обратного вызова в качестве первого аргумента).

Kw ignore_invalid_cwd

Этот флаг указывает, игнорировать ли недопустимый cwd (несуществующий или не каталог) или вызвать исключение.

Возвращает

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 в свой модуль.

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