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

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

Ansible: плейбуки, handlers и Jinja2

⏱ 3 ч

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

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

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

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

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

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

Ad-hoc команды из прошлого урока хороши для разовой проверки, но настройка сервера это десятки шагов. Представь: поднял новую ВМ и по памяти повторяешь четыре шага, а один забыл.

1. установить Docker
2. создать пользователя notes
3. положить файл настроек
4. перезапустить приложение

Плейбук (playbook) это те же шаги, записанные в текстовый файл: его читает человек, хранит git, запускает CI, а выполняет программа, не ты по памяти. Так на работе ставят Docker, раскладывают конфиги и заводят пользователей.

Шаг проекта: в ~/notes/infra/ansible/ (папку с ansible.cfg и inventory.yml ты создал в уроке 7.4) появляются site.yml (главный файл, который по очереди запускает остальные), каталог playbooks/ (base.yml, docker.yml, config.yml: по одному плейбуку на этап настройки) и шаблон templates/notes.env.j2 (текст файла настроек с «пустыми местами» под значения; расширение .j2 говорит, что он для Jinja2, о ней ниже).

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

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

Ad-hoc команда это устное поручение: «поставь htop». Плейбук это инструкция по обходу объектов на бумаге: пронумерованные шаги, на каких объектах их делать и в каком порядке. Инструкцию можно передать новому сотруднику, проверить, повторить. Эту аналогию я буду держать, пока она работает.

Две новые детали: шаблон Jinja2 (текст конфига с «пустыми местами» {{ имя }}, куда Ansible подставляет значения) и handler (реакция вида «конфиг поменялся, перезапусти сервис»: срабатывает, только когда что-то реально изменилось).

Вот как всё это связано:

flowchart TD
    S["site.yml<br>точка входа: порядок запуска"] --> B["playbooks/base.yml<br>play 1: пакеты, пользователь, каталоги"]
    B --> D["playbooks/docker.yml<br>play 2: репозиторий и Docker"]
    D --> C["playbooks/config.yml<br>play 3: конфиг из шаблона"]
    V["переменные: vars, -e"] --> T["templates/notes.env.j2<br>текст с пустыми местами"]
    C --> T
    T -->|"рендер на твоём компьютере"| F["/etc/notes/notes.env на сервере"]
    F --> Q{"файл изменился?"}
    Q -->|"да"| H["notify: handler<br>один раз в конце play"]
    Q -->|"нет"| K["ok, handler молчит"]

За урок ты разберёшь каждый кусок: из чего состоит плейбук (play, task), как читать его вывод, как работают переменные и шаблоны, когда срабатывает handler, как ограничить запуск и как проверить плейбук до боя.

Теория

Плейбук: play, tasks, модули

Плейбук это YAML-файл, внутри которого список play. Play (в русской документации иногда «игра», мы пишем play) это блок плейбука для группы серверов: «на этих хостах сделай вот это». Действия называются задачами (tasks). Задача вызывает один модуль (урок 7.4) с параметрами и описывает желаемое состояние: state: present значит «пакет должен быть», а не «поставь пакет». Поэтому второй запуск ничего не меняет: модуль сравнивает факт с описанием и молчит, если они совпали.

Вернёмся к инструкции по обходу объектов: плейбук это вся инструкция, play это «какие объекты и что на них делать», task это один пункт обхода, модуль это инструмент, которым пункт выполняется. Модуль пропускает пункт, если работа уже сделана.

- name: Пример                 # имя play: печатается в выводе
  hosts: all                   # к кому применять (группа из инвентаря)
  become: true                 # выполнять от root (sudo) для всего play
  tasks:                       # список задач: выполняются по порядку сверху вниз
    - name: Пакет htop установлен   # имя задачи: по нему читают вывод
      ansible.builtin.apt:          # модуль
        name: htop                  # параметры модуля
        state: present

Разбор. Строка - name: Пример с дефисом начинает элемент списка (один play). hosts: all берётся из инвентаря: all все хосты, notes группа. become: true на уровне play действует на все его задачи, на одну задачу его можно поставить отдельно. tasks список: каждая задача тоже начинается с дефиса. Всегда пиши name: без имени вывод нечитаем, а линтер (программа проверки стиля) ругается.

Порядок. Задачи идут строго по очереди. Если задача упала на хосте, остальные задачи для этого хоста не выполняются. Плейбук со списком play выполняет их одну за другой.

Как читать вывод плейбука. Пример запуска config.yml (реальный, с Ubuntu 24.04):

PLAY [Конфиг Заметок] **********************************************************

TASK [Gathering Facts] *********************************************************
ok: [notes-vm]

TASK [Файл окружения из шаблона] ***********************************************
changed: [notes-vm]

RUNNING HANDLER [Сообщить о смене конфига] *************************************
ok: [notes-vm] => {
    "msg": "Конфиг изменился, приложению нужен перезапуск"
}

PLAY RECAP *********************************************************************
notes-vm                   : ok=3    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
  • PLAY [...] начало play, в скобках её name.
  • TASK [Gathering Facts] служебная задача: Ansible собирает факты (урок 7.4) в начале каждого play сам.
  • ok: [notes-vm] или changed: [notes-vm]: результат задачи на хосте (в скобках имя хоста из инвентаря).
  • RUNNING HANDLER это handler (о нём ниже).
  • PLAY RECAP итоговая таблица по каждому хосту. ok сколько задач отработало (включая changed), changed сколько что-то изменило, failed сколько упало, unreachable до скольких не достучались, skipped сколько пропущено условием. Здесь ok=3: сбор фактов, задача шаблона и handler.

Главный признак здорового плейбука: второй запуск даёт changed=0. Это проверка идемпотентности.

Прикинь сам: В плейбуке три задачи, а вторая упала на хосте notes-vm. Выполнится ли третья на этом хосте?

Нет: задачи идут строго по очереди, и после падения на хосте остальные для него не выполняются. Что было сделано до падения, остаётся на сервере.

Осторожно: ok в итоговой таблице включает changed. Поэтому в recap ok=5 changed=3 значит «пять задач прошли, три из них что-то изменили», а не «пять без изменений».

Главное: плейбук это список play, play связывает хосты с задачами, задача вызывает модуль и описывает желаемое состояние; здоровый плейбук на втором запуске даёт changed=0.

Проверь понимание: чем state: present в модуле apt отличается от команды apt install?

Ответ

apt install это действие: оно каждый раз что-то делает. state: present это описание итога: модуль проверяет, стоит ли пакет, и ставит только при необходимости. Поэтому повторный запуск безопасен и показывает ok, а не changed.

Чтобы не вписывать значения в каждую задачу, их выносят в переменные.

Переменные и Jinja2

Значения, которые меняются (порт, уровень логов, пароль, версия), нельзя вписывать в каждую задачу: изменение придётся искать по десяти файлам. Их выносят в переменные (variables), а в тексте оставляют «пустое место».

Jinja2 (Джинджа) это шаблонизатор: программа, которая берёт текст с пустыми местами и подставляет значения. Пустое место пишется в двойных фигурных скобках: {{ имя }}. Это как письмо с пропусками «Уважаемый {{ имя }}», которое рассылают по списку. Кроме подстановки, в Jinja2 есть фильтры (функции через |, например {{ port | default(8080) }} подставит 8080, если переменная не задана) и писать условия.

Как это работает по шагам:

  1. Ты объявляешь переменную: в vars play, в group_vars, в ключе -e.
  2. Ansible встречает {{ имя }} в параметре задачи или в файле-шаблоне.
  3. Он вычисляет выражение и подставляет значение. Для параметров задач это происходит на управляющей машине, для шаблона тоже: модуль ansible.builtin.template рендерит (собирает готовый текст) файл .j2 на твоём компьютере, а на сервер отправляет готовый текст.
  4. Если переменной нет, Ansible останавливается с ошибкой 'имя' is undefined.

Последнее это защита: лучше упасть, чем молча записать в конфиг пустой пароль. Если пустое значение допустимо, пиши {{ имя | default('') }}.

Кавычки. В YAML значение, которое начинается с {{, обязательно берут в кавычки: path: "{{ item.path }}". Иначе YAML решит, что { начинает словарь, и файл не разберётся (did not find expected key). Внутри строки, где {{ не первый символ, кавычки не нужны, но безопаснее ставить.

Откуда берутся переменные:

  • vars в play: vars: {notes_port: 8080};
  • group_vars/<группа>.yml и host_vars/<хост>.yml рядом с инвентарём (урок 7.4);
  • факты (facts): значения, собранные автоматически, например ansible_facts['distribution_release'] даёт имя релиза Ubuntu (noble для 24.04);
  • ключ -e (extra vars) в командной строке.

Приоритет (упрощённо, от слабого к сильному): значения по умолчанию, group_vars, host_vars, vars в play, параметр -e. Побеждает более сильный источник. -e побеждает всё, поэтому им удобно переопределять значение на один запуск.

flowchart LR
    A["умолчания"] --> B["group_vars"] --> C["host_vars"] --> D["vars в play"] --> E["-e в команде<br>сильнее всех"]

Слева самый слабый источник, справа самый сильный.

Пример: в vars play задано notes_log_level: INFO. В шаблоне строка LOG_LEVEL={{ notes_log_level }}.

Как запустил Что выйдет в файле
ansible-playbook config.yml LOG_LEVEL=INFO (из vars)
ansible-playbook config.yml -e notes_log_level=DEBUG LOG_LEVEL=DEBUG (-e сильнее vars)

Прикинь сам: Ты задал notes_port: 8080 в vars, а запустил с -e notes_port=9090. Какой порт попадёт в шаблон?

9090: ключ -e сильнее всех остальных источников. Но только на этот запуск, следующий без -e вернёт 8080.

Осторожно: -e действует только на этот запуск. Если запустить потом без него, значение вернётся к INFO, и Ansible перезапишет файл обратно. Постоянное изменение делай в файле, а не в -e.

Главное: Jinja2 подставляет значения в {{ имя }}, нет переменной значит ошибка is undefined; приоритет от слабого к сильному: умолчания, group_vars, host_vars, vars, -e.

Теперь посмотрим, как выглядит сам файл шаблона.

Шаблоны: как выглядит файл .j2

Шаблон это обычный текстовый файл с расширением .j2 и пустыми местами. Возьмём наш templates/notes.env.j2:

STORE={{ notes_store }}
LOG_LEVEL={{ notes_log_level }}
DATABASE_URL=postgresql://notes:{{ notes_db_password }}@db:5432/notes

При значениях notes_store: postgres, notes_log_level: INFO, notes_db_password: CHANGE_ME модуль template создаст на сервере:

STORE=postgres
LOG_LEVEL=INFO
DATABASE_URL=postgresql://notes:CHANGE_ME@db:5432/notes

Слева от {{ и справа от }} всё копируется как есть. Каждая строка ключ=значение это формат файла окружения, который читает сервис notes (урок 1.8).

В самом шаблоне Jinja2 умеет и циклы с условиями, нам они не понадобятся: мы пользуемся только подстановкой.

Модуль template идемпотентен: он рендерит текст, сравнивает с файлом на сервере (по контрольной сумме) и переписывает только при отличии. Совпало: ok. Отличается: changed, и вызывается handler. Если в шаблон попадёт что-то, меняющееся при каждом запуске (дата, случайное число), задача будет changed всегда: это частая причина «плейбук не идемпотентен».

Прикинь сам: В шаблон добавили строку UPDATED={{ ansible_facts['date_time']['iso8601'] }}. Что станет со вторым запуском?

Дата меняется каждый раз, поэтому файл каждый раз отличается: задача всегда changed, handler всегда срабатывает.

Главное: модуль template рендерит файл на твоём компьютере, сравнивает по контрольной сумме и переписывает только при отличии.

Когда файл изменился, сервису надо об этом сообщить: для этого нужны handlers.

Handlers: реакция на изменение

После смены конфига сервис нужно перезапустить, чтобы он прочитал новый файл. Но перезапускать при каждом запуске плейбука нельзя: пользователи получат обрывы. Нужно «перезапусти, только если конфиг изменился».

Handler (обработчик) это задача, которая выполняется только если её позвала (notify) другая задача, вернувшая changed. Аналогия: консьерж в доме. Ты оставляешь ему записку «если ремонтники что-то поменяли в подъезде, вызови уборку». Если ремонтники ничего не меняли, консьерж ничего не делает. И уборку он сделает один раз в конце дня, сколько бы записок ему ни оставили.

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

  1. Задача с notify: <имя handler> отрабатывает.
  2. Если её результат changed, Ansible запоминает: этот handler нужно выполнить.
  3. Остальные задачи play продолжают идти.
  4. В конце play запомненные handlers выполняются, каждый по разу.
  5. Если задача вернула ok, handler не запоминается.

Три правила, на которых ломаются:

  1. Handler запускается один раз в конце play, сколько бы задач его ни вызвали.
  2. Если задача вернула ok (файл не менялся), handler не запускается.
  3. Если play упал раньше, накопленные handlers не выполняются (флаг --force-handlers или meta: flush_handlers меняют это).
tasks:
  - name: Конфиг
    ansible.builtin.template:
      src: notes.env.j2
      dest: /etc/notes/notes.env
    notify: Перечитать конфиг       # имя handler: должно совпасть символ в символ
handlers:
  - name: Перечитать конфиг
    ansible.builtin.debug:
      msg: "конфиг изменился"
flowchart TD
    A["задача с шаблоном"] --> Q{"результат changed?"}
    Q -->|"да"| N["notify: Ansible запоминает handler"]
    Q -->|"нет, ok"| X["handler не запоминается"]
    N --> E["конец play: handler выполняется один раз"]

Пример: реальный прогон нашего config.yml, два раза подряд:

Запуск Задача с шаблоном Handler changed в recap
Первый (файла ещё нет) changed выполнился 1
Второй (всё совпало) ok не показан вовсе 0

Во втором запуске в выводе нет блока RUNNING HANDLER: задача вернула ok, и записки для консьержа не было.

Прикинь сам: Три задачи изменили файлы и все вызвали один handler. Сколько раз он выполнится?

Один раз, в конце play. Это защита от трёх перезапусков подряд.

Осторожно: Первое: имя в notify должно совпасть с name handler символ в символ, включая регистр. Если не совпало, Ansible завершает play с The requested handler 'Reload' was not found in either the main handlers list nor in the listening handlers list. Второе: в режиме --check на сервере ничего не меняется. Задача с шаблоном покажет changed (файл изменился бы), а handler появится в выводе как «был бы вызван», но сам перезапуск не выполняется.

Главное: handler выполняется один раз в конце play, и только если вызвавшая его задача вернула changed; имя в notify совпадает с name handler символ в символ.

Проверь понимание: первый запуск обновил файл конфига, но упал на следующей задаче. Ты починил причину и запустил плейбук снова, он прошёл, а сервис со старым конфигом. Что случилось?

Ответ

В первом запуске задача шаблона вернула changed, но play упал раньше конца, и накопленный handler не выполнился. Во втором запуске файл уже совпадает, задача вернула ok, handler не вызывается вовсе. Поэтому перезапуск нужно сделать вручную один раз; а чтобы это не повторялось, ставят meta: flush_handlers сразу после задачи или запускают с --force-handlers.

Остальные приёмы, которые встречаются в каждом плейбуке: циклы, сохранение ответа и условия.

Условия, циклы и register

Три приёма, без которых не обойтись уже в первом задании: цикл, сохранение ответа и условие. Теги разберём ниже, в «Как ограничить запуск».

Цикл loop повторяет задачу для каждого элемента списка. Текущий элемент доступен как item. В задании 1 задача создаёт три каталога: вместо трёх копий одна задача с loop и таблицей значений { path, owner, group, mode }. В выводе каждая итерация видна отдельной строкой changed: [notes-vm] => (item={...}).

register сохраняет ответ модуля в переменную. В задании 2 register: dpkg_arch сохраняет ответ dpkg --print-architecture, и потом {{ dpkg_arch.stdout }} даёт его текст (amd64 или arm64). stdout это поле ответа: то, что напечатала команда.

Отдельно про command и shell: они всегда возвращают changed, потому что Ansible не знает, что сделала команда (урок 7.4). Лечится тремя способами: creates: (пропустить, если файл уже есть), changed_when: false (для команд, которые только читают, как dpkg --print-architecture), либо заменой на специализированный модуль.

Прикинь сам: Задача с command: touch /tmp/flag на втором запуске снова changed. Что добавить?

args: {creates: /tmp/flag}: тогда Ansible увидит файл и пропустит задачу как ok. Лучше заменить command модулем file с state: touch, modification_time: preserve и access_time: preserve (без них время файла обновляется и задача каждый раз changed).

Осторожно: changed_when: false не «отключает» задачу, а заявляет, что она ничего не меняет. Если такая команда что-то меняет, Ansible об этом не скажет.

Условие when. Один и тот же плейбук запускают на разных серверах: на одном Ubuntu 24.04, на другом 22.04, на третьем Docker уже стоит. К задаче дописывается строка when: выражение, и Ansible считает её для каждого хоста отдельно. Истина: задача выполняется. Ложь: хост получает skipped и идёт дальше. Внутри when двойные скобки не нужны, там и так выражение. Условия склеиваются словами and, or, not; несколько строк списком считаются как and.

Пример: репозиторий подключается только на Ubuntu с релизом noble:

- name: Подключить репозиторий Docker
  ansible.builtin.copy:
    content: "deb ... {{ ansible_facts['distribution_release'] }} stable"
    dest: /etc/apt/sources.list.d/docker.list
  when:
    - ansible_facts['distribution'] == 'Ubuntu'
    - ansible_facts['distribution_release'] == 'noble'

В инвентаре две машины: notes-vm (Ubuntu 24.04, noble) и old-vm (Ubuntu 22.04, jammy). Результат:

TASK [Подключить репозиторий Docker] *******************************************
changed: [notes-vm]
skipped: [old-vm]

Для notes-vm оба условия истинны, задача сработала. Для old-vm второе ложно (jammy не равно noble), значит skipped, и в итоговой таблице у него появится skipped=1.

Прикинь сам: У задачи when: ansible_facts['memtotal_mb'] < 1024, на хосте 2048 МБ. Что напечатает Ansible?

skipped: [хост]: выражение ложно. Это не ошибка.

Осторожно: skipped не «сломалось», а честное «условие не выполнено». Ещё не пиши when: "{{ условие }}": в новых версиях (ansible-core 2.19 и выше) это может быть ошибкой, скобки лишние.

Главное: loop повторяет задачу, register сохраняет ответ модуля; changed_when: false заявляет «команда только читает», а не отключает задачу; when считается для каждого хоста отдельно, skipped значит «условие не выполнено».

Теперь заглянем под капот: что стоит за строкой changed: [notes-vm].

Что происходит на сервере во время задачи

Полезно один раз увидеть, что стоит за строкой changed: [notes-vm], потому что от этого зависит, как ты читаешь ошибки. Возьмём задачу «Файл окружения из шаблона» и пройдём её по шагам:

sequenceDiagram
    participant P as твой компьютер
    participant S as сервер notes-vm
    P->>P: 1-2. читает плейбук, подставляет переменные в шаблон
    P->>S: 3. SSH-вход как ubuntu
    P->>S: 4. копирует модуль copy и готовый текст
    P->>S: 5. запускает модуль через sudo
    Note over S: сравнивает контрольные суммы<br>разные: пишет файл, права 0640<br>одинаковые: ничего не трогает
    S-->>P: 6. JSON: changed true или false
    P->>P: 7. если changed, запоминает handler

Отсюда несколько следствий, которые пригодятся при поиске ошибок.

  • Ошибки в шаблоне и переменных (is undefined, кривой YAML) возникают на шагах 1 и 2, ещё на твоём компьютере: до сервера дело не доходит, и сервер остаётся нетронутым.
  • Ошибки входа (UNREACHABLE, Permission denied (publickey)) возникают на шаге 3. Плейбук тут вообще ни при чём.
  • Ошибки прав (are you root?, Missing sudo password) возникают на шаге 5: вход есть, а повысить права нельзя.
  • Ошибки модуля (нет каталога, нет группы) приходят из шага 5 внутри ответа JSON, и Ansible печатает FAILED с текстом.

Так, увидев ошибку, ты сначала определяешь, на каком шаге она случилась, и не ищешь причину не там. Чтобы увидеть шаги подробнее, добавь ключ -v: он печатает больше деталей, а -vvv показывает даже SSH-команды.

Прикинь сам: Ты видишь is undefined и Permission denied (publickey). На каком шаге возникла каждая ошибка?

is undefined на шагах 1-2, ещё на твоём компьютере: сервер не тронут. Permission denied (publickey) на шаге 3, это вход по SSH и к плейбуку отношения не имеет.

Осторожно: «плейбук упал» не значит «сервер в плохом состоянии». Задачи до упавшей уже выполнены и остались применёнными: Ansible не откатывает изменения. Поэтому после падения плейбук просто исправляют и запускают снова: идемпотентные задачи пройдут как ok, а работа продолжится с места ошибки.

Главное: определи, на каком шаге сломалось: шаблон и переменные, вход, права или сам модуль; Ansible не откатывает уже выполненные задачи.

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

become и порядок прав: на каком уровне ставить

become: true можно поставить на трёх уровнях: на весь play, на одну задачу или (реже) в ansible.cfg. Чем выше уровень, тем шире права. Сравни:

- name: Пример уровней
  hosts: all
  # become: true          # вариант 1: на весь play, все задачи от root
  tasks:
    - name: Читаем файл пользователя      # вариант 2: root нужен не везде
      ansible.builtin.command: cat /home/ubuntu/.bashrc
      changed_when: false
    - name: Ставим пакет                  # root только здесь
      ansible.builtin.apt:
        name: htop
        state: present
      become: true

Правило: если почти все задачи меняют систему (как в наших base.yml, docker.yml, config.yml), ставь become: true на play. Если play в основном читает и только один шаг меняет систему, ставь become на эту задачу. Это принцип наименьших привилегий (least privilege): каждому шагу столько прав, сколько ему нужно. Забытый become даёт ошибку Permission denied или are you root? (сценарий 3 ниже), лишний become ошибки не даёт, но расширяет возможный вред при опечатке.

Прикинь сам: В play одна задача меняет систему, остальные только читают. Где ставить become: true?

На саму задачу: каждому шагу столько прав, сколько ему нужно.

Главное: become ставят на play, если почти все задачи меняют систему, и на отдельную задачу, если меняет одна; принцип наименьших привилегий.

Идемпотентность тоже нужно вписать в плейбук, вот чек-лист.

Как писать плейбук, который безопасно запускать снова

Идемпотентность не приходит сама, её нужно «вписать». Короткий чек-лист, по которому ты проверяешь каждую задачу:

  1. Есть ли готовый модуль? apt, user, file, copy, template, systemd_service умеют проверять состояние. Если есть, берёшь его, а не command.
  2. Если нужен command, что сообщит, что работа уже сделана? Добавь creates: (файл, который команда создаёт) или changed_when: false (команда только читает).
  3. Нет ли в шаблоне того, что меняется каждый раз (дата, случайный токен)? Такие значения делают задачу changed при каждом запуске.
  4. Совпадают ли имена в notify и handlers? Иначе плейбук падает.
  5. Второй запуск даёт changed=0? Всегда запускай дважды, пока отлаживаешь. Это самая дешёвая и самая честная проверка.

Разобранный пример. Есть задача:

- name: Создать флаг
  ansible.builtin.command: touch /var/lib/notes/initialized

Первый запуск: changed, файл создан. Второй: снова changed, потому что command не знает, что делает touch. Исправляем: args: {creates: /var/lib/notes/initialized}. Теперь Ansible перед запуском проверяет, есть ли файл: есть, значит задача пропускается с ok, второй запуск даёт changed=0. Можно заменить на модуль file с state: touch, modification_time: preserve и access_time: preserve (без них время файла обновляется и задача каждый раз changed).

Прикинь сам: Плейбук запустили дважды: в первый раз changed=4, во второй changed=1. Что делать?

Найти задачу, которая снова changed: чаще всего это command без creates или шаблон с датой. Пока changed не станет нулём, плейбук не идемпотентен.

Осторожно: сообщение ok не значит «Ansible проверил, что всё хорошо». Оно значит «модуль не нашёл, что менять». Если модуль неправильно определяет состояние (плохой creates), ошибка тихо остаётся.

Главное: всегда запускай плейбук дважды: второй запуск должен давать changed=0; ok значит «менять нечего», а не «всё хорошо».

Когда плейбуков несколько, их собирают в один файл.

import_playbook и site.yml

Когда плейбуков несколько, их не запускают по одному. Файл-точка входа (принято называть site.yml) подключает остальные командой import_playbook в нужном порядке. Это правило верхнего уровня: import_playbook стоит в списке play файла, а не внутри tasks. Пути в нём считаются от каталога самого site.yml.

- import_playbook: playbooks/base.yml     # 1: пакеты, пользователь, каталоги
- import_playbook: playbooks/docker.yml   # 2: Docker
- import_playbook: playbooks/config.yml   # 3: конфиг (ему нужны каталог и группа notes из шага 1)

Порядок важен: третий шаг зависит от первого. Если поменять их местами, шаблон упадёт, потому что каталога /etc/notes и группы notes ещё нет.

Прикинь сам: Что случится, если в site.yml поменять местами base.yml и config.yml?

Шаблон упадёт: каталога /etc/notes и группы notes ещё нет, их создаёт base.yml.

Главное: site.yml подключает плейбуки командой import_playbook в нужном порядке; порядок важен, потому что шаги зависят друг от друга.

Перед боевым запуском плейбук стоит проверить.

Проверка и безопасный запуск

Плейбук на реальной ВМ страшно запускать вслепую. Перед запуском три шага:

  1. ansible-playbook --syntax-check: ловит опечатки в YAML и неверные ключи, никуда не подключаясь.
  2. ansible-lint: линтер (pip install ansible-lint), находит плохие практики: короткие имена модулей без ansible.builtin., command вместо модуля, задачи без имени, относительные пути (на наш src: ../templates/... он ворчит, это допустимо для учебного проекта).
  3. --check --diff: сухой прогон (урок 7.4): показывает, что изменилось бы, и построчную разницу файлов. Ограничение: command и shell в нём пропускаются, поэтому по нему нельзя судить о задачах-командах.

Затем запуск на одном хосте (--limit), потом на остальных.

Главное: три шага перед запуском: --syntax-check, ansible-lint, --check --diff; затем один хост через --limit, потом остальные.

Прикинь сам: Сухой прогон показал changed=0, а после запуска что-то изменилось. Как так вышло?

Изменение сделала задача command или shell: в --check они пропускаются. Или шаг зависел от предыдущего, который в сухом прогоне ничего не сделал.

Когда базовое понятно, добавим к шаблонам фильтры.

Фильтры Jinja2: как подправить значение по дороге в шаблон

Значение переменной не всегда лежит в нужном виде: список надо склеить в одну строку, пустое значение заменить запасным, регистр поменять. Писать для этого отдельные переменные на каждый случай неудобно. Фильтр (filter) это маленькая функция, которая обрабатывает значение прямо в месте подстановки. Пишется через вертикальную черту: {{ значение | фильтр }}.

Значение слева от | передаётся фильтру справа, результат подставляется в текст. Фильтры можно соединять цепочкой слева направо. Самые частые:

Фильтр Что делает Пример и результат
default('x') подставляет запасное, если переменной нет {{ port \| default(8080) }} даёт 8080, если port не задана
upper / lower регистр {{ 'info' \| upper }} даёт INFO
join(', ') склеивает список в строку {{ ['a','b','c'] \| join(', ') }} даёт a, b, c
length длина списка или строки {{ ['a','b','c'] \| length }} даёт 3
int превращает строку в число {{ '8080' \| int }} даёт 8080 как число

Пример: Допустим, в переменных есть notes_hosts: [db1, db2], а notes_log_level не задана. Строки шаблона:

DB_HOSTS={{ notes_hosts | join(',') }}
LOG_LEVEL={{ notes_log_level | default('INFO') | upper }}
DB_COUNT={{ notes_hosts | length }}

Разбор. Первая строка: список [db1, db2] склеен через запятую, получилось db1,db2. Вторая: переменной нет, поэтому default подставил INFO, а upper оставил его заглавными. Третья: в списке два элемента. Итоговый файл на сервере:

DB_HOSTS=db1,db2
LOG_LEVEL=INFO
DB_COUNT=2

Прикинь сам: Что окажется в файле после строки PORTS={{ [80, 443] | join(' ') }}?

PORTS=80 443: список склеен через пробел.

Осторожно: Вертикальная черта здесь не pipe из bash (урок 1.2). Внешне похоже: «передали дальше». Но в bash между программами идёт поток текста, а в Jinja2 значение обрабатывается функцией внутри Ansible. Ещё путают default с пустотой: default('x') срабатывает, если переменная не определена, а пустую строку считает значением. Для пустой строки пишут default('x', true).

Главное: фильтр обрабатывает значение через | прямо в месте подстановки; default срабатывает, только если переменная не определена, а не когда она пустая.

Осталось защитить пароли, которые участвуют в шаблонах.

Секреты в плейбуке: Vault и no_log

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

Для этого есть Ansible Vault: встроенный механизм, который шифрует секрет, чтобы в репозитории лежал только шифртекст. Как им пользоваться (шифрование, пароль от vault, утечка ключа), разберём подробно в уроке 7.6. Пока в шаблоне пароль будет заглушкой CHANGE_ME, зашифруем его в 7.6.

Здесь нужен второй риск, который Vault не закрывает: Ansible печатает в вывод параметры задач, и пароль из шаблона может попасть в лог. Параметр no_log: true у задачи запрещает печатать её параметры и результат, вместо них будет censored.

Пример: Задача с шаблоном, в котором есть пароль БД:

- name: Файл окружения
  ansible.builtin.template:
    src: notes.env.j2
    dest: /etc/notes/notes.env
    mode: "0640"
  no_log: true      # не печатать содержимое и diff: там пароль

Без no_log режим --diff напечатал бы файл с паролем в терминал и в лог CI. С no_log при ошибке ты увидишь censored вместо подробностей, и отлаживать придётся осторожнее: на время отладки no_log временно отключают на тестовом стенде.

Прикинь сам: Задача с шаблоном, в котором есть пароль, упала с --diff в CI. Что окажется в логе без no_log?

Содержимое файла с паролем: --diff печатает разницу файлов, а лог CI видят многие. Поэтому на таких задачах ставят no_log: true.

Осторожно: Vault (урок 7.6) защищает секрет в репозитории, но не на сервере: в /etc/notes/notes.env пароль лежит открытым текстом, и защищают его правами 0640 (урок 1.3). no_log прячет секрет из вывода Ansible, но не из истории shell.

Главное: no_log: true прячет секрет из вывода Ansible; Vault шифрует его в репозитории (7.6); на сервере пароль лежит открытым текстом и защищается правами 0640.

Последнее: как запустить плейбук не целиком, а частично.

Как ограничить запуск: limit, tags и start-at-task

Плейбук на 10 серверов не всегда нужно гнать целиком. Иногда надо обновить конфиг на одной машине, иногда перезапустить с упавшего шага, иногда просто посмотреть список шагов.

Для этого есть четыре ключа, их можно комбинировать. Теги (tags: [config]) это метки, которые ты сам ставишь на задачи: ограничить запуск по тегу, которого нет, нельзя, поэтому расставляй их заранее.

Флаг Что ограничивает Пример
--limit хосты --limit notes-vm запускает только на этом хосте
--tags задачи --tags config выполняет только помеченные tags: [config]
--start-at-task начало --start-at-task "Файл окружения из шаблона" начинает с этой задачи
--list-tasks ничего не запускает печатает список задач, которые выполнились бы

Пример: В инвентаре 10 хостов, плейбук site.yml с тегом config у задачи шаблона. Нужно обновить конфиг только на notes-vm:

ansible-playbook site.yml --limit notes-vm --tags config --check --diff

Разбор. --limit notes-vm сужает хосты с десяти до одного. --tags config оставляет только задачи с тегом config. --check --diff просит сухой прогон (урок 7.4): показать изменения, не применяя. Убедившись, что ожидаемое совпало, убираешь --check --diff и запускаешь по-настоящему. Так из 10 хостов x N задач запускается одна.

Прикинь сам: Нужно узнать, какие задачи пойдут на notes-vm, ничего не запуская. Какие флаги?

ansible-playbook site.yml --limit notes-vm --list-tasks: флаг --list-tasks только печатает задачи.

Осторожно: Тег не ограничивает хосты, а --limit не ограничивает задачи: это разные оси. И ещё: задача без тегов при --tags config не выполнится, даже если от неё зависит следующая. Поэтому теги расставляют осмысленно и после --tags проверяют результат.

Главное: --limit ограничивает хосты, --tags задачи, --start-at-task начало, --list-tasks ничего не запускает; это разные оси.

На проде: проверка конфига и осторожный перезапуск

Для любопытных. В учебном плейбуке handler только печатает сообщение. В боевом он перезапускает сервис, и тут две осторожности.

  • Проверка конфига до замены. У template есть параметр validate (например, validate: nginx -t -c %s): Ansible сначала проверит временный файл этой командой, и битый конфиг не заменит рабочий. Это и есть самый дешёвый «откат»: плохой файл просто не попадает на сервер.
  • Перезапуск Docker. Handler с state: restarted останавливает демон Docker, а без настройки live-restore вместе с ним останавливаются и контейнеры. На нескольких серверах разом это простой всего сервиса, поэтому плейбук катят по одному серверу за раз (коротко в уроке 7.6).

Соответствие AWS

Что делаем в Ansible Аналог в AWS Замечание
Плейбук по SSH AWS Systems Manager Run Command, State Manager SSM ходит через агента, без открытого порта 22
Группа хостов в inventory Теги EC2 и Resource Groups динамический inventory строится по тегам
Шаблон .j2 с параметрами User data (cloud-init) с переменными user data срабатывает при первом старте, Ansible можно запускать повторно
Handler и перезапуск Перезапуск через SSM или замена инстанса в Auto Scaling при immutable-подходе сервер меняют, а не правят

Практика

Везде дальше рабочий каталог ~/notes/infra/ansible/, а inventory.yml и ansible.cfg из урока 7.4 уже настроены. Ansible ставился в venv или pipx: версия ansible-core 2.21.4 (в новом терминале активируй venv: source ~/.venvs/ansible/bin/activate). Целевая машина это ВМ notes-vm (облако или Multipass, Ubuntu 24.04 или 26.04). Плейбуки написаны для hosts: all, чтобы не зависеть от имени группы в твоём инвентаре.

cd ~/notes/infra/ansible
ansible --version | head -1
ansible all -m ansible.builtin.ping
mkdir -p playbooks templates

Разбор. head -1 оставляет первую строку. ansible all -m ...ping проверяет вход на все хосты. mkdir -p создаёт каталоги для плейбуков и шаблонов (-p: без ошибки, если они уже есть).

ansible [core 2.21.4]
notes-vm | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3.12"
    },
    "changed": false,
    "ping": "pong"
}

Как читать вывод: первая строка версия, дальше SUCCESS и pong значит «вход и Python работают». Если видишь UNREACHABLE, вернись в урок 7.4.

Задание 1. Первый плейбук: база сервера и идемпотентность

Цель: описать плейбуком пакеты, системного пользователя notes и каталоги «Заметок» и убедиться, что повторный запуск ничего не меняет.

Предскажи: что покажет PLAY RECAP при первом запуске и при втором? Сколько задач будут changed во второй раз?

Ответ

Первый запуск: changed равен числу задач, которые что-то создали (пакеты, пользователь, каталоги). Второй: changed=0, все задачи ok. Если во втором запуске changed не ноль, в плейбуке есть неидемпотентная задача.

Шаги:

  1. Создай playbooks/base.yml:
- name: Базовая настройка сервера для Заметок
  hosts: all
  become: true          # без этого apt и useradd упадут: нужен root
  tasks:
    - name: Индекс пакетов свежий
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600   # не чаще раза в час

    - name: Базовые пакеты установлены
      ansible.builtin.apt:
        name:
          - ca-certificates
          - curl
          - jq
        state: present

    - name: Системный пользователь notes существует
      ansible.builtin.user:
        name: notes
        system: true
        shell: /usr/sbin/nologin
        create_home: false

    - name: Каталоги Заметок созданы
      ansible.builtin.file:
        path: "{{ item.path }}"
        state: directory
        owner: "{{ item.owner }}"
        group: "{{ item.group }}"
        mode: "{{ item.mode }}"
      loop:
        - { path: /opt/notes, owner: root, group: root, mode: "0755" }
        - { path: /var/lib/notes, owner: notes, group: notes, mode: "0750" }
        - { path: /etc/notes, owner: root, group: notes, mode: "0750" }

Разбор по задачам. Индекс пакетов: update_cache обновляет список доступных пакетов (аналог apt update), cache_valid_time: 3600 не ходить за индексом в сеть, если обновляли меньше часа (3600 секунд) назад. Пакеты: name со списком ставит все три за один вызов apt. ca-certificates нужен для HTTPS, curl для запросов, jq для разбора JSON. Пользователь: system: true создаёт системную учётную запись (для служб, а не для людей), shell: /usr/sbin/nologin запрещает вход в неё, create_home: false не создаёт домашний каталог. Каталоги: loop берёт три строки из списка, и на каждой item.path, item.owner и остальные поля подставляются в параметры. Запись { path: ..., owner: ... } это словарь в одну строку. Режим "0750" в кавычках, иначе YAML прочитает его как число.

  1. Проверь синтаксис и запусти дважды:
ansible-playbook playbooks/base.yml --syntax-check
ansible-playbook playbooks/base.yml
ansible-playbook playbooks/base.yml

Что должно получиться: первый запуск на свежей ВМ (фрагмент; если пакеты уже стоят, changed будет меньше):

TASK [Каталоги Заметок созданы] ************************************************
changed: [notes-vm] => (item={'path': '/opt/notes', 'owner': 'root', 'group': 'root', 'mode': '0755'})
changed: [notes-vm] => (item={'path': '/var/lib/notes', 'owner': 'notes', 'group': 'notes', 'mode': '0750'})
changed: [notes-vm] => (item={'path': '/etc/notes', 'owner': 'root', 'group': 'notes', 'mode': '0750'})

PLAY RECAP *********************************************************************
notes-vm                   : ok=5    changed=3    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

В конце второго запуска:

PLAY RECAP *********************************************************************
notes-vm                   : ok=5    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

ИИ: если плейбук упал с непонятной ошибкой, вставь нейросети текст ошибки и задачу (без паролей). Предложенную правку сначала проверь через --syntax-check и --check --diff, потом запускай.

Как читать вывод: ok=5 это сбор фактов плюс четыре задачи. На свежей ВМ в первом запуске changed дают пакеты, пользователь и каталоги: это changed=3, как в примере выше (индекс пакетов в нём получился ok, потому что кэш apt на только что созданной ВМ ещё свежий). Если кэш старый, индекс тоже обновится, и будет changed=4. Во втором запуске все задачи ok, changed=0: идемпотентность подтверждена.

Объясни себе:

  • Зачем у apt стоит cache_valid_time, и что было бы без него?
  • Что делает loop и откуда берётся item?
  • Почему пользователь notes создан без домашнего каталога и с nologin?

Типичные ошибки:

  • Task failed: Missing sudo password (в старых версиях FAILED! => {"msg": "Missing sudo password"}): у пользователя ВМ нет NOPASSWD в sudo, а become включён. Настрой sudo без пароля или запусти с --ask-become-pass.
  • E: Could not get lock /var/lib/dpkg/lock-frontend: на свежей ВМ фоном идёт unattended-upgrades (автообновления). Подожди пару минут и повтори.
  • [ERROR]: YAML parsing failed: Tabs are usually invalid in YAML.: отступы пробелами, табы в YAML запрещены.

Задание 2. Docker из официального apt-репозитория

Цель: поставить Docker Engine на ВМ так, как это делают в проде: ключ, репозиторий с проверкой подписи, пакеты, автозапуск.

Что здесь нового. В Ubuntu есть пакет docker.io, но без Compose-плагина v2 и со своим циклом обновлений. Мы берём docker-ce из репозитория Docker, как в уроке 7.4 и теме про контейнеры: репозиторий это адрес, откуда apt берёт пакеты. Чтобы apt доверял ему, скачиваем GPG-ключ (файл, которым Docker подписывает пакеты: apt проверяет подпись и отбрасывает подделки). Ключ привязываем к одному репозиторию параметром signed_by: так он не станет доверенным для всех источников сразу. Репозиторий подключаем модулем deb822_repository: он пишет файл /etc/apt/sources.list.d/docker.sources в современном формате. Старый apt_repository вытесняется им, признаки устаревания смотри в своей версии (ansible-doc ansible.builtin.apt_repository).

Предскажи: какие факты нужны, чтобы собрать описание репозитория для Ubuntu 24.04 (noble) и 26.04 одним плейбуком?

Ответ

Архитектура процессора (amd64 или arm64) и кодовое имя релиза. Оба даёт сбор фактов: ansible_facts['architecture'] (значения x86_64 и aarch64, поэтому нужна таблица соответствия) и ansible_facts['distribution_release']. Здесь архитектуру берём готовой командой dpkg --print-architecture.

Шаги:

  1. Создай playbooks/docker.yml:
- name: Docker Engine на сервере
  hosts: all
  become: true
  tasks:
    - name: Каталог для ключей apt
      ansible.builtin.file:
        path: /etc/apt/keyrings
        state: directory
        mode: "0755"

    - name: Ключ репозитория Docker скачан
      ansible.builtin.get_url:
        url: https://download.docker.com/linux/ubuntu/gpg
        dest: /etc/apt/keyrings/docker.asc
        mode: "0644"

    - name: Пакет python3-debian для модуля deb822_repository
      ansible.builtin.apt:
        name: python3-debian
        state: present

    - name: Архитектура dpkg
      ansible.builtin.command: dpkg --print-architecture
      register: dpkg_arch
      changed_when: false      # команда только читает, изменений нет
      check_mode: false        # читает и в сухом прогоне, иначе --check упадёт ниже

    - name: Репозиторий Docker подключён
      ansible.builtin.deb822_repository:
        name: docker
        types: deb
        uris: https://download.docker.com/linux/ubuntu
        suites: "{{ ansible_facts['distribution_release'] }}"
        components: stable
        architectures: "{{ dpkg_arch.stdout }}"
        signed_by: /etc/apt/keyrings/docker.asc
        state: present
        enabled: true

    - name: Пакеты Docker установлены
      ansible.builtin.apt:
        name:
          - docker-ce
          - docker-ce-cli
          - containerd.io
          - docker-compose-plugin
        state: present
        update_cache: true
      notify: Перезапустить Docker

    - name: Docker включён и запущен
      ansible.builtin.systemd_service:
        name: docker
        state: started
        enabled: true

  handlers:
    - name: Перезапустить Docker
      ansible.builtin.systemd_service:
        name: docker
        state: restarted

Разбор. /etc/apt/keyrings/ стандартное место для ключей сторонних репозиториев. get_url скачивает файл по адресу. python3-debian нужен самому модулю deb822_repository на целевой машине (модули это Python-программы, им нужны библиотеки). register: dpkg_arch сохраняет вывод команды в переменную, changed_when: false объясняет Ansible, что команда ничего не меняет. check_mode: false говорит выполнять задачу даже при --check: команда только читает, а без неё dpkg_arch в сухом прогоне останется пустым. (Архитектуру можно взять и из ansible_facts['architecture'], но тогда нужна таблица x86_64 в amd64.) В deb822_repository: suites это кодовое имя релиза (noble), signed_by указывает apt, каким ключом проверять именно этот репозиторий. notify у установки пакетов вызывает handler «Перезапустить Docker», и он выполнится в конце play, только если пакеты реально ставились. systemd_service с state: started и enabled: true запускает Docker сейчас и включает его автозапуск при загрузке (урок 1.8).

  1. Запусти два раза и проверь на ВМ:
ansible-playbook playbooks/docker.yml
ansible-playbook playbooks/docker.yml
ansible all -m ansible.builtin.command -a "docker compose version" --become

Что должно получиться: второй запуск с changed=0, в конце версия плагина Compose. Число версии зависит от даты установки (версия Docker не закреплена):

notes-vm | CHANGED | rc=0 >>
Docker Compose version v<версия>

Как читать вывод: CHANGED | rc=0 для command нормально: command всегда пишет CHANGED, а rc=0 значит, что команда завершилась успешно (урок 7.4). Если Docker не запустился, здесь будет ошибка.

Объясни себе:

  • Зачем changed_when: false у задачи с dpkg, и что покажет второй запуск без него?
  • В каком порядке выполнятся задача установки и handler, и когда именно?
  • Почему ключ лежит в /etc/apt/keyrings/, а репозиторий ссылается на него через signed_by?

Типичные ошибки:

  • E: The repository ... does not have a Release file: у Docker может не быть репозитория для только что вышедшего релиза Ubuntu. Проверь curl -I https://download.docker.com/linux/ubuntu/dists/<релиз>/Release; при 404 подставь предыдущий LTS в suites (актуальную поддержку смотри на странице Docker).
  • Error while resolving value for 'architectures': 'dpkg_arch' is undefined (в начале строки Task failed: Finalization of task args for 'ansible.builtin.deb822_repository' failed:): задача с register не выполнилась раньше или переименована: имена в register и в шаблоне должны совпадать.
  • Could not resolve host: download.docker.com: у ВМ нет выхода в интернет или DNS. Проверь dig download.docker.com (урок 2.3).
  • [DEPRECATION WARNING]: ansible.builtin.apt_repository has been deprecated: так предупреждает старый модуль, если взять его из чужих примеров. Замени на deb822_repository, как здесь.

Задание 3. Шаблон Jinja2 и handler на конфиг

Цель: сгенерировать /etc/notes/notes.env из шаблона, выдать права 640 root:notes и вызвать handler только при реальном изменении.

Предскажи: ты меняешь в плейбуке только notes_log_level с INFO на DEBUG и запускаешь. Что покажет задача с шаблоном и выполнится ли handler? А если запустить ещё раз?

Ответ

Первый запуск: задача changed, handler выполнится. Второй: задача ok, handler пропущен, потому что нечего перечитывать.

Шаги:

  1. Создай templates/notes.env.j2:
# Файл создан Ansible, не правь руками: изменения перезапишутся
STORE={{ notes_store }}
HOST=127.0.0.1
PORT=8080
LOG_LEVEL={{ notes_log_level }}
DATABASE_URL=postgresql://notes:{{ notes_db_password }}@db:5432/notes
  1. Создай playbooks/config.yml. Пароль в шаблоне пока заглушка CHANGE_ME, зашифруем его в уроке 7.6:
- name: Конфиг Заметок
  hosts: all
  become: true
  vars:
    notes_store: postgres
    notes_log_level: INFO
    notes_db_password: CHANGE_ME
  tasks:
    - name: Файл окружения из шаблона
      ansible.builtin.template:
        src: ../templates/notes.env.j2
        dest: /etc/notes/notes.env
        owner: root
        group: notes
        mode: "0640"
      notify: Сообщить о смене конфига
      tags: [config]

  handlers:
    - name: Сообщить о смене конфига
      ansible.builtin.debug:
        msg: "Конфиг изменился, приложению нужен перезапуск"

Разбор. vars задаёт три переменные, которые подставятся в шаблон. src путь к шаблону (.. значит «на уровень выше каталога playbooks/»), dest куда положить готовый файл, owner, group, mode владелец и права. Режим 0640: владелец root читает и пишет, группа notes читает, остальные ничего (урок 1.3). Так сервис notes прочитает пароль, а посторонние пользователи нет. debug это модуль, который просто печатает сообщение: в учебном плейбуке он показывает, что handler сработал (в боевом здесь был бы перезапуск сервиса).

  1. Запусти, потом покажи разницу и права:
ansible-playbook playbooks/config.yml
ansible-playbook playbooks/config.yml -e notes_log_level=DEBUG --check --diff
ansible all -m ansible.builtin.command -a "stat -c '%a %U:%G %n' /etc/notes/notes.env" --become

Разбор. -e notes_log_level=DEBUG подменяет переменную только для этого запуска. stat -c '%a %U:%G %n' печатает права числом, владельца, группу и имя файла.

Что должно получиться: --diff показывает одну изменённую строку, права правильные (путь в строке +++ after у тебя будет другой, это временный файл):

--- before: /etc/notes/notes.env
+++ after: /home/ubuntu/.ansible/tmp/.../notes.env.j2
@@ -2,5 +2,5 @@
 STORE=postgres
 HOST=127.0.0.1
 PORT=8080
-LOG_LEVEL=INFO
+LOG_LEVEL=DEBUG
 DATABASE_URL=postgresql://notes:CHANGE_ME@db:5432/notes

changed: [notes-vm]
...
notes-vm | CHANGED | rc=0 >>
640 root:notes /etc/notes/notes.env

ИИ: шаблон .j2 можно попросить написать по готовому файлу, но пароли из него убери заранее и сверь список переменных с твоими vars.

Как читать вывод: - строка, которая исчезнет, + строка, которая появится, строки без знака остались как были. @@ -2,5 +2,5 @@ значит «показаны 5 строк, начиная со второй». Заметь, что changed видно даже при --check: Ansible показывает, что было бы, файл при этом не меняется. Handler в этом режиме тоже появится в выводе (в нашем учебном плейбуке он просто печатает сообщение, поэтому выполнится), а настоящий перезапуск сервиса в сухом прогоне не выполняется. Фрагмент вывода:

RUNNING HANDLER [Сообщить о смене конфига] *************************************
ok: [notes-vm] => {
    "msg": "Конфиг изменился, приложению нужен перезапуск"
}

Запусти ansible-playbook playbooks/config.yml без -e ещё раз: задача будет ok, блока RUNNING HANDLER не будет.

Объясни себе:

  • Где рендерится шаблон: на ВМ или на твоей машине?
  • Почему -e notes_log_level=DEBUG победил значение из vars?
  • Почему файл с паролем нельзя оставить 644? (урок 1.3)

Типичные ошибки:

  • Task failed: 'notes_store' is undefined (в блоке Origin будет путь к templates/notes.env.j2): переменная не определена ни в vars, ни в group_vars. Определи её или задай значение по умолчанию {{ notes_store | default('postgres') }}.
  • Could not find or access '../templates/notes.env.j2': путь src считается от каталога плейбука: проверь, что шаблон лежит в infra/ansible/templates/, а плейбук в infra/ansible/playbooks/; из какого каталога ты запускаешь, не важно.
  • did not find expected key while parsing a block mapping: значение с {{ в начале не взято в кавычки.

Задание 4. Шаг проекта: site.yml собирает всё

Итоговый site.yml собери по образцу из плейбуков, которые уже проверил отдельно. У каждой задачи нужно понимать требуемое состояние, используемый модуль и причину запуска handler; параметры модулей можно сверять с ansible-doc. Повторный запуск без лишних изменений покажет, что получилась воспроизводимая настройка.

Цель: оформить infra/ansible/site.yml точкой входа, которая подключает три плейбука по порядку, и получить changed=0 при втором запуске на настроенной ВМ.

Предскажи: что будет, если site.yml подключит config.yml раньше base.yml?

Ответ

Задача шаблона упадёт: каталога /etc/notes и группы notes ещё нет, template вернёт ошибку про несуществующую группу или каталог. Порядок import_playbook задаёт порядок выполнения.

Шаги:

  1. Создай site.yml:
# Точка входа: порядок важен, каждый шаг опирается на предыдущий
- import_playbook: playbooks/base.yml
- import_playbook: playbooks/docker.yml
- import_playbook: playbooks/config.yml
  1. Проверь линтером, сделай сухой прогон и запусти дважды. Затем ограничь запуск одним тегом:
source ~/.venvs/ansible/bin/activate && pip install ansible-lint && ansible-lint playbooks/
ansible-playbook site.yml --syntax-check
ansible-playbook site.yml --check --diff
ansible-playbook site.yml
ansible-playbook site.yml
ansible-playbook site.yml --tags config
  1. Зафиксируй в git:
cd ~/notes
git add infra/ansible
git commit -m "ansible: site.yml, playbooks base/docker/config, шаблон notes.env"

Что должно получиться: ansible-lint у меня нашёл одно замечание, на src: ../templates/notes.env.j2, это правило no-relative-paths. Для учебной структуры его можно оставить; в проекте с CI линтер запускают на каждый pull request, и такие замечания либо чинят, либо осознанно отключают. Во втором полном запуске везде changed=0; с --tags config выполняется только задача шаблона (и сбор фактов):

PLAY RECAP *********************************************************************
notes-vm                   : ok=15   changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

Как читать вывод: число ok зависит от версии Ansible, ролей и фактов (у тебя может отличаться), смотри на changed и failed: должны быть нули. Сухой прогон --check на чистой ВМ может упасть на шагах, которые зависят от ещё не сделанных (например, config.yml без каталога): это ограничение check-режима, а не ошибка плейбука. Список задач под тегом можно посмотреть без запуска: ansible-playbook site.yml --tags config --list-tasks.

Объясни себе:

  • Чем import_playbook отличается от трёх запусков вручную?
  • Что даёт --tags, и почему теги нужно ставить заранее?

Типичные ошибки:

  • Task failed: Action 'ansible.builtin.import_playbook' does not support raw params.: import_playbook записан внутри списка tasks:, а должен стоять на верхнем уровне файла.
  • [ERROR]: Unable to retrieve file contents. Could not find or access '.../playbooks/base.yml' on the Ansible Controller: неверный путь: пути в import_playbook считаются от каталога site.yml.
  • UNREACHABLE!: изменился IP ВМ после пересоздания: обнови NOTES_VM_IP или inventory.yml (урок 7.4).

Сломай и почини

Скрипта поломки для этого урока нет: ты ломаешь плейбук руками. Каждый сценарий это маленький отдельный плейбук в каталоге /tmp/b5/, чтобы не портить рабочие файлы. Подготовка:

mkdir -p /tmp/b5 && cd /tmp/b5
cp ~/notes/infra/ansible/ansible.cfg ~/notes/infra/ansible/inventory.yml .

Симптом

Четыре картины:

  1. второй запуск показывает changed=1 на одной и той же задаче;
  2. запуск падает с 'foo' is undefined;
  3. задача падает с Permission denied или are you root?;
  4. конфиг изменился (или должен был), а handler не отработал, либо play падает с The requested handler ... was not found.

Воспроизведи по очереди:

# 1. command без creates: всегда changed
cat > s1.yml <<'EOF'
- name: сценарий 1
  hosts: all
  tasks:
    - name: создать флаг
      ansible.builtin.command: touch /tmp/flag-b5
EOF
ansible-playbook s1.yml; ansible-playbook s1.yml

# 2. переменная не определена
cat > s2.yml <<'EOF'
- name: сценарий 2
  hosts: all
  tasks:
    - name: печать
      ansible.builtin.debug:
        msg: "{{ foo }}"
EOF
ansible-playbook s2.yml

# 3. забыт become: apt без прав root
cat > s3.yml <<'EOF'
- name: сценарий 3
  hosts: all
  tasks:
    - name: пакет
      ansible.builtin.apt:
        name: cowsay
        state: present
EOF
ansible-playbook s3.yml

# 4. имя в notify не совпадает с именем handler
cat > s4.yml <<'EOF'
- name: сценарий 4
  hosts: all
  become: true
  tasks:
    - name: конфиг
      ansible.builtin.copy:
        content: "x"
        dest: /tmp/cfg-b5
      notify: Reload
  handlers:
    - name: reload
      ansible.builtin.debug:
        msg: "сработал"
EOF
ansible-playbook s4.yml

Гипотезы

Для каждого симптома выпиши по 2 причины до просмотра разбора. Подумай: что в задаче не идемпотентно; где определяется переменная; на каком уровне стоит become; как называется handler и вызывался ли он.

Проверки

Запускай ansible-playbook файл.yml --check --diff и -v: они показывают, что меняется и что вернул модуль. Для переменной поищи её определение: grep -rn foo .. Для handler сравни две строки: notify: и name: в блоке handlers.

Исправление

Разбор сценариев
  1. changed=1 каждый раз: в плейбуке command без creates, removes или changed_when. В recap второго запуска будет changed=1. Замени на модуль (file с state: touch, modification_time: preserve и access_time: preserve, copy, get_url) или добавь args: {creates: /tmp/flag-b5}. Проверка: второй запуск даёт changed=0.
  2. 'foo' is undefined: текст Error while resolving value for 'msg': 'foo' is undefined. Переменная не задана или опечатка в имени. Ищи grep -rn foo ., определи в vars или group_vars, либо задай {{ foo | default('значение') }}, если пустое допустимо.
  3. Забыт become: true: текст E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied) и E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), are you root?. Модуль apt, user или запись в /etc выполняется от обычного пользователя. Добавь become: true в play или в задачу. Пакет должен быть не установлен (перед запуском проверь dpkg -l cowsay): если он уже стоит, модуль apt ничего не запускает и ошибки не будет.
  4. Имя в notify (Reload) не совпадает с name handler (reload), регистр важен. Текст: The requested handler 'Reload' was not found in either the main handlers list nor in the listening handlers list. Выровняй имена. Если имя верное, а handler всё равно не сработал, значит задача вернула ok (файл уже совпадал) или play упал до конца: тогда добавь meta: flush_handlers сразу после нужной задачи.

Убери за собой: rm -rf /tmp/b5 и на ВМ ansible all -m ansible.builtin.file -a "path=/tmp/flag-b5 state=absent".

ИИ в помощь

Нейросеть хорошо пишет шаблоны .j2 и объясняет вывод PLAY RECAP, но не видит твой сервер, поэтому перепроверяй имена модулей и параметры. Общие правила работы с ней: ИИ-помощник.

Задача: найти, почему плейбук неидемпотентен.

Мой плейбук на втором запуске показывает changed=2. Вот задачи: <вставь YAML без секретов> и вывод PLAY RECAP. Найди задачи, которые всегда changed, и предложи исправление: готовый модуль или creates, или changed_when.

Проверь ответ: сам запусти исправленный плейбук дважды: второй запуск должен дать changed=0. Типичная ошибка: нейросеть ставит changed_when: false на задачу, которая на самом деле меняет систему.

Задача: написать шаблон .j2 по готовому файлу настроек.

Вот файл /etc/notes/notes.env: <вставь без реальных паролей>. Сделай из него шаблон notes.env.j2 с переменными в двойных фигурных скобках и перечисли переменные, которые нужно задать. Пароль не вписывай, он придёт из Vault.

Проверь ответ: сверь список переменных с vars и group_vars: любой пропуск даст is undefined. Типичная ошибка: она оставляет пароль в шаблоне открытым текстом.

Задача: разобрать ошибку handler.

Плейбук падает с The requested handler was not found. Вот задача с notify и блок handlers: <вставь>. Объясни причину.

Проверь ответ: имя в notify и name у handler должны совпасть символ в символ, включая регистр. Типичная ошибка: нейросеть советует переименовать модуль вместо исправления имени.

Словарик урока

Термин Простыми словами
Плейбук (playbook) YAML-файл со списком play: инструкция, что и на каких серверах сделать
play Часть плейбука: группа хостов плюс список задач для неё
Задача (task) Один вызов модуля с параметрами
PLAY RECAP Итоговая таблица запуска: ok, changed, failed по каждому хосту
Переменная (variable) Именованное значение, которое подставляется в задачи и шаблоны
-e (extra vars) Значение переменной из командной строки, сильнее всех остальных источников
Jinja2 Шаблонизатор: подставляет значения в {{ ... }} и умеет условия и циклы
Шаблон (.j2) Текстовый файл с пустыми местами, из которого Ansible делает готовый конфиг
Рендер (render) Сборка готового текста из шаблона и значений переменных
Handler Задача-обработчик, которая срабатывает по notify, только если задача изменила что-то
notify «Позови этот handler, если я вернула changed»
register Сохранить ответ модуля в переменную
loop / item Повторить задачу для каждого элемента списка; item текущий элемент
changed_when Явно сказать Ansible, считать ли задачу изменившей что-то
check_mode: false Выполнять задачу даже при --check (годится для команд, которые только читают)
import_playbook Подключение другого плейбука по порядку из site.yml
Фильтр Jinja2 (filter) Функция в {{ значение \| фильтр }}, которая обрабатывает значение: default, upper, join, length
when Условие у задачи: ложь даёт skipped, истина выполняет задачу
skipped Задача пропущена, потому что условие when ложно (не ошибка)
Ansible Vault Встроенное шифрование значений, чтобы хранить секреты в git (разбираем в 7.6)
no_log Параметр задачи: не печатать её параметры и результат, чтобы секрет не попал в лог
--limit, --tags, --start-at-task Запустить плейбук только на части хостов, только помеченные задачи или с нужной задачи
Тег (tag) Метка на задаче, чтобы запускать только помеченные (--tags)
GPG-ключ репозитория Файл, которым apt проверяет подпись пакетов
ansible-lint Программа проверки плейбука на плохие практики

Вопросы с собеседований

Раздел для повторения: ответь вслух, потом открой ответ. Короткие вопросы с пометкой [на скорость] тренируй на время: ответ за 30 секунд.

1. [junior] [часто] Ты запускаешь плейбук второй раз, и он показывает changed=3. Твои действия?

Ответ

Смотрю, какие именно задачи changed. Обычно это command или shell без creates, removes или changed_when, либо шаблон с меняющимся содержимым (метка времени внутри). Заменяю на модуль или добавляю условия, проверяю --check --diff.

Что хотят услышать: идемпотентность как критерий качества, поиск по PLAY RECAP, --diff, changed_when.

Красный флаг: «так и должно быть» или «просто игнорирую».

2. [junior] [часто] В плейбуке ты поменял конфиг nginx, но сервис не перезапустился. Почему?

Ответ

Проверю три вещи: есть ли notify у задачи, совпадает ли имя с name handler, и вернула ли задача changed. Если файл уже был таким, handler не вызывается. Ещё смотрю, не упал ли play до конца.

Что хотят услышать: handler запускается в конце play, только при changed, flush_handlers, --force-handlers.

Красный флаг: считает, что handler запускается при каждом запуске.

3. [junior] Что делает become: true и на каком уровне его лучше ставить?

Ответ

Повышает привилегии до root через sudo. Ставлю на play, если почти все задачи требуют root, и на задачу, если нужен один шаг: так остальное идёт с минимумом прав.

Что хотят услышать: sudo, become_user, минимальные права, NOPASSWD только для автоматизации.

Красный флаг: запускает всё ansible_user: root.

4. [junior] Плейбук падает с 'db_host' is undefined. Как ищешь?

Ответ

grep -rn db_host по плейбукам, шаблонам и group_vars. Проверяю имя (опечатка), область видимости (vars play или inventory) и приоритет. Отладка: ansible -m debug -a "var=db_host" хост.

Что хотят услышать: источники переменных, приоритет, debug, default() там, где пусто допустимо.

Красный флаг: «добавлю ignore_errors: true».

5. [middle] Плейбук на проде страшно запускать. Как снижаешь риск?

Ответ

--syntax-check, ansible-lint, затем --check --diff на одном хосте (--limit), потом по одному-двум хостам, потом на всех. Помню, что command в check пропускается, и проверяю такие места вручную.

Что хотят услышать: --check --diff, --limit, постепенный раскат, ограничения check, git-ревью.

Красный флаг: «запускаю сразу на всех, откатим».

6. [middle] [углублённо] После смены конфига нужно перезапустить сервис, но только если конфиг проходит проверку. Как сделать?

Ответ

В модуле template есть параметр validate (например, nginx -t -c %s, где %s подменяется путём к временному файлу): Ansible сначала проверяет временный файл этой командой, и невалидный файл не заменит рабочий. Перезапуск делаю через notify, чтобы он был только при изменении.

Что хотят услышать: validate, notify, reload против restart, откат при ошибке.

Красный флаг: пишет конфиг, потом отдельной command проверяет и не останавливает play при ошибке.

7. [middle] Как передать секрет в плейбук и не засветить его в логах и git?

Ответ

Не хранить в открытом виде: ansible-vault (шифрование файла с переменными; в учебном плейбуке пароль в шаблоне пока заглушка, зашифруем в 7.6) или внешний менеджер секретов. На задачах с секретом ставлю no_log: true, чтобы значение не попало в вывод.

Что хотят услышать: vault, no_log, секрет не в -e из истории shell, не в git.

Красный флаг: пароль в vars плейбука в репозитории.

8. [middle] Нужно пересоздать конфиг только на одной ВМ из десяти, а не гонять весь плейбук. Как?

Ответ

--limit host для хоста и --tags config для задач. Заранее размечаю задачи тегами, иначе ограничить нечем.

Что хотят услышать: --limit, --tags, --start-at-task, --list-tasks.

Красный флаг: правит плейбук, комментируя задачи.

9. [middle] [углублённо] Ты подставляешь в шаблон список серверов, а в файле пустые строки. Что не так?

Ответ

Скорее всего, лишние переводы строк от блоков {% for %}. Помогают trim_blocks (убирает перевод строки сразу после тега блока; в модуле template включён по умолчанию) и lstrip_blocks: true (убирает пробелы и табы перед тегом блока; по умолчанию выключен, включается параметром модуля) или знак - в тегах Jinja2 ({%- ... -%}). Проверяю результат --diff.

Что хотят услышать: циклы Jinja2, управление пробелами, --diff для проверки, отладка шаблона.

Красный флаг: правит файл на сервере руками после запуска.

10. [middle] [углублённо] Чем include_tasks отличается от import_tasks?

Ответ

import_tasks статический: файл разворачивается при разборе плейбука, задачи видны заранее, а теги и условия применяются к каждой задаче внутри. include_tasks динамический: файл подключается во время выполнения, поэтому имя файла можно собрать из переменной, а само включение допускает loop. Цена динамики в том, что --list-tasks не покажет вложенные задачи, а теги работают иначе: их нужно вешать и на сам include. Если набор задач известен заранее, я беру import_tasks, а include_tasks только когда выбор зависит от данных.

Что хотят услышать: static против dynamic, когда разворачивается, влияние на теги и loop, выбор по ситуации.

Красный флаг: «это синонимы» или массовое использование include по привычке.

11. [middle] [углублённо] Как работают register, when, changed_when и failed_when?

Ответ

register: результат сохраняет вывод задачи в переменную: код возврата, stdout, статус. when запускает следующую задачу только при выполненном условии, например when: result.rc != 0. По умолчанию модуль command всегда отдаёт changed, хотя ничего не менял, поэтому я задаю changed_when, по stdout или коду возврата, и идемпотентность в выводе становится честной. failed_when делает наоборот: объявляет задачу упавшей по моему условию, если модуль сам считает успехом код, который мне не подходит.

Что хотят услышать: register хранит результат, when по условию, changed_when для честного changed у command/shell, failed_when для своего критерия ошибки.

Красный флаг: оставлять command без changed_when и жить с вечным changed=1.

12. [middle] [углублённо] Как в плейбуке обработать ошибку задачи: что такое block, rescue и always?

Ответ

block группирует задачи. Если одна упала, управление переходит в rescue, где я делаю откат или уведомление. Секция always выполняется после блока независимо от успеха, как finally, например чтобы убрать временные файлы, но не гарантированно: при недоступном хосте (UNREACHABLE) ни rescue, ни always не сработают. Так я обрабатываю, к примеру, неудачный рестарт сервиса: в rescue возвращаю старый конфиг и снова запускаю сервис. ignore_errors: true проще, но он просто скрывает ошибку и идёт дальше, и использовать его надо точечно.

Что хотят услышать: block/rescue/always как try/catch/finally, пример отката, ignore_errors только точечно.

Красный флаг: ignore_errors: true на всех задачах.

Проверено на версиях

  • ansible-core 2.21.4 (venv, Python 3.14, macOS). Локально прогнаны: шаблон с --check --diff (изменение видно, файл не тронут, блок RUNNING HANDLER появляется), check_mode: false у команды, которая только читает (без него в сухом прогоне register получает skipped: true и пустой stdout), ansible-lint playbooks/ по четырём файлам урока (одно замечание no-relative-paths).
  • Задачи с apt, user, systemd_service, публикацию репозитория Docker и site.yml целиком (ok=15) в этой версии урока на ВМ не запускали: числа ok, changed и версия Compose в выводах примерные. Ubuntu 26.04 и облачная ВМ не проверялись.
  • Скрипта поломки для этого урока нет: сценарии «Сломай и почини» выполняются руками.

Итог урока: ты умеешь

  • умею писать плейбук с play, tasks и become и запускать его через ansible-playbook
  • умею доказать идемпотентность вторым запуском с changed=0
  • умею генерировать конфиг из шаблона Jinja2 и выдавать права 640 root:notes
  • умею вызывать handler через notify и объяснить, когда он срабатывает
  • умею читать --check --diff и знаю его пределы для command
  • умею ограничивать запуск через --tags, --limit и --start-at-task
  • умею собрать site.yml из нескольких плейбуков через import_playbook
  • умею найти причину is undefined и неидемпотентной задачи

Дальше: Урок 7.6: роли и деплой «Заметок» одним запуском

Проверь себя

Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.

Тест работает с включённым JavaScript.

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

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

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