Коллекции Ansible: ansible.posix, community и своя коллекция

[Maksim_DevOps]

Ты пишешь плейбук, который вчера прекрасно работал, а сегодня на свежей машине падает с ошибкой "couldn't resolve module/action 'firewalld'". Модуль есть в документации, синтаксис правильный, а Ansible его не видит. Знакомо? Это и есть первая встреча с коллекциями. Начиная с ansible-core почти весь контент вынесли из монолитного движка в отдельные пакеты - и теперь модуль надо не просто вызвать, а сначала иметь установленным. В этом уроке разберёмся, что такое ansible collection, как устроены пространства имён, как ставить нужное через ansible galaxy collection install и как собрать свою коллекцию, чтобы раздавать роли и модули по команде.

Что такое коллекция и зачем разделили ansible-core и контент

Раньше Ansible был одним большим пакетом: движок плюс тысячи модулей в одной поставке. Это стало неподъёмным - релизы редкие, модули разной свежести, всё тащится скопом. Решение - разделение. Теперь есть ansible-core (сам движок, парсер плейбуков, базовый набор ansible.builtin) и коллекции - пакеты с контентом, которые версионируются и обновляются отдельно.

Коллекция (collection) - это способ упаковки и распространения контента: модулей, ролей, плагинов (фильтры, lookup, callback), а заодно документации и тестов. У каждой коллекции есть имя из двух частей: пространство имён (namespace) и собственно имя. Например, ansible.posix - это namespace "ansible" и коллекция "posix". community.general - namespace "community", коллекция "general".

Проверить, что движок и так далее у тебя в системе, и какая версия ansible-core стоит:

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

ansible --version
# ansible [core 2.16.x]
ansible-galaxy collection list

Команда list покажет установленные коллекции и их пути. Для экзамена EX294 актуальна связка RHEL 9 с ansible-core (примерно 2.14 и новее) - там коллекции уже базовый механизм, и знать его обязательно.



FQCN и пространства имён: почему firewalld пишут как ansible.posix.firewalld

FQCN расшифровывается как Fully Qualified Collection Name - полностью квалифицированное имя. Это форма namespace.collection.module, например ansible.posix.firewalld. Почему так? Потому что короткое имя firewalld может встречаться в нескольких коллекциях, и движку нужно знать однозначно, какой именно модуль ты зовёшь.

Модули из ansible.builtin (copy, file, template, service, dnf, user) идут вместе с ansible-core, их ставить не нужно. А вот firewalld, selinux, mount, authorized_key, sysctl живут в ansible.posix - и эту коллекцию надо установить отдельно.

Сравни. Не сработает на чистой системе без коллекции:

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

- name: Открыть HTTP в firewalld
  ansible.posix.firewalld:
    service: http
    state: enabled
    permanent: true
    immediate: true

А это базовый модуль - работает из коробки:

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

- name: Скопировать конфиг
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app/app.conf
    owner: root
    group: root
    mode: "0644"

Совет от практики: всегда пиши FQCN явно, даже для builtin. Это спасает от коллизий имён и делает плейбук читаемым. На экзамене за короткие имена не наказывают, но привычка к FQCN не даст промахнуться, когда два модуля называются одинаково.

Установка: ansible galaxy collection install и requirements.yml

Самый прямой путь - поставить коллекцию из Galaxy:

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

ansible-galaxy collection install ansible.posix
ansible-galaxy collection install community.general

Можно зафиксировать версию, это важно для воспроизводимости:

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

ansible-galaxy collection install ansible.posix:1.5.4

По умолчанию коллекции кладутся в ~/.ansible/collections. Путь поиска задаётся параметром collections_path в ansible.cfg - и это правильный приём для проекта: держать зависимости рядом с плейбуками, а не в домашнем каталоге.

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

[defaults]
collections_path = ./collections

Тогда установка с явным путём:

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

ansible-galaxy collection install ansible.posix -p ./collections

Но руками по одной коллекции ставят только для разовых задач. Нормальный способ - файл requirements.yml. В нём перечисляешь и коллекции, и роли. Обрати внимание: для коллекций используется ключ collections, и формат отличается от старого ролевого:

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

---
collections:
  - name: ansible.posix
    version: ">=1.5.0"
  - name: community.general
  - name: community.crypto

roles:
  - name: geerlingguy.nginx

Установка всего разом:

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

ansible-galaxy collection install -r requirements.yml
# роли из того же файла:
ansible-galaxy role install -r requirements.yml

Ключевые коллекции, которые нужны на RHCE и просто в работе: ansible.posix (firewalld, selinux, mount, authorized_key, sysctl, синхронизация через synchronize) и community.general - огромный набор на все случаи: parted, timezone, ldap, sudoers, modprobe и сотни других. Для Ubuntu/Debian принципиально ничего не меняется - тот же ansible-galaxy collection install, просто внутри плейбука вместо ansible.builtin.dnf берёшь ansible.builtin.apt. На RED OS и Astra механизм коллекций тоже стандартный, ansible-core ставится из репозитория дистрибутива.

Создать свою коллекцию: init, galaxy.yml, build и install

Когда у тебя накопились свои роли и пара плагинов, их удобно упаковать в одну коллекцию и раздавать командой. Чтобы создать коллекцию ansible, есть скелет-генератор:

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

ansible-galaxy collection init mycompany.infra

Получится структура:

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

mycompany/
  infra/
    galaxy.yml
    README.md
    docs/
    plugins/
    roles/
    meta/

Сердце коллекции - файл galaxy.yml с метаданными. Минимально валидный вид:

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

namespace: mycompany
name: infra
version: 1.0.0
readme: README.md
authors:
  - Ivan Admin <ivan@example.com>
description: Внутренние роли и модули инфраструктуры
license:
  - GPL-2.0-or-later
tags:
  - linux
  - rhel
dependencies:
  ansible.posix: ">=1.5.0"
repository: https://git.example.com/mycompany/infra

Свои роли кладёшь в roles/, кастомные модули - в plugins/modules/, фильтры - в plugins/filter/. Когда всё на месте, собираешь артефакт-тарбол прямо из корня коллекции:

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

ansible-galaxy collection build
# создаст mycompany-infra-1.0.0.tar.gz

И ставишь его как обычную коллекцию - локально или на другой машине:

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

ansible-galaxy collection install mycompany-infra-1.0.0.tar.gz -p ./collections

После установки твои роли доступны по FQCN: mycompany.infra.имя_роли, а модули - mycompany.infra.имя_модуля. Это и есть та самая упаковка с версионированием: поднял version в galaxy.yml, пересобрал, раскатал.

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

• Ошибка "couldn't resolve module/action 'firewalld'" - коллекция ansible.posix не установлена либо лежит вне collections_path. Лечится install и проверкой ansible-galaxy collection list.
• Путаница в requirements.yml: коллекции идут под ключом collections, роли под roles. Если свалить роль в секцию collections, получишь невнятную ошибку.
• ansible-galaxy collection install -r ставит только коллекции. Роли из того же файла надо отдельно: ansible-galaxy role install -r requirements.yml. Это частая засада на экзамене.
• Коллекция установлена для одного пользователя (~/.ansible), а плейбук запускается из-под другого или из CI - и она "пропадает". Используй collections_path в проекте.
• При сборке своей коллекции забывают поднять version в galaxy.yml - install не перезатрёт уже установленную ту же версию, и кажется, что правки не приехали. Используй опцию --force при отладке.
• Неверный license: должен быть валидный SPDX-идентификатор (GPL-2.0-or-later, MIT), произвольную строку build не пропустит.

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

• Проверь версию: ansible --version и ansible-galaxy collection list. Найди, есть ли уже ansible.posix.
• Создай requirements.yml с ansible.posix и community.general, поставь обе в локальный ./collections через -p.
• Пропиши collections_path = ./collections в ansible.cfg и напиши плейбук с ansible.posix.firewalld (открой http). Запусти, добейся идемпотентности (второй прогон - changed=0).
• Сделай ansible-galaxy collection init mycompany.infra, положи в roles/ простую роль, заполни galaxy.yml, собери build и установи тарбол. Вызови роль по FQCN mycompany.infra.имя.

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

• Что такое FQCN и почему firewalld надо писать как ansible.posix.firewalld, а copy можно как ansible.builtin.copy без установки?
• Чем отличается секция collections от roles в requirements.yml и какими двумя командами они ставятся?
• Какой параметр в ansible.cfg задаёт, где Ansible ищет коллекции, и зачем держать их в каталоге проекта?
• Какие шаги нужны, чтобы создать коллекцию ansible с нуля и установить её на другую машину (перечисли команды)?

Итог

Коллекции - это модульная упаковка контента Ansible с версиями и пространствами имён. ansible-builtin едет с движком, а всё остальное (ansible.posix, community.general) ставится через ansible-galaxy collection install, лучше через requirements.yml с фиксацией версий и collections_path внутри проекта. Для RHCE/EX294 обязательны ansible.posix (firewalld, selinux, mount, authorized_key) и уверенная установка коллекций - на этом срезаются чаще всего. А когда своих ролей становится много, init, build и install превращают их в переносимую коллекцию.

[fpga_veteran]

Спасибо, наконец дошло почему firewalld не находился - забыл поставить ansible.posix. Поставил через requirements.yml, заработало.

[mikefox]

Подскажите, а как обновить уже установленную коллекцию до свежей версии? install с --force прокатит или есть отдельная команда?