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

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

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

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

Параметры

• arg – Исполняемая программа для поиска.
• required – если исполняемая программа не найдена и required равно True, возвращает ошибку.
• 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.

Большинство случаев использования этой функции могут использовать функцию модуля.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, она будет разбита на список и выполнена с 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

Если задано, информация для записи в стандартный ввод команды

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 (несуществующий или не каталог) или следует ли вызывать исключение.

Возвращаемое значение

Кортеж из трёх элементов: код возврата (целое число), 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 из значения. Если значение является типом контейнера, то удалить гораздо больше.

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

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

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

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

Параметры

• obj – Объект-контейнер для очистки. Объекты, не являющиеся контейнерами, возвращаются без изменений.
• no_log_strings – Набор строковых значений, которые не должны регистрироваться.
• ignore_keys – Набор строковых значений ключей, которые не нужно очищать.

Возвращает

Объект с очищенными ключами.