01.03.2023

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

server one
HOSTKEY
Арендуйте выделенные и виртуальные GPU серверы с профессиональными графическими картами NVIDIA RTX A5000 / A4000 в надежных дата-центрах класса TIER III в Москве и Нидерландах. Принимаем оплату за услуги HOSTKEY в Нидерландах в рублях на счет российской компании. Оплата с помощью банковских карт, в том числе и картой МИР, банковского перевода и электронных денег.

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

Арендуйте выделенные и виртуальные GPU серверы с профессиональными графическими картами NVIDIA RTX A5000 / A4000 в надежных дата-центрах класса TIER III в Москве и Нидерландах. Принимаем оплату за услуги HOSTKEY в Нидерландах в рублях на счет российской компании. Оплата с помощью банковских карт, в том числе и картой МИР, банковского перевода и электронных денег.

Другие статьи

21.09.2023

Мониторинг SSL-сертификатов oVirt

Рассказываем о способах мониторинга срока действия SSL-сертификатов в oVirt.

09.09.2023

Fabula - нейросеть, которая нарисует ваш уникальный аватар по фото

Как стартап из Казахстана смог построить успешный бизнес, используя генеративные нейросети на GPU-серверах от HOSTKEY

04.09.2023

Персональный VPN сервер 3x-UI в Европе, США и России

Hostkey подготовил новый сервис для своих клиентов — аренду сервера с предустановленным VPN 3X-UI. Новый сервис доступен для заказа на сайте компании.

04.09.2023

Серверы Dell и Supermicro: авторизация через LDAP

Рассказываем, как обеспечить интеграцию разнородных серверных платформ с централизованной LDAP-аутентификацией.

26.07.2023

Мониторинг и алертинг серверов Supermicro (sensor metrics) через Prometheus

Рассказываем о процессе настройки сбора метрик серверов Supermicro с помощью утилиты IPMItool и Prometheus.

HOSTKEY Выделенные серверы в Европе, России и США Готовые решения и индивидуальные конфигурации серверов на базе процессоров AMD, Intel, карт GPU, Бесплатной защитой от DDoS-атак и безлимитный соединением на скорости 1 Гбит/с 30
4.3 48 48
Upload