✻ Урок 7.6 · Тема 7: IaC: Terraform и Ansible
Ansible: роли и деплой «Заметок» одним запуском
Содержание урока
Как работать с кодом и когда идти дальше
Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:
- Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
- Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
- Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.
Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.
Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.
Зачем это нужно
Плейбук (playbook, файл с описанием настройки сервера, урок 7.5) на 200 строк, в котором смешаны установка Docker, конфиги, пароли и запуск приложения, никто не хочет читать и никто не осмеливается менять. Это как одна инструкция на весь ресторан сразу: и закупка, и кухня, и зал. Найти нужный кусок трудно, а повторить только его невозможно.
Вот как выглядит такой «монолит» и его главная опасность: в файле на 214 строк где-то посередине лежит строка
notes_db_password: "qwerty-notes-2026"
Пароль базы записан открытым текстом, и вместе с файлом он попадёт в Git, а найти его в двухстах строках можно только случайно.
На работе такое разбирают на роли (roles). Роль это готовый «модуль знаний» об одном деле: «поставить Docker», «развернуть приложение». Каждая лежит в своей папке, у каждой понятная структура, и её можно взять на десятки серверов, не копируя текст. Без ролей каждый новый сервер означает копипасту плейбука, а через месяц копии расходятся.
Вторая проблема: пароль базы данных (БД) нужно где-то хранить. Держать его в открытом виде в git нельзя (урок 3.4), а без него приложение не запустится. Поэтому секреты шифруют инструментом Ansible Vault, его разберём в теории.
В этом уроке ты соберёшь две роли и запустишь «Заметки» на чистой виртуальной машине (ВМ) одной командой. Пароль БД будет лежать в зашифрованном файле.
Шаг проекта: в ~/notes/infra/ansible/ появятся роли docker и notes и зашифрованный group_vars/all/vault.yml; ansible-playbook site.yml поднимает «Заметки» на ВМ.
Что нужно знать
- Урок 7.4: инвентарь, модули, ad-hoc - inventory,
ansible.cfg, доступ по SSH - Урок 7.5: плейбуки, handlers и Jinja2 -
tasks,notify, шаблоны.j2, идемпотентность - Урок 7.2: переменные, ВМ и outputs - откуда берётся IP ВМ
- Урок 4.5: Compose с PostgreSQL -
compose.yml,.env, healthcheck - Урок 6.3: деплой на ВМ - что мы автоматизируем: pull образа и
up -d - Урок 1.3: права и пользователи - владелец и режим файла
.env(640)
Картина целиком
Представь небольшой ресторан. Есть должностные инструкции по станциям: «холодный цех», «горячий цех», «раздача». Каждая инструкция лежит в своей папке и описывает свою работу от начала до конца. Это роли. Есть меню на сегодня: какие станции работают и в каком порядке. Это плейбук site.yml. Есть индивидуальные настройки: сколько порций, какой соус, а ещё сейф с кодами от склада: пароли, которые нельзя оставлять на виду. Это переменные и vault.
flowchart TD
S["site.yml<br>меню: роли на серверах"] -->|"roles: notes"| N["roles/notes<br>роль приложения"]
N -->|"meta/main.yml: зависит от"| D["roles/docker<br>роль Docker на сервере"]
N --- T["tasks/main.yml: каталоги, .env, compose, /readyz"]
N --- DF["defaults/: значения по умолчанию, самые слабые"]
N --- TP["templates/: notes.env.j2, compose.yml.j2"]
G["group_vars/all/vars.yml<br>notes_db_password"] -->|"ссылка"| V["group_vars/all/vault.yml<br>зашифрован"]
V -->|"расшифровка в памяти<br>паролем из ~/.notes-secrets"| N
Части схемы:
- роль (role) - папка с заранее оговорённой структурой: задачи, шаблоны, значения по умолчанию лежат на своих местах;
- зависимость роли - запись в
meta/main.yml: «перед мной выполни роль docker»; - defaults и group_vars - слои значений: слабые (значения роли по умолчанию) и сильные (значения проекта);
- vault - шифрование файла с секретами, чтобы его можно было хранить в git;
- коллекция (collection) - пакет с дополнительными модулями; Compose управляется модулем из коллекции
community.docker.
Теория
Зачем плейбуку роли
В уроке 7.5 плейбук был один файл на несколько play. Пока серверов один и задач десять, это удобно. Когда задач шестьдесят, а серверов разных видов пять, возникают три проблемы. Нужную строку трудно найти. Кусок «поставь Docker» хочется взять в другой проект и приходится копировать. Проверить один кусок отдельно от остальных нельзя.
Помнишь ресторан из «Картины целиком»? Инструкция «горячий цех» лежит отдельно от «раздачи», и меню просто говорит, какие станции работают. Роль (role) это такая станция: каталог с заранее оговорённой структурой. Ansible сам ищет нужные файлы в нужных подкаталогах, поэтому ничего вручную подключать не нужно. Если в плейбуке написано roles: [notes], Ansible идёт в roles/notes/ и ищет там:
roles/notes/
tasks/main.yml # задачи: точка входа, выполняются сверху вниз
handlers/main.yml # обработчики: реакции на notify (урок 7.5)
templates/ # шаблоны .j2: бланки с пустыми местами для значений
files/ # статичные файлы: копируются как есть, без подстановок
defaults/main.yml # значения по умолчанию: самый низкий приоритет
vars/main.yml # «жёсткие» значения роли: высокий приоритет
meta/main.yml # метаданные и зависимости от других ролей
Все подкаталоги необязательны: если в роли нет шаблонов, папки templates/ просто не будет. Особое правило поиска: модуль template без указания пути берёт файл из templates/ этой роли, а copy из files/. Поэтому в задаче роли пишут src: notes.env.j2, а не длинный путь.
Пример: Плейбук сжимается до списка ролей:
- name: Настройка сервера «Заметки» # название play для вывода
hosts: notes # на каких серверах (группа из inventory, урок 7.4)
become: true # выполнять с правами root (урок 7.4)
roles:
- docker # сначала поставить Docker
- notes # потом развернуть приложение
Ansible выполняет роли по порядку сверху вниз. Внутри каждой роли: загрузит значения из defaults/ и vars/, затем выполнит tasks/main.yml, а handlers сработают в конце play, как в уроке 7.5. В нашем проекте та же настройка, что в 7.5 делали тремя отдельными плейбуками (base.yml, docker.yml, config.yml), теперь живёт в двух ролях: так понятно, где искать и что переиспользовать.
Прикинь сам: В плейбуке
roles: [notes, docker], а ролиnotesнужен Docker. Что произойдёт?
Роль notes выполнится первой, Docker и плагина Compose ещё нет, задача запуска стека упадёт. Исправить без перестановки можно зависимостью: записать в roles/notes/meta/main.yml строку dependencies: [{role: docker}], и Ansible сам подтянет docker перед notes при любом порядке в списке.
Осторожно:
- Роль и плейбук. Плейбук отвечает на вопрос «на каких серверах и что выполнить», роль отвечает на вопрос «как именно настроить одну вещь». Роль сама никуда не запускается, её подключают из плейбука.
- «Роль обязана быть большой». Хорошая роль делает одно дело: Docker отдельно, приложение отдельно.
Главное: роль это каталог с заранее оговорённой структурой: Ansible сам находит в нём задачи, шаблоны и значения; роль делает одно дело, а плейбук говорит, где и в каком порядке её запускать.
Внутри роли значения лежат в двух местах, и выбор между ними важен.
defaults и vars: два места для значений внутри роли
Роль должна работать «из коробки», но пользователь роли хочет менять часть настроек: тег образа, порт, каталог. Нужно место для разумных значений по умолчанию, которые легко перебить снаружи.
Значение из defaults/main.yml самое слабое из всех: его перекрывает group_vars, host_vars, -e и практически всё остальное. Значение из vars/main.yml роли сильное: снаружи его перебьёт только совсем сильный источник вроде -e. Правило выбора: всё, что пользователь роли может захотеть поменять (тег образа, каталог), кладёшь в defaults/. В vars/ только то, что менять нельзя (внутренний порт приложения).
Пример: В роли notes лежит defaults/main.yml:
notes_tag: "0.4.1" # тег образа; latest не используем
notes_image: "ghcr.io/CHANGE_ME/notes"
notes_dir: /opt/notes # где лежит compose.yml
notes_env_dir: /etc/notes # где лежит .env (конфиг)
Пользователь роли в group_vars/all/vars.yml пишет notes_tag: "0.4.2". Значение group_vars сильнее, поэтому задеплоится 0.4.2, а роль менять не пришлось. Если бы notes_tag стоял в vars/ роли, правка в group_vars не сработала бы, и пользователь бы недоумевал, почему «переменная не применяется».
В vars/main.yml той же роли лежит то, что менять нельзя: notes_internal_port: 8080 (порт, на котором приложение слушает внутри контейнера, он зашит в образ) и порт PostgreSQL 5432. Если кто-то перебьёт их снаружи, приложение перестанет отвечать.
Прикинь сам: Куда в роли положить тег образа
notes_tagи внутренний порт приложения 8080: вdefaultsили вvars?
Тег в defaults: это настройка, которую пользователь роли захочет менять, а defaults перекрывается чем угодно. Внутренний порт в vars: он зашит в образ, и менять его снаружи нельзя.
Осторожно: Кладут всё в vars/, «чтобы наверняка». Роль становится негнущейся: ни один параметр не перебить без -e. Правильный шаг: по умолчанию defaults/.
Главное: всё, что пользователь может захотеть поменять, кладут в
defaults/main.yml; вvars/только то, что роль менять не позволяет.
Если одна роль требует другую, это записывают прямо в ней.
Зависимости ролей: meta/main.yml
Часть ролей без других не работает: приложению нужен Docker. Если держать порядок только в плейбуке, его легко нарушить (переставили строки, запустили роль отдельно). Зависимость записывает связь внутри самой роли.
В roles/notes/meta/main.yml:
dependencies:
- role: docker
Когда Ansible берёт роль notes, он сначала выполняет все роли из dependencies, затем саму роль. Если одну и ту же роль подключили несколько раз с одинаковыми параметрами, она выполнится один раз.
Пример: В site.yml стоит одна строка roles: [notes]. Вывод ansible-playbook site.yml --list-tasks (команда печатает задачи в порядке выполнения и ничего не запускает) покажет сначала задачи docker : ..., затем notes : .... Префикс роль : в именах задач показывает, какой роли принадлежит шаг.
Прикинь сам: Задача Compose упала с «Docker not found», а в
site.ymlтолькоroles: [notes]. Где смотреть первым делом?
В roles/notes/meta/main.yml: на месте ли блок dependencies с ролью docker. Затем --list-tasks: задачи docker : ... должны идти перед notes : ....
Осторожно: Зависимость не делает роль «частью» другой: docker можно по-прежнему подключить самостоятельно на сервер, где приложения нет.
Главное:
dependenciesвmeta/main.ymlвыполняются до самой роли, один раз; зависимость не делает роль частью другой.
Теперь ответим на вопрос, какое значение переменной в итоге применится.
Приоритет переменных: кто победил
Одну и ту же переменную можно задать в десятке мест: в роли, в каталоге проекта, в команде. Нужно заранее знать, какое значение применится, иначе неожиданный тег образа уйдёт в боевой запуск.
Правило простое: чем ближе значение к команде, которую ты набираешь, тем оно сильнее. Вот основной порядок от слабого к сильному (полная таблица в документации Ansible длиннее, но для нашего проекта хватает этой):
flowchart LR
A["defaults роли"] --> B["group_vars/all"] --> C["group_vars/группа"] --> D["host_vars"]
D --> E["vars в плейбуке"] --> F["vars роли"] --> G["-e в команде<br>сильнее всех"]
group_vars/каталог рядом с inventory или плейбуком: файлы в нём называются по группе (group_vars/notes.yml), аgroup_vars/all/действует на все серверы;host_vars/то же для одного сервера;-e(extra vars, «дополнительные переменные») задаёт значение прямо в команде:ansible-playbook site.yml -e notes_tag=0.4.2. Побеждает всё. Поэтому-eудобен для разовой правки и опасен: «временный»-eв скрипте CI живёт годами.
Когда результат неожиданный, не гадай, а спроси у Ansible итоговое значение. Добавь в плейбук задачу ansible.builtin.debug с var: notes_tag (debug модуль, печатающий переменную, var имя) и запусти плейбук, лучше с тегом, чтобы выполнилась только она. Команда ansible -m debug -a "var=notes_tag" notes для этого не подходит: ad-hoc запуск не загружает роли из site.yml, поэтому не увидит defaults и vars ролей и переменные плейбука.
Пример: notes_tag задан в трёх местах: defaults роли 0.4.1, group_vars/all/vars.yml 0.4.0, в команде -e notes_tag=0.4.2. Ответ: 0.4.2, потому что -e сильнее всего. Убери -e: победит 0.4.0 (group_vars сильнее defaults). Убери и group_vars: останется 0.4.1. Так по цепочке виден весь смысл приоритета.
Прикинь сам:
notes_tagзадан вdefaultsкак 0.4.1 и вgroup_vars/allкак 0.4.0, запуск без-e. Какой тег уйдёт?
0.4.0: group_vars сильнее defaults. Добавь -e notes_tag=0.4.2, и победит 0.4.2.
Осторожно: «Что ближе к файлу с задачей, то и главнее». Нет: главнее то, что ближе к командной строке. Ещё путают vars роли и vars плейбука: оба сильные, но не равны (vars роли сильнее, чем vars в плейбуке).
Главное: порядок от слабого к сильному: defaults, group_vars, host_vars, vars плейбука, vars роли,
-e; побеждает то, что ближе к командной строке, а не к файлу с задачей.
Пароли тоже переменные, но их в открытом виде хранить нельзя: нужен Vault.
Ansible Vault: секреты в git в зашифрованном виде
Пароль БД нужен плейбуку, плейбук лежит в git, а пароли в git открытым текстом класть нельзя: история хранит их вечно. Без шифрования пришлось бы передавать пароль руками при каждом запуске или хранить в чате. Ansible Vault (встроенный механизм шифрования файлов) позволяет положить секрет в репозиторий в виде, который без пароля не прочитать.
Команда ansible-vault encrypt файл шифрует файл одним паролем, им же потом расшифровывает. Внутри файла остаётся заголовок $ANSIBLE_VAULT;1.1;AES256 и шестнадцатеричный текст. При запуске Ansible расшифровывает значения в памяти и подставляет в шаблоны. Принятая схема из двух файлов в group_vars/all/:
group_vars/all/vars.yml открытый: notes_db_password: "{{ vault_notes_db_password }}"
group_vars/all/vault.yml ЗАШИФРОВАН: vault_notes_db_password: "<секрет>"
В vars.yml лежит только ссылка на секрет. Открытый файл удобен для поиска: grep notes_db_password -r . покажет, где переменная используется. Секретное значение остаётся в vault.yml, а префикс vault_ говорит читателю, откуда оно.
Пароль от vault хранится вне репозитория. У нас это ~/.notes-secrets/ansible-vault-pass с правами 600, а путь к нему указан в ansible.cfg строкой vault_password_file. Это осознанный долг: ключ лежит на твоём ноутбуке, и при смене ноутбука его нужно перенести. Централизованное хранение появится в теме 9 (Vault от HashiCorp, не путать с ansible-vault, см. урок 9.1).
Полезные команды: ansible-vault view файл показывает содержимое, ansible-vault edit файл правит, ansible-vault rekey файл меняет пароль, ansible-vault encrypt_string 'секрет' --name имя зашифровывает одну строку для вставки прямо в YAML.
flowchart TD
V["vault.yml в git<br>зашифрован"] --> M["расшифровка в памяти<br>пароль из ~/.notes-secrets/ansible-vault-pass"]
M --> T["шаблон notes.env.j2"]
T -->|"SSH"| F["/etc/notes/notes.env на ВМ<br>открытым текстом, права 0640"]
Пример: Файл vault.yml после шифрования:
$ANSIBLE_VAULT;1.1;AES256
36323431386533613538323261353762313331366335363330333462303836666436396264316531
...
Первая строка говорит, что это vault версии 1.1 (AES256 это название шифра). Остальное это зашифрованный текст. По git log -p и по git diff пароль не прочитать. Но есть две оговорки: git покажет, что файл изменился целиком (по тексту не понять, какая переменная поменялась), и пароль на ВМ всё равно окажется в /etc/notes/notes.env открытым текстом: vault защищает репозиторий, а не сервер.
Ещё один риск: Ansible печатает в вывод параметры задач, и пароль из шаблона может попасть в лог. Параметр no_log: true у задачи запрещает печатать её параметры и результат, вместо них будет censored. Он прячет секрет только из вывода Ansible, но не из файла на сервере.
Для любопытных: сменить пароль БД и дать пароль vault в CI
Сменить пароль БД. Изменить переменную в vault.yml мало: POSTGRES_PASSWORD читается только при первой инициализации тома, у работающей базы пароль не поменяется, и приложение перестанет подключаться. Порядок такой:
- Сделай резервную копию:
docker compose -f /opt/notes/compose.yml exec -T db pg_dump -U notes notes > notes-backup.sql(проверь, что файл не пустой). - Смени пароль в работающей БД:
docker compose -f /opt/notes/compose.yml exec db psql -U notes -d notes, внутриALTER USER notes PASSWORD '<новый пароль>';. - Впиши новый пароль в
vault.yml(ansible-vault edit). - Выкати роль:
ansible-playbook site.yml.
Пароль vault в CI. На сервере сборки нет твоего ~/.notes-secrets, поэтому пароль vault кладут в секрет самого CI (раздел секретов в настройках пайплайна). Перед запуском пайплайн пишет его во временный файл и удаляет после: printf '%s' "$VAULT_PASS" > .vp && chmod 600 .vp && ansible-playbook site.yml --vault-password-file .vp; rm -f .vp. Если у тебя несколько vault с разными паролями (например, для dev и prod), каждому дают метку: ansible-vault encrypt --vault-id prod@prompt файл, а при запуске перечисляют --vault-id prod@путь_к_файлу.
Прикинь сам: Ты закоммитил зашифрованный
vault.yml, а файл с паролем vault тоже случайно попал в git. Что с защитой?
Защиты нет: ключ лежит рядом с замком, и история git хранит его вечно. Порядок действий: сначала меняют настоящие секреты (пароль БД и токены), потом делают rekey для будущих коммитов, потом убирают ключ из репозитория. Старые коммиты расшифровывает утёкший ключ, поэтому одной смены пароля vault мало.
Осторожно:
ansible-vaultи HashiCorp Vault. Это разные вещи: первое шифрует файл для Ansible, второе отдельный сервис хранения секретов (тема 9).- «Зашифровал, значит, можно коммитить и пароль vault рядом». Нельзя: ключ рядом с замком это отсутствие замка.
- «Потерял пароль vault, достану из git». Нельзя: без пароля расшифровать невозможно, файл пересоздают заново.
Главное: Vault шифрует файл для хранения в git, пароль от него лежит вне репозитория; защищается репозиторий, а не сервер.
После расшифровки пароль окажется в файле на ВМ, и его надо защитить правами.
Права на секретный файл
После расшифровки пароль оказывается в файле .env на ВМ. Если файл читают все, в системе любой процесс и любой пользователь получит пароль БД. Нужно дать право чтения только тем, кому оно необходимо.
Права на файл выражаются тройкой «владелец, группа, остальные» (урок 1.3). Режим 0640 означает: владелец читает и пишет (6), группа только читает (4), остальные ничего (0). Владелец root, группа notes: читать файл могут root и сервис от пользователя в группе notes. Режим нужно задавать в самой задаче template, а не рассчитывать на права по умолчанию: без явного mode файл создастся с правами, которые задаёт системная маска umask (обычно это 0644), то есть читаемым для всех. Каталог /etc/notes получает 0750, чтобы чужие пользователи не могли даже посмотреть список файлов.
Пример: Результат проверки: stat -c '%a %U:%G' /etc/notes/notes.env печатает 640 root:notes. Формат %a даёт права числом, %U владельца, %G группу. Если вместо этого 644 root:root, в задаче потерялся mode или group.
Прикинь сам: Зачем
mode: "0640"писать в самой задачеtemplate, если потом можно сделатьchmod?
Между созданием файла и chmod пароль какое-то время читают все, а ручной chmod не воспроизводится на новом сервере. Режим в задаче выставляется при создании файла.
Осторожно: права защищают файл на сервере, а no_log (см. выше) только вывод Ansible. Это разные слои защиты, нужны оба.
Главное:
0640с владельцемrootи группойnotesпускает читать root и сервис; режим пишут в самой задаче, а не отдельнымchmod.
Для запуска Compose нужны модули, которых нет в ядре Ansible: коллекции.
Коллекции и модуль community.docker
Ядро Ansible содержит только базовые модули (apt, copy, template, service). Для всего остального есть коллекции (collections): отдельно устанавливаемые пакеты модулей. Без них для Compose пришлось бы вызывать docker compose up -d командой и вручную проверять, изменилось ли что-то, то есть терять идемпотентность.
Коллекцию ставишь на свой компьютер (управляющий узел), а не на сервер: модули запускает Ansible оттуда. Для Compose нужна коллекция community.docker, а в ней модуль docker_compose_v2: он вызывает на сервере команду docker compose (это плагин к программе docker, он ставится пакетом docker-compose-plugin) и сам решает, нужно ли что-то менять. Версию коллекции закрепляют в файле requirements.yml:
collections:
- name: community.docker
version: "5.0.0" # закреплено, чтобы у всех была одна версия
Установка командой ansible-galaxy collection install -r requirements.yml (Galaxy это каталог ролей и коллекций Ansible). Полное имя модуля вместе с коллекцией называют FQCN (из урока 7.4), например ansible.builtin.apt или community.docker.docker_compose_v2: сначала коллекция, потом модуль. Ключевые параметры: project_src (каталог с compose.yml), env_files (файлы с переменными для ${...} в compose-файле), state: present (поднять стек, как up -d), pull: missing (скачать образ, только если его нет на сервере).
Пример: Первый запуск: образов нет, модуль скачивает их, создаёт контейнеры и сообщает changed. Второй запуск: контейнеры уже работают с теми же настройками, модуль ничего не делает и сообщает ok. Поменялся notes_tag и изменился compose.yml: модуль пересоздаёт только затронутый контейнер.
Прикинь сам: Зачем закреплять версию коллекции в
requirements.yml, если всё и так работает?
Без закрепления через полгода у коллеги и в CI окажутся разные версии модулей: плейбук начнёт вести себя иначе. Закреплённая версия даёт воспроизводимость.
Осторожно: Коллекцию устанавливают один раз на управляющем узле, а не на каждом сервере. Если забыть, будет couldn't resolve module/action 'community.docker.docker_compose_v2'.
Главное: коллекция это пакет модулей, её ставят один раз на управляющий узел через
ansible-galaxy; модульdocker_compose_v2сам решает, нужно ли менять стек.
В шаблоне Compose встретятся два вида подстановок, их нельзя путать.
Два уровня подстановки: Jinja2 и Compose
В файле compose.yml.j2 встречаются и {{ notes_image }}, и ${POSTGRES_PASSWORD}. Выглядят похоже, но их обрабатывают разные программы в разное время. Если смешать, получишь либо пустое значение, либо ошибку.
Как это устроено:
- На твоём компьютере Ansible обрабатывает шаблон
compose.yml.j2шаблонизатором Jinja2 (урок 7.5): всё в двойных фигурных скобках заменяется значениями переменных. Конструкция${...}для Jinja2 просто текст. - Готовый
compose.ymlкопируется на ВМ. - На ВМ Compose читает файл и сам подставляет
${POSTGRES_PASSWORD}из файла окружения, переданного черезenv_files.
Пример: Строка шаблона image: {{ notes_image }}:{{ notes_tag }} на шаге 1 превращается в image: ghcr.io/user/notes:0.4.1. Строка POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} на шаге 1 не меняется, а на шаге 3 Compose подставит значение из /etc/notes/notes.env. Поэтому пароль в самом compose.yml не оказывается.
Прикинь сам: Где подставится значение в двойных фигурных скобках, а где в
${...}вcompose.yml.j2?
Первое подставит Ansible на твоём компьютере при рендере шаблона, второе подставит Compose на ВМ при запуске, читая файл окружения.
Осторожно: Пробуют подставлять секрет через Jinja2 прямо в compose.yml: тогда пароль попадает в файл с правами 0644, читаемый всеми. Секрет должен жить только в .env с правами 0640.
Главное: Jinja2 работает на твоём компьютере до отправки файла,
${...}читает Compose на ВМ; секрет подставляют вторым способом, чтобы он не попал в читаемый всеми файл.
Роль нужно проверять до запуска на десятках серверов.
Как проверять роль: lint, check, повторный запуск
Роль запускают на десятках серверов, и ошибка размножается. Нужны проверки, которые ловят ошибки до боевого запуска.
От дешёвых проверок к дорогим:
ansible-playbook site.yml --syntax-check: проверка синтаксиса YAML и структуры без подключения к серверам;ansible-lint: линтер (программа проверки стиля и плохих практик, урок 7.5);--list-tasks: список задач и порядок, без выполнения;--check --diff: «сухой прогон», показывающий, что изменилось бы;--diffдобавляет построчное сравнение файлов;- боевой запуск на одной тестовой ВМ, затем второй запуск: при правильной роли
changed=0(идемпотентность).
Для ролей, которыми пользуются многие, добавляют Molecule (инструмент, который поднимает временную ВМ или контейнер, выполняет роль и проверяет результат). В учебном проекте мы его не ставим.
Пример: Опечатка в имени переменной в шаблоне: --syntax-check её не найдёт (синтаксис верный), а --check --diff найдёт: задача template упадёт с 'notes_tg' is undefined ещё до изменений. Опечатка в отступе YAML ловится на первом шаге.
Прикинь сам: Опечатка в имени переменной в шаблоне: поймает ли её
--syntax-check?
Нет, синтаксис верный. Её найдёт --check --diff: задача template упадёт с is undefined ещё до изменений.
Осторожно: --check не безопасен на 100%: модули command и shell в этом режиме пропускаются, и задачи, зависящие от их результата, могут вести себя иначе. Если команда только читает, как наша с dpkg, ей ставят check_mode: false; остальные места проверяй вручную.
Главное: проверки идут от дешёвых к дорогим: синтаксис, линтер, список задач, сухой прогон, один тестовый хост и повторный запуск с
changed=0.
Проверь понимание: второй запуск роли показывает
changed=2, хотя на сервере ничего не меняли. Что это говорит о роли?
Ответ
Роль неидемпотентна: две задачи каждый раз «меняют» состояние, например пишут файл с меняющимся содержимым (время, случайное значение) или используют command без changed_when. Нужно найти эти задачи по выводу (они помечены changed) и сделать их идемпотентными.
Для готовности приложения одной проверки статуса мало: нужно ждать.
Цикл loop и проверка готовности: retries и until
Одну задачу часто нужно выполнить для нескольких значений (создать два каталога), а после запуска приложения подождать, пока оно начнёт отвечать. Без ожидания плейбук рапортует «готово», когда приложение ещё стартует.
Параметр loop принимает список. Для каждого элемента Ansible выполняет задачу, а текущий элемент доступен как item. В роли notes список состоит из двух словарей (path, group, mode), и задача file создаёт оба каталога с разными правами. Связка retries, delay и until работает так: Ansible выполняет задачу, проверяет условие из until, а если оно ложно, ждёт delay секунд и повторяет, максимум retries раз. Если условие так и не выполнилось, задача падает.
Адрес для проверки выбираем /readyz, а не /healthz. /healthz отвечает «процесс жив» и в базу не ходит, поэтому будет 200 даже при недоступной БД. /readyz проверяет зависимости и отвечает 200, только когда приложение видит базу (урок 4.5). Нам нужно «готово принимать запросы», значит /readyz.
Пример: Проверка /readyz с retries: 10 и delay: 3 даёт приложению около 30 секунд на старт (девять пауз по 3 секунды). Первая попытка сразу после docker compose up может получить «connection refused» (порт ещё не слушает). Ansible печатает FAILED - RETRYING и пробует снова. Когда приходит код 200, задача проходит. Так в плейбуке закреплён принцип «роль считается выполненной, когда приложение отвечает, а не когда команда запуска вернулась».
Прикинь сам:
retries: 3иdelay: 2, а приложение стартует 20 секунд. Что будет?
Ansible сделает три попытки с двумя паузами по 2 секунды (около четырёх секунд всего) и упадёт, хотя приложение потом запустится. Время подбирают с запасом.
Осторожно: Принимают RETRYING за ошибку. Это нормальная часть ожидания, ошибкой считается только итоговый FAILED после всех попыток.
Главное:
loopповторяет задачу для каждого элемента;retries,delayиuntilдают приложению время стартовать;RETRYINGэто ожидание, а не ошибка.
Теперь главный тест роли: что показывает повторный запуск.
Идемпотентность роли: почему «повторный запуск» главный тест
Роль запускают много раз: при каждом изменении, по расписанию, на новых серверах, поэтому повторный запуск не должен ничего «менять». Как работает идемпотентность и чем опасны command и shell, мы разобрали в уроке 7.5; здесь важны две вещи.
Пример: в роли docker задача «Архитектура dpkg» запускает dpkg --print-architecture. Без changed_when: false она каждый раз будет changed, и проверка «второй запуск даёт changed=0» не пройдёт.
Прикинь сам: Второй запуск дал
changed=0. Значит ли это, что приложение работает?
Нет: если приложение было сломано и осталось сломанным, тоже будет changed=0. Поэтому смотрят и результат: curl /readyz.
Главное:
changed=0говорит «ничего не менялось», а не «всё настроено верно»: результат проверяют отдельно.
Для любопытных: роли в работе (import_role, galaxy init, serial)
roles:в плейбуке подключает роль заранее, при разборе файла. Если роль нужно включить по условию или во время выполнения, пишут задачуansible.builtin.import_role(статично, какroles:) илиansible.builtin.include_role(выполняется, когда до неё дошла очередь, имя роли можно собрать из переменной).- Скелет новой роли с нужными каталогами создаёт
ansible-galaxy init имя_роли. - Роль это один кусок настройки, коллекция это пакет, в котором могут лежать модули, плагины и роли вместе (как
community.docker). - Когда серверов много, плейбук катят пачками: строка
serial: 1в play берёт хосты по одному, и если на первом случился сбой, остальные Ansible уже не трогает. Так ошибка не размножается на все серверы разом. При одном сервереserialсмысла не имеет, в нашем проекте он не нужен.
Соберём всё в один запуск.
Сквозной разбор: что происходит при ansible-playbook site.yml
Ты в ~/notes/infra/ansible и выполняешь ansible-playbook site.yml.
flowchart TD
A["1. ansible.cfg: inventory, SSH, vault_password_file"] --> B["2. inventory.yml: группа notes с одной ВМ"]
B --> C{"3. group_vars и vault.yml<br>расшифрованы?"}
C -->|"нет: Decryption failed"| X1["проблема в пароле vault<br>до ВМ дело не дошло"]
C -->|"да"| D["4. SSH на ВМ, сбор фактов"]
D --> E{"5a. роль docker<br>отработала?"}
E -->|"нет"| X2["роль notes не стартует<br>проблема в Docker"]
E -->|"да"| F{"5b. роль notes:<br>каталоги, notes.env, compose, /readyz"}
F -->|"undefined variable"| X3["значения не дошли:<br>group_vars и имя переменной"]
F -->|"ok"| G["6-7. handlers и PLAY RECAP"]
Если падает шаг 3 (Decryption failed), до ВМ дело не доходит: проблема в пароле vault. Если падает шаг 5a, роль notes даже не стартует: проблема в Docker. Если шаг 5b падает на undefined variable, значения не дошли: проверь group_vars и имя переменной. Диагностика в Ansible сводится к вопросу «на каком шаге этой цепочки остановились».
Прикинь сам: На каком шаге упадёт запуск, если пароль vault неверен?
На шаге 3, при расшифровке: Decryption failed. До ВМ дело не доходит.
Главное: диагностика в Ansible сводится к вопросу, на каком шаге цепочки остановились: конфиг, инвентарь, vault, вход, роль docker или роль notes.
Соответствие AWS
| Что в Ansible | Ближайшее в AWS |
|---|---|
роль docker (настройка ОС) |
AMI с Packer или EC2 Image Builder |
ansible-vault |
AWS Secrets Manager, SSM Parameter Store (для зашифрованных значений) |
| плейбук по SSH | SSM Run Command, State Manager |
site.yml целиком |
User Data + CloudFormation cfn-init |
--limit на группу |
Target по тегу в SSM |
(AMI это готовый образ ВМ; Packer это программа, которая собирает такие образы. Secrets Manager и SSM Parameter Store это сервисы AWS для хранения секретов и параметров.)
Практика
Целевая машина: ВМ notes-vm из уроков 6.2 и 7.2 (или Multipass-ВМ Ubuntu 24.04). Inventory и ansible.cfg готовы с урока 7.4. Работаем в ~/notes/infra/ansible/.
Задание 1. Роль docker: apt-репозиторий Docker
Цель: установить Docker Engine и Compose-плагин из официального apt-репозитория, чтобы повторный запуск ничего не менял.
Предскажи: сколько задач покажут changed при втором запуске роли? Почему?
Ответ
Ноль. Модули apt, get_url, deb822_repository и systemd_service проверяют состояние и меняют его только при расхождении.
Шаги:
-
Создай каталоги роли:
cd ~/notes/infra/ansible mkdir -p roles/docker/{tasks,defaults,handlers} -
roles/docker/defaults/main.yml: версию репозитория и список пакетов выносим в значения по умолчанию:# Релиз Ubuntu для репозитория Docker (можно перебить, если у Docker нет нового) docker_apt_release: "{{ ansible_facts['distribution_release'] }}" # Пакеты, которые ставим из репозитория Docker docker_packages: - docker-ce - docker-ce-cli - containerd.io - docker-compose-plugin -
Перенеси задачи из
playbooks/docker.yml(урок 7.5) вroles/docker/tasks/main.yml: только списокtasks, без строкname,hostsиbecomeсамого play (они остаются в плейбуке). Отличия от того, что ты писал в 7.5, четыре:# 1. Новая первая задача: ca-certificates и curl раньше ставил base.yml, а в роли их ставим сами - name: Зависимости для apt по HTTPS ansible.builtin.apt: name: [ca-certificates, curl] state: present update_cache: true cache_valid_time: 3600 # ... дальше как в docker.yml: каталог ключей, ключ, python3-debian ... # 2. Результат команды получает префикс роли: так имя не пересечётся с чужими переменными - name: Архитектура dpkg ansible.builtin.command: dpkg --print-architecture register: docker_arch changed_when: false check_mode: false # 3. Релиз и архитектура берутся из переменных роли - name: Репозиторий Docker ansible.builtin.deb822_repository: # name, types, uris, components, signed_by, state, enabled как в docker.yml suites: "{{ docker_apt_release }}" architectures: "{{ docker_arch.stdout }}" # 4. Список пакетов приходит из defaults - name: Docker Engine и Compose-плагин ansible.builtin.apt: name: "{{ docker_packages }}" state: present update_cache: true notify: Перезапустить dockerЗадача «Docker включён и запущен» остаётся как была, а
handlersпереезжают в отдельный файл (следующий шаг). -
roles/docker/handlers/main.yml:- name: Перезапустить docker ansible.builtin.systemd_service: name: docker state: restarted -
Сохрани прежний
site.ymlиз 7.5 и создай временный (он подключает только рольdocker):cp site.yml site.yml.7-5.bak- name: Настройка сервера «Заметки» hosts: notes # группа из inventory.yml урока 7.4 become: true roles: - dockerФайлы
playbooks/*.ymlиз 7.5 теперь только справочные:site.ymlих больше не подключает, а их работа переезжает в роли. -
Запусти дважды:
ansible-playbook site.yml ansible-playbook site.yml
Что должно получиться: в конце второго запуска:
PLAY RECAP *********************************************************************
notes-vm : ok=9 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Число ok зависит от версии роли и модулей (у нас сбор фактов плюс восемь задач роли). Смотри на changed и failed: оба должны быть нулями. Вывод ориентировочный: эту роль на ВМ мы целиком не прогоняли.
Разбор команд:
mkdir -p roles/docker/{tasks,defaults,handlers}: создаёт сразу три каталога;-pсоздаёт и родителяroles/docker, и не ругается, если каталог уже есть;{a,b,c}это раскрытие в оболочке, оно превращается в три пути.cp site.yml site.yml.7-5.bak: копия старой точки входа из 7.5, чтобы было куда вернуться.ansible-playbook site.yml: запускает плейбук;site.ymlтрадиционное имя «главного» плейбука проекта.ansible notes -a "docker compose version": одноразовая команда (ad-hoc, урок 7.4) на хосты группыnotes;-aпередаёт аргументы модулю по умолчаниюcommand.
ИИ: структуру роли
dockerможно попросить набросать у нейросети, но имена параметров модулейaptиget_urlсверяй сansible-doc, а не с её памятью.
Как читать вывод: при первом запуске в списке TASK [docker : ...] у большинства задач changed: система менялась. Строка RUNNING HANDLER [docker : Перезапустить docker] появляется один раз в конце, потому что пакеты ставились. При втором запуске всё ok, а handler не запускается вообще. Префикс docker : перед названием задачи показывает роль. Смотри в PLAY RECAP на changed и failed: остальное справочное. Если выводишь только хвост: ansible-playbook site.yml | tail -n 3.
Про apt-key: так называлась старая команда добавления ключа. Она объявлена устаревшей, потому что ключ становился доверенным для всех репозиториев сразу: подпись чужого репозитория тоже принималась. Параметр signed_by привязывает ключ к одному репозиторию.
Проверка на ВМ: ansible notes -a "docker compose version" печатает строку вида Docker Compose version v5.x (номер версии у тебя будет свой).
Объясни себе:
- Зачем
signed_byи ключ в/etc/apt/keyrings, а неapt-key? - Почему
distribution_releaseберётся из фактов, а не пишется руками? - Когда сработает handler и почему не при втором запуске?
Типичные ошибки:
E: The repository 'https://download.docker.com/linux/ubuntu <кодовое_имя> Release' does not have a Release file.: у Docker нет каталога для кодового имени твоего релиза Ubuntu (бывает сразу после выхода нового релиза). Посмотри список на https://download.docker.com/linux/ubuntu/dists/ и временно укажи последний поддержанный LTS в переменнойdocker_apt_releaseвместо факта.Task failed: Missing sudo password(в старых версияхFAILED! => {"msg": "Missing sudo password"}): забытbecome: trueили на ВМ нетNOPASSWD. Проверь урок 7.4.changed=1на каждом запуске у задачи «Архитектура dpkg»: забытchanged_when: false. Команда только читает, но Ansible про это не знает. А безcheck_mode: falseв сухом прогонеdocker_archостанется пустым.This module requires the python3-debian package: задача сpython3-debianстоит после репозитория или удалена. Модульdeb822_repositoryсам использует эту библиотеку на ВМ.
Задание 2. Vault: зашифруй пароль БД
Цель: положить пароль БД в зашифрованный файл и убедиться, что в git он не читается.
Предскажи: что покажет cat group_vars/all/vault.yml после шифрования: пароль, часть пароля или что-то ещё?
Ответ
Заголовок $ANSIBLE_VAULT;1.1;AES256 и строки шестнадцатеричного текста. Пароля нет.
Шаги:
-
Сгенерируй пароль vault и пароль БД, ни один не печатай в терминал:
mkdir -p ~/.notes-secrets && chmod 700 ~/.notes-secrets openssl rand -base64 24 > ~/.notes-secrets/ansible-vault-pass chmod 600 ~/.notes-secrets/ansible-vault-pass -
В
ansible.cfgв секцию[defaults]добавь строку:vault_password_file = ~/.notes-secrets/ansible-vault-pass -
Создай открытый файл и шифруемый файл:
mkdir -p group_vars/all printf '# Секреты из vault.yml через префикс vault_\nnotes_db_password: "%s"\n' '{{ vault_notes_db_password }}' > group_vars/all/vars.yml printf 'vault_notes_db_password: "%s"\n' "$(openssl rand -hex 24)" > group_vars/all/vault.yml ansible-vault encrypt group_vars/all/vault.yml -
Проверь, что видно снаружи и что внутри:
head -n 2 group_vars/all/vault.yml ansible-vault view group_vars/all/vault.yml | sed 's/: ".*"/: "***"/'
Что должно получиться:
$ANSIBLE_VAULT;1.1;AES256
36323431386533613538323261353762313331366335363330333462303836666436396264316531
vault_notes_db_password: "***"
Объясни себе:
- Зачем два файла, а не один зашифрованный
vars.yml? - Что будет с историей git, если ты потеряешь пароль vault?
- Почему пароль БД генерируется, а не придумывается?
Разбор команд:
openssl rand -hex 24: берёт 24 случайных байта и печатает их шестнадцатеричными знаками (48 символов 0-9a-f). Так в пароле нет/,+,=, которые ломают разбор адресаpostgresql://...вDATABASE_URL; это и есть пароль. Вывод уходит в файл через>, поэтому на экране его нет.chmod 700иchmod 600: права только для владельца (каталог и файл соответственно, урок 1.3).ansible-vault encrypt файл: заменяет содержимое файла зашифрованным (файл перезаписывается на месте). Пароль берёт изvault_password_file.head -n 2: первые две строки файла, этого хватает, чтобы увидеть заголовок.ansible-vault view ... | sed 's/: ".*"/: "***"/': показывает расшифрованное содержимое и сразу замазывает значение звёздочками, чтобы пароль не попал в терминал и историю экрана.
Как читать вывод: первая строка $ANSIBLE_VAULT;1.1;AES256 подтверждает, что файл зашифрован (если видишь vault_notes_db_password: ... открытым текстом, шифрование не сработало). Вторая строка шестнадцатеричный мусор: так и должно быть. Длина этой строки у тебя будет другой, это нормально.
Типичные ошибки:
[ERROR]: Attempting to decrypt but no vault secrets found.: вansible.cfgнетvault_password_fileи не передан--ask-vault-pass. Добавь строку из шага 2.[ERROR]: Decryption failed (no vault secrets were found that could decrypt).: пароль в файле не тот, которым шифровали. Восстанови верный пароль или зашифруй файл заново.Vault format unhexlify error: Odd-length string: файл повреждён при правке вручную. Верни из git прежнюю версию.
Задание 3. Роль notes: compose и .env из vault
Каркас роли и шаблоны возьми из примеров. Проследи путь значения от переменной, включая пароль из Vault, до готового файла на сервере и найди задачу, которая запускает Compose после изменения. Не нужно писать все файлы роли по памяти; нужно объяснить разделение задач, шаблонов и переменных и проверить результат повторным запуском.
Цель: роль кладёт на ВМ compose.yml и .env (читают только root и группа notes), затем поднимает стек.
Предскажи: какие права будут у /etc/notes/notes.env и кто сможет его прочитать на ВМ? Почему это важно в модуле template?
Ответ
Владелец root, группа notes, режим 0640. Читают root и участники notes. Режим задаётся в самой задаче, иначе пароль окажется на диске с umask по умолчанию (0644), доступный всем.
Шаги:
-
Каталоги и зависимость от роли
docker:mkdir -p roles/notes/{tasks,defaults,vars,meta,templates} cat > roles/notes/meta/main.yml <<'YML' # Роль docker выполняется до notes автоматически dependencies: - role: docker YML -
roles/notes/defaults/main.yml. Пакет с образом в GitHub Packages сделай публичным (иначе на ВМ потребуетсяdocker login ghcr.io):notes_tag: "0.4.1" # тег образа, latest не используем notes_image: "ghcr.io/CHANGE_ME/notes" # замени CHANGE_ME на свой ник GitHub строчными буквами notes_dir: /opt/notes # код и compose, владелец root notes_env_dir: /etc/notes # конфиг, режим 640 root:notesroles/notes/vars/main.yml: то, что менять снаружи нельзя (порт зашит в образ):notes_internal_port: 8080 # на этом порту приложение слушает внутри контейнера -
roles/notes/tasks/main.yml:- name: Системная группа notes ansible.builtin.group: name: notes system: true - name: Каталоги проекта ansible.builtin.file: path: "{{ item.path }}" state: directory owner: root group: "{{ item.group }}" mode: "{{ item.mode }}" loop: - { path: "{{ notes_dir }}", group: root, mode: "0755" } - { path: "{{ notes_env_dir }}", group: notes, mode: "0750" } - name: Файл окружения с паролем БД ansible.builtin.template: src: notes.env.j2 dest: "{{ notes_env_dir }}/notes.env" owner: root group: notes mode: "0640" no_log: true - name: compose.yml ansible.builtin.template: src: compose.yml.j2 dest: "{{ notes_dir }}/compose.yml" owner: root group: root mode: "0644" - name: Стек запущен community.docker.docker_compose_v2: project_src: "{{ notes_dir }}" env_files: - "{{ notes_env_dir }}/notes.env" state: present pull: missing - name: Приложение отвечает на /readyz ansible.builtin.uri: url: http://127.0.0.1/readyz status_code: 200 register: notes_health retries: 10 delay: 3 until: notes_health.status == 200 -
roles/notes/templates/notes.env.j2:STORE=postgres POSTGRES_PASSWORD={{ notes_db_password }} DATABASE_URL=postgresql://notes:{{ notes_db_password }}@db:5432/notes APP_VERSION={{ notes_tag }} -
roles/notes/templates/compose.yml.j2:services: notes: image: {{ notes_image }}:{{ notes_tag }} ports: - "80:{{ notes_internal_port }}" # TLS и nginx перед приложением: урок 6.3 env_file: {{ notes_env_dir }}/notes.env restart: unless-stopped depends_on: db: condition: service_healthy db: image: postgres:18 environment: POSTGRES_USER: notes POSTGRES_DB: notes POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - pgdata:/var/lib/postgresql healthcheck: test: ["CMD-SHELL", "pg_isready -U notes -d notes"] interval: 5s retries: 10 restart: unless-stopped volumes: pgdata: -
Обнови
site.yml, оставив только рольnotes(dockerпридёт по зависимости) и запусти. Что переехало из плейбуков 7.5: пакетыca-certificatesиcurlушли в рольdocker, каталоги и шаблон окружения в рольnotes,playbooks/docker.ymlстал рольюdocker. Что не переехало изbase.yml: системный пользовательnotes(теперь есть только группа, а приложение работает в контейнере) и пакетjq. Группаnotesвhostsэто группа изinventory.ymlурока 7.4.cat > site.yml <<'YML' - name: Настройка сервера «Заметки» hosts: notes become: true roles: - notes YML ansible-galaxy collection install community.docker:==5.0.0 ansible-playbook site.yml
Что должно получиться: запуск заканчивается failed=0, а на ВМ:
$ ansible notes --become -a "stat -c '%a %U:%G' /etc/notes/notes.env"
notes-vm | CHANGED | rc=0 >>
640 root:notes
Проверка сайта: curl -s http://<IP ВМ>/readyz печатает ready. Повторный ansible-playbook site.yml даёт changed=0. На настроенной ВМ --check --diff покажет changed=0. На чистой ВМ сухой прогон отметит changed у задач, которые что-то поставили бы, а шаги, зависящие от них, могут упасть: это ограничение check-режима, а не ошибка роли (--check ничего не меняет на сервере, --diff показывает, что изменилось бы, по строкам). Задача с dpkg выполняется и в сухом прогоне благодаря check_mode: false.
Разбор ключевого:
dependenciesвmeta/main.yml: Ansible выполнит рольdockerпередnotes, поэтому вsite.ymlдостаточно одной роли.loopсitem.path,item.group,item.mode: одна задача создаёт два каталога, подставляя значения из списка по очереди.no_log: true: Ansible не печатает параметры и результат задачи; вместо них в выводеcensored.retries: 10,delay: 3,until: проверка повторяется до десяти раз с паузой 3 секунды, пока/readyzне вернёт 200. Приложению нужно время на старт, а БД наhealthcheck.ansible-galaxy collection install community.docker:==5.0.0: ставит коллекцию на твой компьютер,==закрепляет точную версию.
ИИ: если стек не поднялся, отдай нейросети вывод
docker compose logsбез паролей и попроси указать первую строку с ошибкой: причину проверь сам на ВМ.
Как читать вывод: при первом запуске в PLAY RECAP ищи failed=0. В списке задач TASK [notes : Файл окружения с паролем БД] покажет changed без параметров (из-за no_log). TASK [notes : Стек запущен] на первом запуске changed (скачиваются образы, это дольше остальных). TASK [notes : Приложение отвечает на /readyz] может показать FAILED - RETRYING: ... (10 retries left): это нормальная пауза, пока приложение стартует, если потом идёт ok. Если все десять попыток закончились ошибкой, смотри логи контейнера на ВМ: docker compose -f /opt/notes/compose.yml logs.
Объясни себе:
- Почему пароль не появился в выводе плейбука?
- Что произойдёт, если поменять только
notes_tagи запустить снова?
Типичные ошибки:
[ERROR]: Task failed: 'notes_db_password' is undefined(строкаfatal:скрыта: у задачиno_log: true): не подхватилсяgroup_vars/all/vars.yml. Каталогgroup_varsдолжен лежать рядом с inventory или плейбуком.[ERROR]: couldn't resolve module/action 'community.docker.docker_compose_v2'. ...: не установлена коллекция. Выполниansible-galaxy collection install community.docker:==5.0.0.manifest unknown(полностьюmanifest for ghcr.io/<ник>/notes:0.4.1 not found: manifest unknown): образа с таким именем или тегом нет в реестре. Проверьnotes_image(ник строчными буквами, не осталось лиCHANGE_ME) иnotes_tag.unauthorizedпри скачивании образа: пакет в GitHub Packages приватный. Сделай его публичным либо выполни на ВМdocker login ghcr.io.
Задание 4. Шаг проекта: «Заметки» одним запуском на чистой ВМ
Цель: зафиксировать роли в репозитории и проверить полный цикл на чистой ВМ.
Шаги:
-
Добавь
requirements.yml:collections: - name: community.docker version: "5.0.0" -
Закоммить и запусти на свежей ВМ (пересоздай её или удали контейнеры и
/opt/notes):cd ~/notes git add infra/ansible git commit -m "feat(infra): роли docker и notes, vault для пароля БД" cd infra/ansible ansible-galaxy collection install -r requirements.yml time ansible-playbook site.yml -
Проверь снаружи и повторно:
curl -s -o /dev/null -w '%{http_code}\n' http://<IP ВМ>/readyz ansible-playbook site.yml | tail -n 3
Что должно получиться:
200
PLAY RECAP *********************************************************************
notes-vm : ok=15 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Число ok зависит от версий роли и модулей (у нас около 15). Смотри на changed и failed: оба должны быть нулями, а не на точное ok. Вывод ориентировочный: стек Compose на чистой ВМ в этой версии урока не прогонялся, поэтому 640 root:notes, 200 и число ok сверяй со своим запуском. Команда time в шаге 2 печатает, сколько заняло выполнение: на чистой ВМ несколько минут (установка Docker, скачивание образов), на второй запуск секунды.
Как читать вывод: 200 это код ответа /readyz (-o /dev/null выбрасывает тело, -s убирает индикатор, -w '%{http_code}\n' печатает только код). Повторный запуск не должен ничего менять: если changed не ноль, смотри, какие задачи помечены жёлтым.
Роли и плейбук лежат в твоём репозитории ~/notes/infra/ansible.
Объясни себе:
- Что осталось долгом: где хранится пароль vault и что будет при смене ноутбука?
Типичные ошибки:
UNREACHABLE! => {"msg": "Failed to connect to the host via ssh: ... Permission denied (publickey)."}: у ВМ пересоздан ключ или сменился IP. Обновиinventory.yml(урок 7.4).Could not find or access 'notes.env.j2': шаблон лежит не вroles/notes/templates/.
Сломай и почини
Запусти скрипт из клона курса и не читай его: bash <клон-курса>/devops/project/notes/break/7.6/break.sh 1 (или 2, 3). Он вносит одну поломку в ~/notes/infra/ansible; вернуть всё как было: bash <клон-курса>/devops/project/notes/break/7.6/break.sh fix.
Симптом
После запуска ansible-playbook site.yml падает или показывает не то, что ты ждёшь. Одна из картин: ошибка про vault («Decryption failed»), «is undefined» в задаче шаблона, или тихо подменённое значение (в --check --diff другой тег образа, ошибки нет).
Гипотезы
- Файл vault зашифрован другим паролем или в
ansible.cfgуказан не тот файл пароля. - В шаблоне опечатка в имени переменной либо переменная не объявлена.
- Переменную перекрыло значение с более высоким приоритетом (например,
roles/notes/vars/main.yml). - Дополнительно: потеряна зависимость
dockerвmeta/main.yml, и Compose идёт раньше установки Docker.
Проверки
ansible-playbook site.yml --syntax-check
ansible-playbook site.yml --list-tasks
ansible-vault view group_vars/all/vault.yml >/dev/null && echo vault-ok
ansible -m debug -a "msg={{ notes_db_password | length }}" notes
grep -rn "dependencies" roles/notes/meta/main.yml
Порядок в --list-tasks показывает, идёт ли docker до notes. Вывод vault-ok подтверждает пароль. Число вместо ошибки is undefined значит, что переменная пришла из group_vars; значение пароля в терминал не печатаем, смотрим только длину.
Исправление
Разбор всех сценариев
- Неверный пароль vault: проверь
vault_password_fileвansible.cfgи файл~/.notes-secrets/ansible-vault-pass. Если пароль потерян, файлvault.ymlпересоздают заново и шифруют новым паролем, а пароль БД меняют в работающей базе (порядок в разделе про Vault). - Шаблон Jinja2 без переменной: найди имя в ошибке
'xxx' is undefined, сверь сdefaults/main.ymlиgroup_vars. Обычно опечатка в шаблоне или пропавшая строка вvars.yml. - Переменная перекрыта: ошибки нет, а
ansible-playbook site.yml --check --diffпоказывает тег0.0.1вместо0.4.1. Ищиnotes_tagпо приоритету переменных: удали лишнийroles/notes/vars/main.yml. - Дополнительно, если Compose падает раньше установки Docker: в
meta/main.ymlролиnotesдопишиdependencies: [{role: docker}]либо переставь роли вsite.yml.
Профилактика: ansible-lint, --syntax-check и --check --diff перед каждым прогоном.
ИИ в помощь
Нейросеть помогает собрать структуру роли и объяснить приоритет переменных, но не знает твой проект и охотно придумывает несуществующие параметры модулей. Общие правила работы с ней: ИИ-помощник.
Задача: превратить длинный плейбук в роль.
Вот мой плейбук на 80 строк: <вставь без паролей>. Разбей его на роль: покажи дерево каталогов и содержимое tasks/main.yml, defaults/main.yml и handlers/main.yml. Значения, которые пользователь захочет менять, положи в defaults.
Проверь ответ: запусти ansible-playbook site.yml --syntax-check и --list-tasks, потом повтори запуск и убедись в changed=0. Типичная ошибка: она кладёт всё в vars/, и значения не удаётся перебить.
Задача: понять, какое значение переменной победит.
Переменная notes_tag задана в defaults роли, в group_vars/all и в host_vars хоста, а запуск идёт с -e. Вот мои файлы: <вставь>. Расположи источники от слабого к сильному и скажи, какое значение применится.
Проверь ответ: сверь с порядком из раздела про приоритет, а потом спроси у Ansible: задача debug с var: notes_tag внутри плейбука. Типичная ошибка: нейросеть считает, что ближе к файлу с задачей значит сильнее.
Задача: проверить, нет ли секретов на виду.
Вот структура моего каталога ansible и содержимое group_vars без значений паролей: <вставь>. Покажи места, где секрет может оказаться в git или в логе, и как это закрыть через vault и no_log.
Проверь ответ: убедись, что пароль vault не в репозитории, а у задачи с паролем стоит no_log: true. Типичная ошибка: она путает ansible-vault и HashiCorp Vault из темы 9.
Словарик урока
| Термин | Простыми словами |
|---|---|
| роль (role) | Папка с заданной структурой для одного дела (Docker, приложение): задачи, шаблоны, значения по умолчанию. |
tasks/main.yml |
Точка входа роли: задачи выполняются сверху вниз. |
defaults/main.yml |
Значения по умолчанию роли; самый слабый приоритет, перебиваются чем угодно. |
vars/main.yml |
Жёсткие значения роли с высоким приоритетом. |
templates/ |
Шаблоны .j2 роли, модуль template берёт их отсюда. |
files/ |
Статичные файлы роли, модуль copy берёт их отсюда. |
meta/main.yml |
Метаданные роли и её зависимости. |
зависимость роли (dependencies) |
Роль, которая выполнится автоматически до текущей. |
group_vars/ |
Переменные для группы серверов; group_vars/all/ для всех. |
host_vars/ |
Переменные для одного сервера. |
| приоритет переменных | Порядок: defaults роли, group_vars, host_vars, vars плейбука, vars роли, -e; сильнее тот, что правее. |
-e (extra vars) |
Значение переменной прямо в команде; побеждает всё. |
debug |
Модуль, который печатает переменную или сообщение; способ увидеть итоговое значение. |
ansible-vault |
Встроенное шифрование файлов Ansible; пароль хранится вне git. |
vault_password_file |
Настройка ansible.cfg: путь к файлу с паролем vault. |
encrypt_string |
Команда vault: зашифровать одну строку для вставки в YAML. |
rekey |
Команда vault: сменить пароль шифрования. |
префикс vault_ |
Соглашение: секрет лежит в vault.yml под именем vault_..., открытый vars.yml ссылается на него. |
no_log |
Параметр задачи: не печатать её параметры и результат в вывод (секрет не попадёт в лог). |
| коллекция (collection) | Пакет дополнительных модулей, ставится на управляющий узел. |
ansible-galaxy |
Инструмент установки ролей и коллекций. |
requirements.yml |
Список коллекций с закреплёнными версиями. |
community.docker.docker_compose_v2 |
Модуль, который поднимает стек Compose идемпотентно. |
deb822_repository |
Модуль подключения apt-репозитория в современном формате (.sources). |
python3-debian |
Библиотека на целевой ВМ, нужная модулю deb822_repository. |
| Jinja2 (подстановка) | Замена {{ ... }} в шаблоне значениями; выполняет Ansible на твоём компьютере. |
--syntax-check |
Проверка структуры плейбука без подключения к серверам. |
--list-tasks |
Печатает список задач в порядке выполнения, ничего не запуская. |
--check --diff |
Сухой прогон: что изменилось бы, по строкам. |
| Molecule | Инструмент автотестов ролей на временной ВМ или контейнере. |
import_role / include_role |
Подключить роль задачей: import_role разворачивается при разборе плейбука, include_role во время выполнения. |
ansible-galaxy init |
Создаёт скелет новой роли с нужными каталогами. |
--vault-id |
Метка у vault-пароля, чтобы в одном проекте работали несколько паролей. |
serial |
Параметр play: выполнять на серверах пачками, а не на всех сразу (см. «Для любопытных» в конце теории). |
healthcheck |
Проверка состояния контейнера: команда, которую Docker запускает по расписанию. |
/healthz, /readyz |
Адреса приложения: /healthz отвечает 200, если процесс жив (базу не проверяет), /readyz отвечает 200, только когда приложение готово работать, в том числе видит БД. |
| FQCN | Полное имя модуля вместе с коллекцией, например ansible.builtin.apt. |
Вопросы с собеседований
Раздел для повторения: ответь вслух, потом открой ответ. Короткие вопросы с пометкой [на скорость] тренируй на время: ответ за 30 секунд.
1. [junior] [часто] Что такое роль в Ansible и зачем она нужна?
Ответ
Роль это каталог с фиксированной структурой (tasks, handlers, templates, defaults), которую можно подключить одной строкой. Я выношу туда повторяющуюся настройку вроде Docker или nginx и использую на разных серверах и проектах. Переменные роли задаю через defaults, чтобы их можно было переопределить.
Что хотят услышать: структура каталогов, defaults против vars, переиспользование, meta и зависимости.
Красный флаг: «это то же самое, что плейбук, только в папке».
2. [junior] [часто] Как хранить пароли в Ansible, чтобы они не попали в git открытым текстом?
Ответ
Через ansible-vault: шифрую файл переменных, пароль от vault держу вне репозитория, в CI он приходит из секретов. В открытом vars.yml только ссылки на vault_*. Задачам с секретами ставлю no_log.
Что хотят услышать: шифрование файла целиком или значения (encrypt_string), пароль вне репозитория, no_log.
Красный флаг: «пароль в .env и добавлен в .gitignore, а на ВМ копируем руками».
3. [middle] Я закоммитил пароль vault в git. Что делаешь?
Ответ
Считаю скомпрометированным и сам vault-файл, и всё, что в нём. Меняю реальные секреты (пароль БД, токены), делаю ansible-vault rekey, убираю файл пароля из репозитория. История git всё помнит, поэтому переписывание истории вторично: главное, что секреты ротированы.
Что хотят услышать: ротация секретов на первом месте, rekey, чистка истории вторым шагом, профилактика (pre-commit, сканер секретов).
Красный флаг: «сделаю git rm и всё».
4. [middle] Роль отработала без ошибок, но приложение на ВМ не поднялось. Как ищешь?
Ответ
Смотрю на ВМ docker compose ps и logs, а не на вывод Ansible: changed не означает «работает». Проверяю, что шаблон отрисовался верно (--check --diff), права на .env и что переменные пришли из нужного места (debug с длиной значения, не с самим секретом). Затем добавляю в роль задачу uri с retries, чтобы такая ошибка ловилась сразу.
Что хотят услышать: проверка результата на цели, debug, --diff, health-check внутри роли.
Красный флаг: «перезапускаю плейбук, пока не заработает».
5. [middle] Переменная задана в трёх местах, а применяется не та. Как разбираешься?
Ответ
Знаю порядок приоритета: defaults роли самые слабые, дальше group_vars, host_vars, vars плейбука, vars роли, -e сильнее всех. Итоговое значение смотрю задачей debug внутри плейбука (ad-hoc ansible -m debug роли не загружает). Ищу лишний -e в CI и vars роли.
Что хотят услышать: порядок приоритетов, способ посмотреть итог, где искать перекрытие.
Красный флаг: «просто задам во всех местах одинаково».
6. [junior] Что значит «идемпотентно» на примере Ansible?
Ответ
Повторный запуск не меняет систему, если она уже в нужном состоянии. Модуль apt с state: present ничего не ставит второй раз, а итог changed=0. Ломают идемпотентность command и shell без creates или changed_when.
Что хотят услышать: пример модуля, признак changed=0, ловушка с shell.
Красный флаг: «идемпотентно значит быстро».
7. [middle] Нужно обновить приложение на 20 серверах без простоя. Как сделаешь через Ansible?
Ответ
Использую serial в плейбуке: обновляю по 1-2 сервера, после каждой пачки проверяю health-check и только затем иду дальше. Ставлю max_fail_percentage, чтобы остановить раскатку при первых ошибках. Серверы выводят из балансировщика на время обновления через delegate_to.
Что хотят услышать: serial, проверка здоровья, остановка при сбое, вывод из балансировки.
Красный флаг: «запущу на всех сразу, Ansible идемпотентный».
8. [middle] Плейбук на проде падает посередине. Что будет с сервером и что делаешь?
Ответ
Ansible не откатывает: выполненные задачи остаются. Смотрю, на какой задаче упал, исправляю причину и запускаю снова: идемпотентность доведёт состояние. Если нужен откат, он должен быть заложен в дизайн: block/rescue или деплой по тегу образа, который можно вернуть.
Что хотят услышать: отсутствие автоотката, безопасность повторного запуска, block/rescue, откат по версии.
Красный флаг: «Ansible сам откатит изменения».
9. [junior] Чем ansible-vault отличается от HashiCorp Vault?
Ответ
ansible-vault шифрует файл и работает только в связке с Ansible, пароль один на файл. HashiCorp Vault это сервис: политики доступа, аудит, динамические секреты. Для одного проекта хватает первого, для команды и множества сервисов нужен второй.
Что хотят услышать: файл против сервиса, аудит и политики, границы применимости.
Красный флаг: «это одно и то же».
10. [middle] Как проверять роли, чтобы не ломать прод?
Ответ
Прогоняю ansible-lint и --syntax-check в CI, затем --check --diff на стенде. Для ролей, которыми пользуются многие, гоняю Molecule (контейнеры или ВМ) и повторный запуск с проверкой changed=0.
Что хотят услышать: lint, check-режим, тестовый стенд, проверка идемпотентности.
Красный флаг: «проверяю сразу на проде, роль же простая».
11. [junior] Чем defaults отличается от vars внутри роли?
Ответ
Это два файла с переменными роли, и отличие в приоритете. defaults/main.yml имеет самый низкий приоритет: это значения по умолчанию, которые пользователь роли должен легко переопределить через inventory, group_vars или -e. vars/main.yml приоритет выше, такие значения переопределить сложнее, поэтому туда кладут внутренние константы роли, которые менять не предполагается. Всё, что может понадобиться настраивать снаружи (порт, версия), я ставлю в defaults, а не в vars, иначе пользователь роли будет бороться с приоритетами.
Что хотят услышать: defaults самый низкий приоритет, vars выше, настраиваемое в defaults, внутреннее в vars.
Красный флаг: класть всё в vars и удивляться, что group_vars не срабатывает.
12. [middle] Как подключить чужие роли и коллекции и зафиксировать их версии?
Ответ
Я описываю зависимости в requirements.yml: название роли или коллекции и версия. Ставлю командой ansible-galaxy install -r requirements.yml, а для коллекций ansible-galaxy collection install -r requirements.yml. Версии закрепляю, чтобы завтрашний релиз чужой роли не поменял поведение прогона. Коллекция - это пакет модулей, плагинов и ролей, а Galaxy - публичный каталог. Перед использованием чужой роли я читаю её задачи: она будет работать с become на моих серверах.
Что хотят услышать: requirements.yml, ansible-galaxy install, фиксация версий, коллекция против роли, проверка чужого кода.
Красный флаг: копировать роль из интернета в репозиторий без чтения и без версии.
Проверено на версиях
- ansible-core 2.21.4 (как в уроках 7.4 и 7.5)
- community.docker: 5.0.0 (закреплена в
requirements.yml) - Docker Engine и Compose-плагин: из apt-репозитория Docker, версия не закреплена, проверь актуальную версию на странице проекта
- PostgreSQL: 18
- «Заметки»: образ 0.4.1
- Ubuntu на ВМ: 26.04 LTS или 24.04 LTS
- Роли целиком (
site.ymlна чистой ВМ, vault, запуск стека Compose) в этой версии урока на ВМ не запускались; синтаксис задач проверенansible-playbook --syntax-checkна ansible-core 2.21.4. ЧислаokвPLAY RECAPпримерные: смотри наchangedиfailed.
Итог урока: ты умеешь
- умею выделить настройку в роль (
tasks,handlers,templates,defaults) - умею закрепить порядок ролей через
meta/main.yml - умею шифровать секреты
ansible-vaultи хранить пароль vault вне репозитория - умею отрисовать
.envс правами 640 из vault и не показать пароль в логе - умею поднять стек Compose модулем
community.docker.docker_compose_v2 - умею смотреть приоритет переменных через
debug - умею проверить плейбук
--check --diff,ansible-lintи повторным запуском
Дальше: Урок 7.7: Terraform + Ansible: конвейер с нуля, drift
Проверь себя
Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.
Тест работает с включённым JavaScript.