Ansible: настройка Linux-сервера и безопасный deploy — 9 практических сценариев
Девять сценариев реального SSH-стенда: первый и повторный запуск, конфигурация Nginx, релизы, rollback и Vault. Исходники и практический порядок Windows/Linux/VPS.

Ansible: сервер, настройку которого можно повторить
Новый сервер обычно начинается с понятных действий: установить пакет, создать пользователя, положить конфигурацию, запустить приложение и проверить ответ. Проблемы появляются позже, когда таких серверов становится несколько, настройка меняется, а часть команд осталась только в истории терминала. Нужно понимать, чем отличаются окружения и как восстановить рабочее состояние после ошибки.
Ansible позволяет описать эту последовательность в файлах и применять её к выбранным машинам. В статье мы построим небольшую лабораторию: настоящий Linux-контроллер подключается по SSH к отдельному Linux-серверу, настраивает Nginx, выпускает две версии приложения и проверяет восстановление после неудачного релиза. Затем разберём перенос подхода на VPS.
Ниже доступны девять записей реального выполнения, полные команды, счётчики изменений и исходники. Можно сравнить первый и повторный запуск, увидеть diff, скачать результат и подготовить собственный inventory. Для повторения есть архив с закреплёнными зависимостями и инструкциями Windows и Linux. Браузерная страница не получает доступ к вашим серверам.
Где применять: настройка, релизы и обслуживание
Ansible полезен, когда работу нужно выполнить одинаково и затем проверить. Например, подготовить сервер PHP-приложения, настроить каталог загрузок, установить Nginx, добавить конфигурацию reverse proxy или развернуть worker Node.js. Другой сценарий — провести одно изменение на нескольких машинах: обновить публичный ключ команды, поправить лимит сервиса или заменить шаблон конфигурации.
Он также помогает сделать передачу проекта понятнее. Вместо инструкции «на сервере когда-то выполняли эти команды» в репозитории находятся inventory, роль, переменные и процедура проверки. Новый участник видит желаемое состояние и может воспроизвести его на отдельном стенде. Изменения этих файлов проходят обычное обсуждение и проверку кода.
При этом полезность начинается даже с одного VPS. Если сервер потерян или нужно создать staging, повторяемая процедура экономит время. Начинать лучше с одной ограниченной задачи: отдельного каталога приложения, проверенного SSH-доступа и явного health check. Постепенно добавляются пакеты, сервисы, резервное копирование и процессы выпуска, которые действительно нужны вашему проекту.
Ansible, shell-скрипт, Docker Compose и Terraform
Shell-скрипт подходит для линейной операции, но разработчик сам отвечает за повторный запуск: существует ли пользователь, нужно ли перезаписывать файл, как распознать уже выполненный шаг. Ansible предлагает модули с описанием состояния и единый отчёт. Это не отменяет командную строку, но позволяет не писать заново множество проверок вокруг привычных действий.
Docker Compose описывает совместный запуск контейнеров. В нашей лаборатории он создаёт инфраструктуру, внутри которой демонстрируется Ansible. Эти инструменты могут дополнять друг друга: Ansible готовит Linux-хост и выкладывает compose-проект, а Compose управляет контейнерными сервисами. Не обязательно переносить каждую команду Docker в отдельную задачу, если уже есть ясный рабочий процесс.
Terraform чаще применяют для ресурсов инфраструктуры через API провайдера, а Ansible — для настройки и операций на доступных машинах. Границы зависят от проекта. Выбирайте инструмент по тому, какое состояние нужно поддерживать, кто его меняет и как проверяется результат. Наличие playbook само по себе не делает развёртывание безопасным или полностью обратимым.
Версии, control node и managed node
В примере используется ansible-core 2.22.0. Это ядро с встроенными модулями ansible.builtin; дополнительные community collections здесь не нужны. Пакет ansible и пакет ansible-core имеют разные номера и состав поставки, поэтому сравнивать их версии как одну линейку неверно. Точные Python-зависимости и контрольные суммы находятся в requirements.lock.
На момент подготовки PyPI указывает для core 2.22 требование Python не ниже 3.13 на контроллере. Контроллер выполняет Ansible, читает проект и подключается к целевым узлам. В лаборатории обе стороны используют Linux и Python 3.13. Возможности target, путь интерпретатора и требования конкретной версии нужно проверять отдельно от установленного Python на вашем ноутбуке.
Версию сверяйте по странице ansible-core 2.22.0 и руководству установки. Windows используется для запуска Docker-стенда из PowerShell. Сам Ansible работает в Linux-контейнере: нативный Windows control node этот материал не обещает. Альтернативный путь через WSL описан отдельно, без утверждения о его проверке в этой лаборатории.
ansible --version
python --version
Мини-мастерская: девять настоящих результатов
Выберите задачу, затем конкретную команду внутри неё. Первый сценарий показывает успешный SSH, отказ при подменённом ключе, дерево inventory и ping. В других задачах можно сравнить два окружения, первое применение и повтор, исправный релиз и восстановление после ошибки. Вывод процесса доступен целиком, а каждый результат можно скачать в JSON.
Мастерская честно показывает механизм: это интерактивный просмотр записей настоящего выполнения. Нажатие «Далее» не запускает новую настройку сервера. Время и счётчики относятся к сохранённому тестовому запуску. Такой формат позволяет изучать серверную автоматизацию прямо на странице, не выдавая посетителю SSH-доступ и не подменяя результат случайными числами.
Ниже расположен отдельный полезный инструмент — конструктор inventory. Он проверяет простые параметры и создаёт YAML локально. Доступность адреса, права пользователя и подлинность сервера проверяются уже в вашей среде. Для полноценного повторения скачайте лабораторию: в ней находятся playbook, роль, шаблон, проверяющий код и все инструкции.
Как устроен изолированный стенд
Compose создаёт два сервиса: controller и target. Первый содержит Ansible и исполняет сценарии; второй запускает SSH-сервер и предоставляет отдельную Linux-среду для настройки. Порты не публикуются на хост, сеть проекта изолирована. Все изменения каталога приложения, пользователя и Nginx выполняются внутри target, а не на вашем рабочем компьютере.
Ключ клиента создаётся специально для лаборатории. Публичный ключ сервера считывается через управление собственным Docker-контейнером и записывается в known_hosts контроллера. Затем SSH требует точного совпадения. При неверном ключе тест ожидает отказ. В обычной эксплуатации Docker-доступ не заменяет проверку VPS: там fingerprint нужно сверять через доверенную консоль провайдера.
Имя проекта фиксировано: aen-b23-ansible. Не запускайте две копии одновременно. После проверки скрипт выполняет down только для этого проекта; другие контейнеры, образы и Docker Desktop не затрагиваются. Приватные лабораторные данные находятся в .runtime и не входят в архив, публичные исходники или Docker build context.
Файл: compose.yaml
name: aen-b23-ansible
services:
target:
build:
context: .
target: target
labels:
aen.batch: '23'
aen.project: ansible
volumes:
- ./.runtime:/seed:ro
networks: [lab]
controller:
build:
context: .
target: controller
labels:
aen.batch: '23'
aen.project: ansible
volumes:
- .:/work
networks: [lab]
profiles: [tools]
networks:
lab:
internal: true
Windows: запуск из PowerShell через Docker
Установите и запустите Docker Desktop в режиме Linux containers, проверьте команды docker и docker compose. Для управляющего скрипта нужен Python 3 на Windows. Node.js требуется только для сборки и локального просмотра страницы; готовая папка public уже включена в проект. Распакуйте архив в отдельный каталог и откройте в нём PowerShell.
Команда run.ps1 строит образы, готовит ключи, выполняет девять сценариев и снимает собственный стенд. Первый запуск дольше из-за загрузки базового образа, системных пакетов и Python-зависимостей. Во время выполнения не закрывайте Docker. Если консоль была аварийно прервана, команда down из того же каталога завершит только лабораторный проект.
После выполнения npm run build обновляет страницу свежими записями. Адрес локального просмотра — http://127.0.0.1:8584/. Открывать index.html через file:// не следует: мастерская загружает JSON и JavaScript-модули по HTTP. Сервер просмотра слушает только loopback и останавливается Ctrl+C в своей консоли.
docker version
docker compose version
python --version
./tools/run.ps1
npm ci
npm test
npm run build
npm run serve
Linux: Docker-лаборатория и отдельный venv
На Linux тот же стенд запускается через tools/run.sh. Нужны Docker Engine с Compose plugin и Python 3. Фактический control node находится внутри контейнера с закреплённой версией Python. Это удобно для первого знакомства: установка Ansible не меняет системные Python-пакеты рабочей машины и не требует доступа к настоящему серверу.
Для постоянного Linux-контроллера можно создать отдельный venv на совместимом Python 3.13 и установить requirements.lock с проверкой хешей. Если в дистрибутиве другая версия Python, не заменяйте системный интерпретатор ради статьи. Выберите поддерживаемый способ установки дополнительного Python или продолжайте использовать контейнерный контроллер.
В WSL логика такая же, как на Linux: проект, venv и SSH-клиент находятся внутри Linux-среды. Этот вариант полезен пользователю Windows, который предпочитает привычный терминал Linux. В нашей проверке зафиксирован путь PowerShell → Docker → Linux controller → SSH target; отдельного испытания WSL и физического VPS не заявлено.
sh tools/run.sh
# Для отдельного Linux-контроллера:
python3.13 -m venv ~/.venvs/aen-ansible
. ~/.venvs/aen-ansible/bin/activate
python -m pip install --require-hashes -r requirements.lock
ansible --version
Сценарий 1. Inventory: кому адресованы задачи
Inventory описывает узлы и группы. В лаборатории группа web содержит один узел lab, а его ansible_host указывает на имя сервиса target внутри Docker-сети. Имя узла в отчёте и сетевой адрес могут отличаться. Это удобно, когда логическое имя stage01 остаётся прежним, а адрес машины меняется.
На уровне группы расположены переменные приложения: окружение, каталог и порт. Настройки соединения относятся к конкретному узлу. Для первого применения всегда полезно посмотреть дерево и список выбранных хостов. Ошибка в inventory опаснее опечатки в сообщении: корректный playbook может выполнить не то изменение не на той машине.
Параметр –limit lab дополнительно ограничивает запуск. Он не создаёт узел и не исправляет неверный адрес, а сужает уже определённый набор. Перед действиями на VPS сверяйте одновременно имя, адрес, пользователя и количество выбранных машин. Конструктор на странице помогает подготовить файл, но не знает вашу инфраструктуру.
Файл: inventories/lab.yml
all:
children:
web:
hosts:
lab:
ansible_host: target
ansible_user: root
ansible_ssh_private_key_file: /tmp/aen-ssh/id_ed25519
vars:
app_env: dev
app_root: /srv/aen-ansible
app_port: 8080
ansible-inventory --graph
ansible web --limit lab --list-hosts
SSH: проверка сервера до выполнения playbook
SSH должен удостовериться, что подключение идёт к ожидаемому серверу. В проекте включены host_key_checking и StrictHostKeyChecking=yes, а known_hosts содержит заранее полученный публичный ключ target. Второй тест намеренно подставляет другой ключ: правильный приватный ключ клиента не должен помогать, если сервер не соответствует известной записи.
В результате такой команды ожидается exit 255. Это полезный отрицательный тест: отказ здесь подтверждает, что проверка действительно работает. Успешный ansible.builtin.ping затем показывает, что Ansible смог подключиться и выполнить модуль через Python. Это не сетевой ICMP ping и не проверка работоспособности вашего приложения.
Для VPS используйте отдельного пользователя и подтверждайте fingerprint через консоль провайдера или другой доверенный канал. Команда ssh-keyscan может собрать ключ, но сама не доказывает его подлинность. При неожиданной смене ключа сначала выясняют причину. Отключение проверки ради исчезновения сообщения лишает эту защиту смысла.
Файл: ansible.cfg
[defaults]
inventory = inventories/lab.yml
roles_path = roles
host_key_checking = True
retry_files_enabled = False
interpreter_python = /usr/local/bin/python3
timeout = 15
[ssh_connection]
ssh_args = -o ControlMaster=no -o StrictHostKeyChecking=yes -o UserKnownHostsFile=/tmp/aen-ssh/known_hosts
pipelining = True
ansible web --limit lab -m ansible.builtin.ping
Сценарий 2. Facts и проверяемые переменные
Facts — сведения, полученные с целевого узла: система, архитектура, интерпретатор и другие параметры. В нашем playbook собираются facts, но в вывод попадает только небольшой полезный набор. Не стоит без необходимости публиковать полный дамп: он усложняет журнал и может раскрывать лишние подробности окружения.
Переменная app_env принимает только dev или stage, порт ограничен допустимым диапазоном. assert проверяет эти условия до изменения файлов. Три запуска показывают dev, stage и намеренно неподдерживаемое prod. Последний останавливается с ошибкой. Это понятнее, чем получить странную конфигурацию Nginx в конце длинного playbook.
Проверка входных значений особенно нужна там, где переменные попадают в пути, шаблоны или условия. В реальном проекте отдельно контролируют имя релиза, расположение каталога и адреса зависимостей. Значения из CI тоже являются входными данными. Удобный интерфейс запуска не отменяет проверки внутри самого playbook.
Файл: playbooks/facts.yml
- name: Inspect a known lab host
hosts: web
gather_facts: true
tasks:
- name: Validate environment before changing anything
ansible.builtin.assert:
that:
- app_env in ['dev', 'stage']
- app_port | int >= 1024
- app_port | int <= 65535
fail_msg: Unsupported environment or unprivileged port
- name: Report selected facts only
ansible.builtin.debug:
msg:
environment: '{{ app_env }}'
distribution: '{{ ansible_facts.distribution }}'
python: '{{ ansible_facts.python.version.major }}.{{ ansible_facts.python.version.minor }}'
inventory: '{{ inventory_hostname }}'
ansible-playbook playbooks/facts.yml --limit lab -e app_env=stage
Сценарий 3. Пользователь и права на каталоги
Приложению создаётся отдельная системная учётная запись aenapp без интерактивной оболочки и домашнего каталога. Далее роль создаёт каталог проекта и дерево releases с заданным владельцем и правами. Такой подход делает назначения явными: видно, кто владеет файлами и кому разрешено читать или менять содержимое.
Права записаны строками, например 0755 и 0644. Не подменяйте разбор проблемы командой chmod 777: это расширяет доступ и маскирует неверно выбранного владельца. Для вашего приложения необходимо отдельно определить, какие каталоги доступны на запись, какие только читаются веб-сервером и где хранятся загружаемые пользователями файлы.
Лабораторная роль ограничивает app_root значением /srv/aen-ansible. Если передать другой путь, assert завершит выполнение. При переносе на VPS это ограничение меняют осознанно под отдельный каталог сервиса. Не делайте универсальный playbook, способный рекурсивно менять произвольное дерево по случайной переменной.
Файл: roles/web_lab/tasks/main.yml
- name: Create an unprivileged application account
ansible.builtin.user:
name: aenapp
system: true
create_home: false
shell: /usr/sbin/nologin
tags: [prepare]
- name: Create owned working directories
ansible.builtin.file:
path: '{{ item }}'
state: directory
owner: aenapp
group: aenapp
mode: '0755'
loop:
- '{{ app_root }}'
- '{{ app_root }}/releases'
- '{{ app_root }}/releases/{{ release_id }}'
tags: [prepare, deploy]
Повторный запуск: что означает changed=0
После первого применения лаборатория запускает ту же роль ещё раз. Ожидаемый результат — changed=0: пользователь, каталоги, содержимое файлов и выбранный релиз уже соответствуют описанию. Именно второй запуск часто показывает качество автоматизации. Если каждое применение переписывает один и тот же файл или без причины перезапускает сервис, процесс трудно использовать ежедневно.
Счётчик changed не является универсальным доказательством правильности. Он отражает отчёты модулей и заданную вами логику changed_when. Можно ошибочно пометить изменяющую команду как неизменяющую и получить красивый recap. Поэтому в проекте счётчики дополняются HTTP-проверкой, наблюдением текущего релиза и сравнением контрольных сумм там, где это важно.
В мастерской откройте третью задачу и переключите первый и второй варианты команды. Посмотрите, какие шаги создали состояние, а какие во втором запуске сообщили ok. Для собственного проекта повторное применение стоит включить в обычную проверку роли на чистом стенде и после изменения шаблонов.
ansible-playbook playbooks/site.yml --limit lab
ansible-playbook playbooks/site.yml --limit lab
Сценарий 4. Шаблон Jinja и конфигурация Nginx
Шаблон позволяет держать одну структуру конфигурации и подставлять только согласованные параметры. В лаборатории меняются app_root, app_port и app_env. Последнее значение попадает в заголовок X-Environment, поэтому результат виден не только в файле, но и в HTTP-ответе. Это небольшая, но наблюдаемая связь между переменной и работающим сервисом.
Модуль template получает явного владельца, права, backup и команду validate. Здесь шаблон является полным самостоятельным конфигом Nginx, поэтому его можно проверить командой nginx -t -c с временным путём. Для отдельного include-фрагмента такая проверка требует другой обвязки: нельзя автоматически считать его полноценным nginx.conf.
Файл backup полезен для расследования и ручного восстановления, но не заменяет продуманный выпуск. Он не откатывает приложение, базу данных или внешние действия. В демонстрации после перехода dev → stage проверяется наличие backup, вызов handler и фактический HTTP-заголовок. Подробности параметров есть в документации template.
Файл: roles/web_lab/templates/nginx.conf.j2
user www-data;
worker_processes 1;
pid {{ app_root }}/nginx.pid;
error_log {{ app_root }}/error.log;
events { worker_connections 128; }
http {
include /etc/nginx/mime.types;
access_log {{ app_root }}/access.log;
server {
listen {{ app_port }};
add_header X-Environment {{ app_env }} always;
root {{ app_root }}/current;
location / { try_files $uri =404; }
}
}
Файл: roles/web_lab/tasks/main.yml
- name: Render and validate a complete standalone Nginx configuration
ansible.builtin.template:
src: nginx.conf.j2
dest: '{{ app_root }}/nginx.conf'
owner: root
group: root
mode: '0644'
backup: true
validate: /usr/sbin/nginx -t -c %s
notify: Reload lab Nginx
tags: [config]
Сценарий 5. Handler и момент применения изменений
Шаблон уведомляет handler только при изменении. Handler выполняет reload лабораторного Nginx. Если несколько задач уведомят один handler, это не означает несколько одинаковых перезагрузок в конце этапа. В нашем сценарии после изменения окружения проверяется один вызов, а повтор с тем же stage вообще не вызывает handler.
Перед HTTP-проверкой используется flush_handlers: конфигурация должна быть применена прежде, чем мы оцениваем результат. Без понимания порядка можно проверить старый процесс и сделать неправильный вывод о новом конфиге. Название handler должно ясно описывать действие, особенно если в роли есть несколько сервисов или разные способы перезапуска.
В этой лаборатории Nginx запускается отдельной командой, поскольку systemd не является PID1 контейнера. На обычном VPS управление процессом переносится в systemd_service. Наличие команды reload ещё не гарантирует отсутствие потерь запросов: поведение зависит от приложения и выбранного способа перезапуска. Семантика уведомлений описана в руководстве handlers.
Файл: roles/web_lab/handlers/main.yml
- name: Reload lab Nginx
ansible.builtin.command:
argv: [/usr/sbin/nginx, '-s', reload, '-c', '{{ app_root }}/nginx.conf']
changed_when: true
when: not ansible_check_mode
Сценарий 6. Check и diff: увидеть план изменения
На уже настроенном stage запускается тот же playbook с параметрами –check –diff и новым app_env=dev. В выводе видна предполагаемая замена заголовка. После команды отдельная проверка сравнивает SHA конфигурации и читает HTTP: файл остаётся прежним, а сервер продолжает отвечать stage. Так запись подтверждает поведение именно этого сценария.
Check mode зависит от поддержки конкретных модулей и логики задач. Он не является полноценной копией исполнения и не гарантирует, что последующий обычный запуск завершится успешно. Особенно внимательно нужно читать задачи с command, зависимостями от register и настройкой check_mode. В проекте read-only pgrep явно выполняется даже при check, чтобы увидеть реальный процесс.
Diff помогает увидеть изменение текста, но способен раскрыть секреты. Для задач с чувствительными значениями используйте diff: false и no_log там, где это необходимо. Перед production сначала выбирают один узел через –limit и изучают вывод. Границы режима изложены в официальном руководстве check/diff.
ansible-playbook playbooks/site.yml --limit lab --check --diff -e app_env=dev
Сценарий 7. Каталоги релизов и ссылка current
Роль создаёт каталог releases/v1 с небольшим JSON-артефактом, а current указывает на выбранную версию. Nginx читает содержимое через current. Для выпуска v2 запускается тот же playbook с release_id=v2. После переключения health check требует не только статус 200, но и правильное значение release в ответе.
Затем отдельный запуск возвращает v1. Старый каталог сохранён, поэтому повторно собирать его не требуется. В реальном процессе вместо учебного JSON здесь будет проверенный артефакт приложения: архив, каталог сборки или набор файлов с контрольной суммой. Желательно, чтобы один идентификатор релиза всегда означал одно и то же содержимое.
Пример не обещает атомарное переключение при любой файловой системе и нагрузке: он показывает управление ссылкой модулем file. Для строгих требований отдельно проектируют способ переключения, блокировку конкурентных deploy и работу процессов, которые удерживают старые файлы. Откат статического содержимого также не равен откату миграций базы данных.
Файл: roles/web_lab/tasks/main.yml
- name: Write the immutable demonstration release
ansible.builtin.copy:
content: '{{ {"release": release_id, "status": "ok"} | to_json }}'
dest: '{{ app_root }}/releases/{{ release_id }}/index.json'
owner: aenapp
group: aenapp
mode: '0644'
tags: [deploy]
- name: Select the release
ansible.builtin.file:
src: '{{ app_root }}/releases/{{ release_id }}'
dest: '{{ app_root }}/current'
state: link
owner: aenapp
group: aenapp
tags: [deploy]
ansible-playbook playbooks/site.yml --limit lab -e app_env=stage -e release_id=v2
Сценарий 8. Ошибка, block/rescue и проверенный возврат
Для демонстрации ошибки создаётся неполный релиз без index.json. Перед переключением сохраняется фактический предыдущий путь current. После перехода HTTP-проверка получает 404, и управление попадает в rescue. Там ссылка возвращается на ранее наблюдавшийся каталог, затем выполняется отдельная проверка восстановленного ответа.
После успешного возврата playbook намеренно заканчивается ошибкой DEPLOY_FAILED_ROLLBACK_OK. Это важная часть поведения: сервис снова доступен, но новый deploy не состоялся. Если скрыть ошибку за зелёным завершением, CI и оператор могут ошибочно считать, что выпущена новая версия. В мастерской видны rescued=1, failed=1 и exit 2.
Rescue не делает любую операцию обратимой. Подключение может пропасть, резервная версия может быть повреждена, а внешняя система уже принять запрос. Поэтому восстановление проектируется отдельно для каждого вида изменения. В статье мы ограничились файлом и ссылкой, сохранили предыдущий релиз и проверили ответ после возврата. Общие правила ошибок описаны в руководстве error handling.
Файл: playbooks/rollback.yml
- name: Demonstrate a failed release and verified rollback
hosts: web
gather_facts: false
vars:
app_root: /srv/aen-ansible
tasks:
- name: Read current target
ansible.builtin.stat:
path: '{{ app_root }}/current'
register: previous
- name: Require a known previous release
ansible.builtin.assert:
that:
- previous.stat.islnk
- previous.stat.lnk_source is match('^/srv/aen-ansible/releases/v[0-9]+$')
- name: Attempt the intentionally incomplete release
block:
- name: Create the incomplete release directory
ansible.builtin.file:
path: '{{ app_root }}/releases/broken'
state: directory
mode: '0755'
- name: Switch to the incomplete release
ansible.builtin.file:
src: '{{ app_root }}/releases/broken'
dest: '{{ app_root }}/current'
state: link
- name: Health check detects the missing artifact
ansible.builtin.uri:
url: http://127.0.0.1:8080/index.json
return_content: true
register: bad_health
failed_when: bad_health.status != 200
rescue:
- name: Restore the previously observed release
ansible.builtin.file:
src: '{{ previous.stat.lnk_source }}'
dest: '{{ app_root }}/current'
state: link
- name: Verify restored service
ansible.builtin.uri:
url: http://127.0.0.1:8080/index.json
return_content: true
register: restored
failed_when: restored.status != 200 or restored.json.status != 'ok'
- name: Fail the deployment after successful rollback
ansible.builtin.fail:
msg: DEPLOY_FAILED_ROLLBACK_OK
Register, failed_when и содержательный health check
Register сохраняет результат задачи для следующей проверки. В лаборатории это используется для HTTP-ответа, исходной ссылки и состояния процесса. Failed_when определяет, какой результат считать ошибкой. Условие нужно формулировать по смыслу операции: нулевой exit команды ещё не доказывает, что пользователь получает нужную версию приложения.
Наш health check проверяет статус и поле release. Для настоящего сервиса можно проверять идентификатор сборки, готовность обязательной зависимости или отдельную readiness-точку. Не включайте туда тяжёлые операции и не превращайте каждую проверку в отправку письма или создание записи. Проверка должна быть наблюдением с предсказуемой стоимостью.
Повторы с until и ограничением retries помогают пережить короткое время запуска, но не должны скрывать постоянную неисправность. Задайте разумную задержку и конечное число попыток. После их исчерпания процесс должен дать понятную ошибку и запустить согласованное восстановление, если оно возможно. Именно это делает результат пригодным для автоматического выпуска.
Файл: roles/web_lab/tasks/main.yml
- name: Verify the served release
ansible.builtin.uri:
url: 'http://127.0.0.1:{{ app_port }}/index.json'
return_content: true
register: health
until: health.status == 200
retries: 5
delay: 1
failed_when: health.status != 200 or health.json.release != release_id
when: not ansible_check_mode
tags: [health]
Сценарий 9. Roles, tags и ограничение хостов
Роль группирует задачи, defaults, handlers и templates вокруг одной ответственности. В архиве это web_lab: она настраивает учебное приложение и его Nginx. Такой способ организации помогает переиспользовать порядок действий и держать связанные файлы рядом. Он также делает обзор изменений проще, чем один огромный playbook со множеством несвязанных серверов.
Tags позволяют выбрать часть задач, например config или health. Но отдельная метка может пропустить необходимую подготовку. Запуск config на совершенно пустой машине не обязан создавать пользователей и каталоги, если вы их исключили. Поэтому сначала изучают –list-tags и зависимости, а затем определяют поддерживаемые варианты частичного применения.
Параметр serial: 1 задаёт поочерёдную обработку узлов в партии. Это полезная часть постепенного выпуска, но не готовая гарантия доступности. Для нескольких рабочих серверов нужны балансировщик, вывод узла из обслуживания, проверка готовности и запас мощности. В нашей записи target один; полноценный rolling deploy нескольких VPS не выдаётся за проведённый тест.
Файл: playbooks/site.yml
- name: Configure the isolated web lab
hosts: web
gather_facts: false
serial: 1
roles:
- role: web_lab
tags: [web]
ansible-playbook playbooks/site.yml --limit lab --list-tags
ansible-playbook playbooks/site.yml --limit lab --syntax-check
Vault: секреты в файлах и отсутствие секретов в журнале
Последний сценарий создаёт случайное учебное значение и шифрует его через ansible-vault. Playbook загружает зашифрованный файл и проверяет требуемую длину токена. Задача помечена no_log и diff: false. В публичный отчёт попадает только факт завершения; проверяющий код дополнительно убеждается, что значение и пароль не оказались в выводе процесса.
Файлы с приватным SSH-ключом, паролем Vault и зашифрованными переменными хранятся в .runtime и исключены из ZIP. Для повторения скрипт создаст собственные значения. Не используйте лабораторные ключи на рабочих серверах и не переносите их в другой проект. Для CI пароль Vault должен приходить из защищённого хранилища, а не из аргумента, записанного в репозитории.
Vault защищает содержимое файла при хранении. После расшифровки значение доступно исполняющему процессу, поэтому нужны обычные права доступа и дисциплина журналирования. Debug секретной переменной способен перечеркнуть пользу шифрования. Подробнее — руководство Ansible Vault.
Файл: playbooks/secret.yml
- name: Read an encrypted variable without logging its value
hosts: web
gather_facts: false
vars_files:
- ../.runtime/vault.yml
tasks:
- name: Require the demonstration token
ansible.builtin.assert:
that: demo_token | length >= 16
no_log: true
diff: false
- name: Report only completion
ansible.builtin.debug:
msg: Vault value validated; contents intentionally omitted
ansible-vault create group_vars/web/vault.yml
ansible-playbook site-vps.yml --limit stage01 --ask-vault-pass
Linux/VPS: подготовить доступ и отдельный конфиг
Для настоящего сервера начните с отдельной stage-машины и возможности войти через консоль провайдера. Создайте пользователя deploy, настройте ключ и необходимые sudo-права. Проверка первого SSH-подключения должна произойти до Ansible. Если вы ещё не можете вручную войти и подтвердить fingerprint, автоматизация не исправит эту неопределённость.
Лабораторный ansible.cfg содержит специальные пути /tmp/aen-ssh, поэтому для VPS создаётся отдельный ansible-vps.cfg. В нём сохраняется проверка ключа, но используется обычный known_hosts вашего контроллера. Пример inventory в архиве содержит адрес 192.0.2.10 из диапазона документации: его необходимо заменить реальным адресом, а не пытаться подключиться к нему.
После этого проверьте дерево inventory, список выбранных хостов, ping и facts. Только затем переходите к изменяющим задачам. Для повышения привилегий используйте become осознанно: чтение фактов и изменение системного unit требуют разных возможностей. Полный порядок и команды собраны в VPS.md, доступном в просмотрщике исходников.
export ANSIBLE_CONFIG="$PWD/ansible-vps.cfg"
ansible-inventory --graph
ansible web --limit stage01 --list-hosts
ansible web --limit stage01 -m ansible.builtin.ping
ansible-playbook playbooks/facts.yml --limit stage01
Файл: inventories/vps.example.yml
all:
children:
web:
hosts:
stage01:
ansible_host: 192.0.2.10
ansible_user: deploy
ansible_python_interpreter: /usr/bin/python3
vars:
app_env: stage
app_root: /srv/my-service
app_port: 8080
# Documentation address: replace with your own server after SSH verification.
# Do not apply the lab role to production unchanged; see VPS.md.
Перенос на VPS: пакеты и служба systemd
Скопируйте учебную роль под именем вашего сервиса и задайте один выделенный app_root. Согласуйте владельцев, каталоги на запись, журналирование и порт. Установка Nginx на обычном сервере становится отдельной задачей apt с повышением привилегий. Выбирайте state: present или согласованную версию; бездумное latest при каждом deploy может обновить больше, чем ожидалось.
Лабораторный запуск Nginx через command заменяется управлением systemd_service. В архиве есть пример отдельного unit: он проверяет подготовленный конфиг и запускает Nginx в foreground. Unit предполагает, что каталог, конфигурация и первый релиз уже созданы. Он не является автоматической заменой штатной службы Nginx на любом сервере.
Проверяйте unit и полный процесс на своей stage VM. В контейнерной лаборатории systemd не запускался, поэтому этот участок описан как практика переноса, а не как выполненный VPS-тест. Для публичного домена отдельно настройте HTTPS и reverse proxy, а служебный порт оставьте доступным только там, где он нужен архитектуре.
Файл: deploy/aen-web.service
[Unit]
Description=Dedicated Nginx for an application release
After=network.target
[Service]
Type=simple
ExecStartPre=/usr/sbin/nginx -t -c /srv/my-service/nginx.conf
ExecStart=/usr/sbin/nginx -c /srv/my-service/nginx.conf -g "daemon off;"
ExecReload=/usr/sbin/nginx -s reload -c /srv/my-service/nginx.conf
Restart=on-failure
RestartSec=3
PrivateTmp=true
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
- name: Start the prepared application service
ansible.builtin.systemd_service:
name: aen-web
state: started
enabled: true
daemon_reload: true
become: true
Порядок первого применения на рабочем сервере
Сначала подготовьте адаптированный playbook и резервную копию затрагиваемых данных. Посмотрите список хостов, выполните syntax-check, затем check/diff на одном stage-узле. Изучите реальные изменения, особенно владельцев, пути и содержимое конфигурации. После обычного запуска проверьте сервис снаружи и повторите playbook, чтобы увидеть ненужные изменения.
Дальше наблюдайте за журналом, ответами приложения и зависимостями. Один успешный HTTP-запрос не доказывает, что все пользовательские сценарии исправны. Для PHP проверьте нужный FPM upstream и доступ к файлам; для Node.js — процесс приложения, переменные окружения и поведение после перезапуска. Эти проверки становятся частью вашей роли или release pipeline.
Имена site-vps.yml и stage01 в примерах обозначают ваш адаптированный проект. Такой файл нужно создать на основе своей конфигурации; он не спрятан в архиве под другим названием. Материал даёт рабочие строительные блоки и испытанную лабораторию, а production-параметры должны соответствовать конкретному серверу и сервису.
ansible-playbook site-vps.yml --limit stage01 --syntax-check
ansible-playbook site-vps.yml --limit stage01 --check --diff --ask-become-pass
ansible-playbook site-vps.yml --limit stage01 --ask-become-pass
ansible-playbook site-vps.yml --limit stage01 --ask-become-pass
ssh deploy@YOUR_SERVER 'systemctl status aen-web --no-pager'
ssh deploy@YOUR_SERVER 'curl --fail http://127.0.0.1:8080/index.json'
Частые ошибки и как читать результат
Unreachable обычно означает, что до выполнения модуля не удалось установить подходящее соединение. Проверяйте адрес, маршрут, порт SSH, пользователя, ключ и known_hosts. Ошибка модуля после успешного подключения — другой уровень: здесь важны права, интерпретатор, пакет, путь и содержание задачи. Не смешивайте эти ситуации в одно сообщение «Ansible не работает».
Если changed появляется при каждом запуске, посмотрите на команды, динамические даты в шаблоне и фактическое содержимое файла. Если handler не вызван, проверьте, было ли изменение и наступил ли момент исполнения уведомлений. Если check прошёл, а apply нет, изучите, какие задачи не моделировались и какие данные появились только во время настоящего исполнения.
Не скрывайте проблему общим ignore_errors. Для ожидаемого отрицательного результата задайте конкретное условие и проверку. В лаборатории неверный SSH-ключ и неподдерживаемое окружение являются намеренными отказами, а не случайными сбоями. Мастерская показывает их команды, exit и объяснение, чтобы можно было отличить полезный тест от неудавшейся настройки.
Что именно было проверено и что остаётся за рамками
Архив содержит результат настоящего запуска Ansible 2.22.0 на Linux-контроллере с отдельным SSH-target. Проверены девять сценариев, включая неправильный host key, повторный changed=0, backup конфигурации, однократный handler, неизменность файла после check, выпуск v2, возврат к v1, неудачный deploy с rescue и отсутствие секрета в логе.
Для UI отдельно проверяются конструктор inventory и целостность записей. Исходники, публичный JSON и файл сборки позволяют сопоставить показанный вывод с проектом. Контрольная сумма вывода помогает проверить скачанную запись, но не превращает её в доказательство состояния вашего сервера: это результат конкретной изолированной лаборатории.
Не заявляются нативный Windows-контроллер, работа systemd внутри обычного контейнера, испытание WSL, несколько физических VPS или промышленный zero-downtime deploy. Эти границы помогают правильно перенести пример. Начните с собственного stage, повторите сценарии и добавьте проверки того приложения, ради которого вы используете автоматизацию.
Исходники, лицензии и следующий практический шаг
Скачайте ZIP, выполните лабораторию и сравните свежий отчёт с опубликованным. Затем измените одну понятную переменную — например окружение — и проследите всю цепочку: входное значение, шаблон, handler, HTTP и recap. Это полезнее, чем сразу переносить большой playbook на рабочую машину без понимания порядка действий.
Авторские файлы мастерской распространяются под MIT. Ansible-core устанавливается отдельно и сохраняет лицензию GPLv3-or-later; он не встроен в браузерный JavaScript. Bootstrap используется под MIT. Python-зависимости имеют собственные лицензии, а lock-файл фиксирует версии и хеши поставки. В архиве нет node_modules, приватных ключей и паролей лаборатории.
Для своего проекта выберите один повторяемый процесс: подготовку staging, выпуск статической сборки, настройку worker или обновление конфигурации. Опишите ожидаемое состояние, проверку результата и действие при ошибке. Сохраните этот порядок рядом с кодом приложения, чтобы следующая настройка начиналась с проверенной процедуры и понятного отчёта.


