Модули Ansible: ansible-doc и поиск нужного модуля

[Maksim_DevOps]

Представь ситуацию: тебе надо открыть порт в firewalld, смонтировать диск, выдать sudo-права или раскатать конфиг через шаблон. Ты примерно помнишь, что "модуль для этого есть", но как он называется и какие у него параметры - вылетело из головы. Гуглить? А если ты на экзамене RHCE (EX294), где интернета нет вообще? Вот тут и выясняется, что главный навык - не зубрить сотни модулей, а уметь быстро найти нужный прямо в системе. Инструмент для этого один и тот же и в проде, и на экзамене: ansible-doc. В этом уроке разберём, что такое модули Ansible, как устроены пространства имён и как выжать из ansible-doc максимум за минуты.

Что такое модуль и почему модулей Ansible так много

Модуль - это маленькая программа, которую Ansible копирует на управляемый узел, запускает и забирает результат. Ты в плейбуке описываешь желаемое состояние ("пакет nginx установлен", "сервис запущен", "строка есть в файле"), а модуль сам разбирается, как этого добиться на конкретной системе. Именно модули делают Ansible декларативным: ты говоришь ЧТО, а не КАК.

Хорошая новость - модулей реально много. В современном Ansible их счёт идёт на тысячи: только в базовой коллекции ansible.builtin несколько сотен (порядка 780 плагинов разных типов), а с подключёнными коллекциями вроде ansible.posix и community.general общее число легко переваливает за несколько тысяч. Плохая новость та же самая: запомнить все модули ansible невозможно и не нужно. Нужно уметь находить.

Раньше модули назывались коротко: copy, file, service. Сейчас правильное полное имя - это FQCN (Fully Qualified Collection Name), то есть полное имя с пространством имён: коллекция.модуль. Три коллекции, которые ты будешь встречать чаще всего:

• ansible.builtin - встроенные модули, идут из коробки: copy, file, template, service, dnf, user, lineinfile и так далее. Это твой хлеб.
• ansible.posix - posix-вещи: firewalld, mount, authorized_key, sysctl, selinux.
• community.general - огромная свалка полезного: parted, timezone, ufw, modprobe и сотни других.

Писать ansible.builtin.copy вместо просто copy - не каприз. На экзамене и в чужих ролях это снимает неоднозначность (мало ли, два модуля copy из разных коллекций) и считается хорошим тоном. Привыкай к полному имени сразу.



ansible-doc: три режима, которые надо довести до автоматизма

Команда ansible-doc читает встроенную документацию прямо из установленных модулей. Никакого интернета. Запомни три режима.

1. Список - ansible-doc -l. Показывает все доступные модули с однострочным описанием. Полезно отфильтровать по пространству имён или грепнуть по ключевому слову:

Код: Выделить всё

# вообще все модули (длинно, для общего счёта)
ansible-doc -l

# только встроенные ansible builtin
ansible-doc -l ansible.builtin

# ищем что-то про firewall
ansible-doc -l | grep -i firewall
# ansible.posix.firewalld   Manage arbitrary ports/services with firewalld
# community.general.ufw     Manage firewall with UFW

2. Полная документация - ansible-doc имя_модуля. Открывает страницу модуля: все параметры, что обязательно, значения по умолчанию, а в самом низу - примеры и возвращаемые значения.

Код: Выделить всё

ansible-doc ansible.builtin.copy
ansible-doc ansible.posix.firewalld

3. Снимок-шаблон - ansible-doc -s. Самый недооценённый режим. Выдаёт готовую заготовку задачи со всеми параметрами в виде закомментированного YAML. Копируешь в плейбук, оставляешь нужное, дописываешь значения:

Код: Выделить всё

ansible-doc -s ansible.builtin.copy

Вывод будет примерно такой - буквально каркас задачи:

Код: Выделить всё

- name: Copy files to remote locations
  ansible.builtin.copy:
      src:                   # Local path to a file to copy...
      dest:                  # Remote absolute path where the file...
      owner:                 # Name of the user that should own...
      mode:                  # The permissions of the destination...
      backup:                # Create a backup file...

На экзамене это экономит дикое количество времени: не пишешь задачу с нуля и по памяти, а получаешь скелет с правильными именами параметров. Ошибиться в имени параметра становится почти невозможно.

Ещё пара мелочей, которые выручают: ansible-doc -F покажет, в каком файле физически лежит модуль (удобно, когда сомневаешься, какая коллекция отвечает), а флаг -t переключает тип плагина - например, ansible-doc -t become -l покажет плагины повышения привилегий, а -t lookup -l - lookup-плагины. По умолчанию тип - module.

Как читать страницу модуля: parameters, examples, return values

Когда открыл ansible-doc на конкретном модуле, не надо читать всё подряд. Структура у всех страниц одинаковая, и сканировать её надо в таком порядке.

• Краткое описание сверху - убеждаешься, что это вообще тот модуль.
• OPTIONS / PARAMETERS - главная часть. Для каждого параметра указано: тип, обязательный он или нет (look for "required"), значение по умолчанию (default) и допустимые варианты (choices). Если у state есть choices present/absent/enabled - значит модуль идемпотентный по состоянию.
• EXAMPLES (в самом низу) - готовые рабочие куски YAML. На экзамене это золото: часто проще скопировать пример и подставить свои значения, чем сочинять.
• RETURN VALUES - что модуль кладёт в результат. Нужно, когда ты регистрируешь вывод через register и потом обращаешься к полям.

Соберём боевой пример. Допустим, нужно открыть HTTP в firewalld - идемпотентно и навсегда. Подсмотрели имя через grep, открыли ansible-doc ansible.posix.firewalld, увидели параметры service, state, permanent, immediate - и пишем:

Код: Выделить всё

- name: Открыть http в firewalld навсегда
  ansible.posix.firewalld:
    service: http
    state: enabled
    permanent: true
    immediate: true

Здесь permanent: true пишет правило в постоянную конфигурацию, а immediate: true применяет его сразу, без перезапуска сервиса. Запустишь playbook повторно - изменений не будет, потому что состояние уже достигнуто. Это и есть идемпотентность.

Идемпотентность и check_mode - почему это про модули

Идемпотентность - свойство, при котором повторный запуск задачи не меняет систему, если она уже в нужном состоянии. Это обеспечивает не магия плейбука, а сам модуль: он сначала проверяет текущее состояние, потом решает, надо ли что-то делать. Поэтому copy при втором прогоне покажет ok, а не changed.

С этим тесно связан check_mode - "сухой прогон". Запускаешь с флагом --check, и модули, которые его поддерживают, говорят, что бы они сделали, не трогая систему:

Код: Выделить всё

ansible-playbook site.yml --check --diff

Поддержку check_mode видно в документации модуля (раздел ATTRIBUTES, check_mode: support full/partial/none). Большинство встроенных модулей ansible builtin его поддерживают полностью. Командные модули вроде ansible.builtin.command и shell - нет, потому что Ansible не знает, что натворит твоя команда. Это типичная ловушка: --check на плейбуке с command может соврать или упасть.

Короткая ремарка про дистрибутивы. Все примеры тут - RHEL/Fedora-семейство: пакеты через ansible.builtin.dnf, сервисы через systemd, файрвол через firewalld, и SELinux на месте (его не выключай, а правь модулями ansible.posix.selinux и community.general.sefcontext). На Debian/Ubuntu пакеты ставятся через ansible.builtin.apt, а файрвол чаще community.general.ufw. В RED OS и Astra Linux логика ближе к RHEL и Debian соответственно - сами FQCN модулей те же, отличается только нижележащий пакетный менеджер.

Типичные грабли

• Имя по памяти. Пишешь ansible.builtin.firewalld - и получаешь ошибку, потому что firewalld живёт в ansible.posix. Не помнишь коллекцию - сначала ansible-doc -l | grep.
• Коллекция не установлена. ansible-doc на модуль из community.general падает с "module not found" - значит, коллекция не стоит. Ставится через ansible-galaxy collection install community.general. На экзамене обычно всё нужное уже предустановлено - проверь ansible-doc -l заранее.
• Параметр выдуман. Кажется, что у модуля есть удобный параметр, а его нет. Лечится только чтением OPTIONS, а не интуицией.
• --check на command/shell. Думаешь, что проверил плейбук вхолостую, а командные модули check_mode игнорируют. Не доверяй сухому прогону там, где есть command.

Мини-лаба: повтори руками

• Выполни ansible-doc -l ansible.builtin и прикинь масштаб - сотни модулей под рукой.
• Найди модуль для управления пользователями: ansible-doc -l | grep -i user. Открой ansible-doc ansible.builtin.user и найди в OPTIONS параметры name, state, groups, shell.
• Сделай шаблон задачи: ansible-doc -s ansible.builtin.lineinfile. Скопируй каркас и собери задачу, которая добавляет строку в /etc/hosts.
• Через ansible-doc найди и собери задачу открытия порта 8080/tcp в firewalld (подсказка: параметр port, формат PORT/PROTOCOL).
• Прогони свой мини-плейбук с --check --diff и посмотри, что Ansible собирается менять.

Контрольные вопросы

• Чем отличается ansible-doc -l от ansible-doc -s и когда какой нужен?
• Что такое FQCN и почему firewalld нельзя писать как ansible.builtin.firewalld?
• Где на странице модуля смотреть, обязателен ли параметр и какие у него допустимые значения?
• Почему --check может ввести в заблуждение на задачах с модулем command?

Итог

Модулей в Ansible тысячи, и зубрить их - тупик. Рабочий навык - находить нужный модуль и его параметры за пару команд: ansible-doc -l для поиска, ansible-doc module для деталей, ansible-doc -s для готового шаблона задачи. Привыкни к полным именам FQCN, читай блок OPTIONS и примеры, помни про идемпотентность и check_mode. На экзамене EX294, где интернета нет, ansible-doc - твой единственный и лучший справочник. Освоишь его - и половина паники на экзамене исчезает.

[postgreswhale]

Блин, я реально на прошлой попытке EX294 пол-времени потратил вспоминая параметры. ansible-doc -s это прям спасение, не знал что он шаблон сразу выдаёт. Спасибо!

[alexsis]

Подскажите, а -F чем от -l отличается на практике? Понял что путь к файлу показывает, но когда это реально нужно кроме как 'из какой коллекции модуль'?