Ansible — стандартизация оформления playbook

Автор: DevOps Team Leader Егор Гараджа

Ansible является, пожалуй, самой Unix-way-системой управления конфигурацией, он прост и нетребователен к оформлению и не обладает собственной развитой инфраструктурой. Во многом за счет этих особенностей Ansible имеет крайне низкий порог входа, а также популярна в небольших компаниях и группах.

Эти же особенности часто приводят к разношерстному оформлению playbook. Мы в компании Hostkey прошли путь от одной директории со свалкой yml к определенному внутреннему порядку и стандарту оформления playbook. Обращаемся мы с этой заметкой в первую очередь к начинающим DevOps и администраторам небольших организаций.

Первой проблемой является структура. Нам довелось повидать очень много форматов оформления (точнее их отсутствия), что сильно затрудняет банальный поиск точки входа (что исполнять?), не говоря уже о проблеме понимания структуры playbook (что он, собственно, делает?).

Для начала надо от чего-то оттолкнуться с точки зрения структуры директорий стандартного проекта. Ansible не предъявляет жестких требований к playbook, зато оформление ролей жестко регламентировано — значит, будем исходить из этого.

Создание структуры для роли происходит с помощью ansible-galaxy init. В результате должен получиться набор файлов следующего вида:

.
├── defaults
│   └── main.yml
├── files
├── handlers
│   └── main.yml
├── meta
│   └── main.yml
├── README.md
├── tasks
│   └── main.yml
├── templates
├── tests
│   ├── inventory
│   └── test.yml
└── vars
    └── main.yml

В playbook нам опционально нужны только files, tasks, templates, vars. Для переменных будем использовать group_vars/host_vars, определенные в документации. На базе этой структуры определим первые пункты внутреннего соглашения:

• Каждый playbook представляет собой отдельный репозиторий. Это необходимо, чтобы структурировать процесс разработки и потенциально ограничить доступы.
• Корень репозитория обязательно содержит файлы:
• входной yml playbook носит название main и располагается в корне репозитория;
  • Handler мы также располагаем во входном main.yml, как показала практика — это наиболее читаемый вариант, позволяющий схватить структуру императивного процесса, просмотрев всего один файл.
• .gitignore для исключения директории с ролями.
  • Содержимое: roles/*.
• LICENSE — стандартная используемая в вашей организации лицензия. Строго говоря, это необязательный пункт, но в нашем случае это необходимо;
• README.md — каждый playbook должен содержать Readme с базовым описанием, зачем он нужен и примером вызова. Сюда обычно попадают все нюансы, в основном связанные с тегами.
• Корень репозитория может опционально содержать следующие директории:
  • files — для файлов, доставляемых на сервера без изменений;
  • templates — для шаблонов jinja2;
  • tasks — для групп дополнительных задач, если основной main.yml начинает превышать две страницы, что снижает его читаемость;
    • vars — для переменных, подгружаемых через include_vars;
  • В этой директории мы также помещаем обязательный main.yml, в котором должна быть как минимум одна наша константа hostkey_playbook_name с собственным именем playbook.
  • group_vars/host_vars — для стандартного механизма подгрузки переменных.
• Опциональные файлы:
  • ansible.cfg — стандартные настройки, чаще определяются на среде исполнения playbook, но мы держим такой файл с набором стандартных настроек в каждом playbook;
  • hosts(yml) — inventory также в нашем случае чаще определяется извне, но мы допускаем наличие такого файла и его имя;
  • requirements.yml — файл с указанием ролей-зависимостей.

Жесткая структура позволяет любому специалисту внутри компании, просто взглянув на playbook, быстро оценить его структуру и назначение, понять стоит ли его применить или доработать. Для создания нового playbook вы можете создать базовый шаблон, по образу и подобию того, что использует ansible-galaxy init, чтобы упростить заведение новых задач по автоматизации.

Кроме структуры стоит определиться с общими соглашениями по написанию. Например, в нашей организации действует соглашение: «Неидемпотентные методы всегда должны содержать условия исполнения». Это правило может иметь исключения только для прототипирования сложной автоматизации, для которой не существует готового набора модулей (соответственно, их необходимо создавать). В остальных случаях инженер обязательно проставляет тег или условие применения метода, таким образом мы сами бьем себя по рукам и стараемся избегать таких конструкций. Если они все же появляются, то это должно быть обусловлено в коде. Также можете взять за хорошую практику:

• Теги только при реальной необходимости, любое управление для playbook усложняет его тестирование.
• Если переменная должна назначаться при исполнении playbook — лучше не задавайте умолчание, поломка с читаемой ошибкой — часто лучший вариант, чем тихое исполнение с неочевидным результатом.
• Ну и конечно, все секреты в зашифрованном виде. Причем шифрование конфигурационного файла целиком — это всегда плохой путь, относительно шифрования содержимого переменных и использования их в шаблонах (первое существенно ухудшает читаемость playbook и коммитов).
• Playbook может содержать конкретные значения и нацелен на создание окончательной конфигурации. Роль отдает набор управляющих переменных. Если в вашей роли начали появляться секреты или что-то подобное — вы что-то делаете не так.
• Используйте роли для конфигурирования стандартных сервисов и не бойтесь писать их самостоятельно. Иногда внешние роли избыточны, сложны или просто некачественны (что уж греха таить). Роли — это не модули, вы можете позволить себе написание и поддержку внутренних ролей, не увеличивая, а снижая сложность эксплуатации.

Такой набор регламентов оформления, с нашей точки зрения, способен сильно упростить жизнь вам или вашим преемникам, если (точнее, когда) автоматизация начнет разрастаться. Если вы все еще держите playbook как набор разноименных yml в одной директории, и этих файлов уже довольно много, подумайте, возможно, пришло время навести в них порядок. Будем рады критике или дополнениям от опытных коллег и надеемся, что наш опыт улучшит практики коллег начинающих.