devops-курс Все курсы

✻ Урок 7.6 · Тема 7: IaC: Terraform и Ansible

Ansible: роли и деплой «Заметок» одним запуском

⏱ 2 ч

Как работать с кодом и когда идти дальше

Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:

  • Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
  • Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
  • Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.

Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.

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

Зачем это нужно

Плейбук (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 поднимает «Заметки» на ВМ.

Что нужно знать

Картина целиком

Представь небольшой ресторан. Есть должностные инструкции по станциям: «холодный цех», «горячий цех», «раздача». Каждая инструкция лежит в своей папке и описывает свою работу от начала до конца. Это роли. Есть меню на сегодня: какие станции работают и в каком порядке. Это плейбук 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 читается только при первой инициализации тома, у работающей базы пароль не поменяется, и приложение перестанет подключаться. Порядок такой:

  1. Сделай резервную копию: docker compose -f /opt/notes/compose.yml exec -T db pg_dump -U notes notes > notes-backup.sql (проверь, что файл не пустой).
  2. Смени пароль в работающей БД: docker compose -f /opt/notes/compose.yml exec db psql -U notes -d notes, внутри ALTER USER notes PASSWORD '<новый пароль>';.
  3. Впиши новый пароль в vault.yml (ansible-vault edit).
  4. Выкати роль: 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}. Выглядят похоже, но их обрабатывают разные программы в разное время. Если смешать, получишь либо пустое значение, либо ошибку.

Как это устроено:

  1. На твоём компьютере Ansible обрабатывает шаблон compose.yml.j2 шаблонизатором Jinja2 (урок 7.5): всё в двойных фигурных скобках заменяется значениями переменных. Конструкция ${...} для Jinja2 просто текст.
  2. Готовый compose.yml копируется на ВМ.
  3. На ВМ 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, повторный запуск

Роль запускают на десятках серверов, и ошибка размножается. Нужны проверки, которые ловят ошибки до боевого запуска.

От дешёвых проверок к дорогим:

  1. ansible-playbook site.yml --syntax-check: проверка синтаксиса YAML и структуры без подключения к серверам;
  2. ansible-lint: линтер (программа проверки стиля и плохих практик, урок 7.5);
  3. --list-tasks: список задач и порядок, без выполнения;
  4. --check --diff: «сухой прогон», показывающий, что изменилось бы; --diff добавляет построчное сравнение файлов;
  5. боевой запуск на одной тестовой ВМ, затем второй запуск: при правильной роли 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 проверяют состояние и меняют его только при расхождении.

Шаги:

  1. Создай каталоги роли:

    cd ~/notes/infra/ansible
    mkdir -p roles/docker/{tasks,defaults,handlers}
    
  2. 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
    
  3. Перенеси задачи из 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 переезжают в отдельный файл (следующий шаг).

  4. roles/docker/handlers/main.yml:

    - name: Перезапустить docker
      ansible.builtin.systemd_service:
        name: docker
        state: restarted
    
  5. Сохрани прежний 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 их больше не подключает, а их работа переезжает в роли.

  6. Запусти дважды:

    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 и строки шестнадцатеричного текста. Пароля нет.

Шаги:

  1. Сгенерируй пароль 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
    
  2. В ansible.cfg в секцию [defaults] добавь строку:

    vault_password_file = ~/.notes-secrets/ansible-vault-pass
    
  3. Создай открытый файл и шифруемый файл:

    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
    
  4. Проверь, что видно снаружи и что внутри:

    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), доступный всем.

Шаги:

  1. Каталоги и зависимость от роли docker:

    mkdir -p roles/notes/{tasks,defaults,vars,meta,templates}
    cat > roles/notes/meta/main.yml <<'YML'
    # Роль docker выполняется до notes автоматически
    dependencies:
      - role: docker
    YML
    
  2. 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:notes
    

    roles/notes/vars/main.yml: то, что менять снаружи нельзя (порт зашит в образ):

    notes_internal_port: 8080           # на этом порту приложение слушает внутри контейнера
    
  3. 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
    
  4. 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 }}
    
  5. 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:
    
  6. Обнови 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. Шаг проекта: «Заметки» одним запуском на чистой ВМ

Цель: зафиксировать роли в репозитории и проверить полный цикл на чистой ВМ.

Шаги:

  1. Добавь requirements.yml:

    collections:
      - name: community.docker
        version: "5.0.0"
    
  2. Закоммить и запусти на свежей ВМ (пересоздай её или удали контейнеры и /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
    
  3. Проверь снаружи и повторно:

    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; значение пароля в терминал не печатаем, смотрим только длину.

Исправление

Разбор всех сценариев
  1. Неверный пароль vault: проверь vault_password_file в ansible.cfg и файл ~/.notes-secrets/ansible-vault-pass. Если пароль потерян, файл vault.yml пересоздают заново и шифруют новым паролем, а пароль БД меняют в работающей базе (порядок в разделе про Vault).
  2. Шаблон Jinja2 без переменной: найди имя в ошибке 'xxx' is undefined, сверь с defaults/main.yml и group_vars. Обычно опечатка в шаблоне или пропавшая строка в vars.yml.
  3. Переменная перекрыта: ошибки нет, а ansible-playbook site.yml --check --diff показывает тег 0.0.1 вместо 0.4.1. Ищи notes_tag по приоритету переменных: удали лишний roles/notes/vars/main.yml.
  4. Дополнительно, если 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.

тема 7 урок 7.6 2 ч курс 0/0 ← → уроки

Помоги улучшить курс

Что нужно изменить?