Пять серверов, и на каждом нужно обновить пакеты, поправить sysctl, добавить правило в фаервол и перезапустить контейнеры. Пока VDS один, это пятнадцать минут в SSH-сессии. Когда их десять, ручной цикл превращается в главный источник аварий: на одном хосте правило добавлено, на другом забыто, на третьем версия Nginx отличается от документации. Ansible убирает этот класс ошибок: вы один раз описываете желаемое состояние серверов в YAML, а инструмент приводит к нему весь парк по SSH — без установки агентов, без открытых дополнительных портов и без «а я думал, ты уже накатил». Разберем рабочую связку ansible-core 2.21.5 (community-пакет ansible 14.5.0) на Ubuntu 24.04: от структуры проекта и инвентаря до ролей для UFW, sysctl, Nginx и Docker, секретов через ansible-vault и уведомления в Telegram о результате прогона.
1. Зачем Ansible, если уже есть SSH, bash-скрипты и GitHub Actions
Ansible не заменяет SSH — он работает поверх него. Ключевое отличие от самописного bash-скрипта не в языке, а в модели выполнения: скрипт описывает последовательность команд, а Ansible — целевое состояние. Эта разница определяет всё остальное.
Инструмент работает по push-модели и не требует постоянного демона на управляемых хостах: control-нода подключается по SSH, копирует временный Python-модуль, выполняет его и удаляет. На сервере нужен только интерпретатор Python и SSH-доступ — ни агента, ни служебного порта, ни дополнительной поверхности атаки.
Практическая выгода проявляется на трех сценариях, знакомых каждому, кто администрирует больше одного сервера:
- Повторный прогон безопасен. Если пакет уже установлен, а правило фаервола уже добавлено, задача вернет статус
ok, а не выполнит действие заново. Bash-скрипт в такой ситуации либо упадет на дублирующейся строке в конфиге, либо создаст ее второй раз. - Дрейф конфигурации виден. Достаточно запустить плейбук в режиме
--check --diff, чтобы узнать, чем реальное состояние десяти серверов отличается от описанного в репозитории, — и не заходить на каждый хост руками. - Секреты не лежат в открытом виде. Пароли и токены шифруются
ansible-vaultи хранятся в том же репозитории рядом с ролями, а не в истории bash или в переписке.
| Критерий | Ручной SSH | Свой bash-скрипт | Ansible |
|---|---|---|---|
| Идемпотентность | Нет: повтор ломает конфиг | Пишется вручную на каждый шаг | Встроена в модули |
| Проверка без изменений | Отсутствует | Нужен отдельный dry-run режим | Флаг --check --diff |
| Отчет по парку | Нужно собирать вручную | Только свой вывод, без структуры | Сводка ok / changed / failed по каждому хосту |
| Секреты | В истории команд | В переменных окружения или файле | Шифрование ansible-vault |
| Агент на хосте | Не нужен | Не нужен | Не нужен, только SSH и Python |
| Порог входа | Нулевой | Нулевой | Нужно освоить YAML и модель ролей |
💡 Где граница между Ansible и CI/CD
Ansible приводит сервер к нужному состоянию, а GitHub Actions запускает сборку и копирование кода приложения. Это разные задачи, и они не конфликтуют: типовой конвейер выглядит как «CDN-пайплайн собирает артефакт, а плейбук уже с готовыми переменными накатывает его на десяток серверов и перезапускает сервис только там, где файл действительно изменился». Если деплой приложения из Git вам еще предстоит настраивать, начните с материала о деплое из GitHub Actions без простоя и вернитесь сюда за автоматизацией самого сервера.
2. Установка control-ноды: ansible 14.5.0, ansible-core 2.21.5 и структура проекта
Control-нода — это ваш рабочий ноутбук или отдельный VDS, с которого выполняются прогоны. Ansible не требует выделенного сервера: подойдет Ubuntu 24.04 с Python 3.12, который уже есть в системе.
Перед установкой важно не перепутать два пакета, потому что от этого зависит доступность модулей:
ansible-core— минимальное ядро: движок, встроенные модули и плагины. Версия на момент публикации — 2.21.5. Ниcommunity.general, ниcommunity.dockerв него не входят.ansible— community-пакет «батарейки в комплекте»: версия 14.5.0, которая ставитansible-core~=2.21.5и полный набор коллекций. Именно отсюда берутся модульcommunity.general.ufw,ansible.posix.sysctlиcommunity.docker.docker_compose_v2.
Ubuntu 24.04 помечен как externally managed (PEP 668), поэтому pip install в системный Python завершится ошибкой. Штатный путь — pipx, он создает изолированное окружение и не ломает пакеты дистрибутива:
sudo apt update
sudo apt install -y pipx
pipx ensurepath
exec $SHELL -l
# Полный community-пакет: ядро 2.21.5 + коллекции
pipx install --include-deps ansible
# Проверка версий
ansible --version
ansible-galaxy collection list | head -n 20
Обновление в дальнейшем выполняется одной командой pipx upgrade --include-injected ansible. Пакет из репозитория Ubuntu (apt install ansible) для этих задач не подходит: версия там отстает от актуальной на несколько минорных релизов, а часть коллекций отсутствует.
| Компонент | Версия / требование | Комментарий |
|---|---|---|
| ansible (community) | 14.5.0 |
Ядро плюс коллекции, рекомендуемый вариант. |
| ansible-core | 2.21.5 |
GA май 2026, поддержка до ноября 2027. |
| Python на control-ноде | 3.12 – 3.14 |
Ubuntu 24.04 LTS поставляет 3.12, попадает в окно. |
| Python на целевых хостах | 3.9 – 3.14 |
Ubuntu 22.04 (3.10) и 24.04 (3.12) поддерживаются. |
Структура проекта
Плоский каталог со скриптами быстро превращается в свалку, поэтому сразу разложим проект по стандартной схеме ролей:
ansible-vds/
├── ansible.cfg
├── site.yml
├── inventory/
│ └── hosts.yml
├── group_vars/
│ └── all/
│ ├── main.yml
│ └── vault.yml # зашифрован ansible-vault
└── roles/
├── common/
│ ├── tasks/main.yml
│ ├── handlers/main.yml
│ └── templates/journald-limits.conf.j2
├── firewall/
│ └── tasks/main.yml
├── nginx/
│ ├── tasks/main.yml
│ ├── handlers/main.yml
│ └── templates/site.conf.j2
└── docker/
└── tasks/main.yml
Файл ansible.cfg рядом с проектом применяется автоматически — глобальные флаги командной строки больше не нужны:
[defaults]
inventory = ./inventory/hosts.yml
forks = 10
interpreter_python = auto_silent
stdout_callback = yaml
host_key_checking = False
retry_files_enabled = False
[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False
⚠️ Два подводных камня в конфигурации
Первый: параметр stdout_callback = yaml ссылается на плагин community.general.yaml. В чистом ansible-core его нет — в ядре доступны только default, minimal, oneline, tree и junit. Если вы ставили минимальный пакет, оставьте вывод по умолчанию или установите community.general отдельно.
Второй: host_key_checking = False отключает сверку ключа SSH-хоста и экономит время на первом прогоне, но одновременно убирает защиту от подмены сервера. Для боевого парка соберите отпечатки заранее: ssh-keyscan -H 203.0.113.10 >> ~/.ssh/known_hosts, а параметр из конфигурации уберите.
Инвентарь описываем в YAML, а не в устаревшем INI — так проще задавать переменные на уровне групп. В примере используются адреса из диапазона документации 203.0.113.0/24, подставьте свои:
all:
children:
web:
hosts:
vds-web-1:
ansible_host: 203.0.113.10
vds-web-2:
ansible_host: 203.0.113.11
vars:
ansible_user: deploy
ansible_port: 22
ansible_ssh_private_key_file: ~/.ssh/id_ed25519
ansible_python_interpreter: /usr/bin/python3
Заранее стоит продумать и то, как вы будете проверять результат снаружи: после прогона полезно убедиться, что наружу открыты только 22, 80 и 443. Сделать это можно через онлайн-проверку открытых портов, не заходя на сам сервер.
3. Первый контакт с серверами: ping, сбор фактов и проверка прав sudo
Прежде чем писать роли, убедимся, что control-нода действительно видит все хосты и может повышать привилегии. Первый и самый частый сюрприз для новичка: модуль ansible.builtin.ping не отправляет ICMP-пакеты. Он подключается по SSH, запускает Python на целевом хосте и возвращает pong — то есть проверяет именно ту цепочку, которая нужна Ansible.
# Проверка SSH-доступа и наличия Python на всех хостах
ansible all -m ansible.builtin.ping
# Сбор фактов: дистрибутив, версия ядра, объем RAM
ansible web -m ansible.builtin.setup -a 'filter=ansible_distribution*'
# Проверка повышения привилегий (sudo без пароля)
ansible web -b -m ansible.builtin.command -a 'id -u'
Команда id -u должна вернуть 0. Если возвращается 1000, значит become: true не сработал: либо у пользователя нет прав в sudoers, либо sudo требует пароль. Во втором случае прогон выполняется с флагом --ask-become-pass, но для регулярной автоматизации правильнее один раз выдать пользователю ограниченное право без пароля в отдельном файле /etc/sudoers.d/ansible-deploy.
💡 Как завести пользователя, если Ansible еще не управляет хостом
Первичную учетную запись с ключом и sudo приходится создавать вручную — это единственный шаг, который Ansible не может сделать за вас на чистом сервере. Выполните его один раз на каждом хосте, после чего добавьте ключ в authorized_keys и не возвращайтесь к ручным действиям. Если сервер только что куплен, начните с харденинга Ubuntu 24.04 за первые 15 минут, а затем отдайте его под управление плейбука.
Обратите внимание на формат обращения к фактам: в современном Ansible используется словарь ansible_facts, то есть ansible_facts['distribution_release'], а не старые переменные вида ansible_distribution_release. Первый вариант не конфликтует с именами ваших собственных переменных и работает одинаково в любых ролях.
4. Роль common: базовые пакеты, часовой пояс, sysctl и лимиты журнала
Точка входа — файл site.yml. Он не содержит логики, только порядок применения ролей, поэтому читается за десять секунд:
---
- name: Baseline configuration for the whole fleet
hosts: all
become: true
gather_facts: true
roles:
- common
- name: Web tier
hosts: web
become: true
roles:
- firewall
- nginx
- docker
Роль common решает четыре задачи, которые повторяются на любом сервере: актуальный индекс пакетов, минимальный набор утилит, часовой пояс и сетевые параметры ядра. Начнем с пакетов и времени:
---
# roles/common/tasks/main.yml
- name: Refresh apt cache at most once per hour
ansible.builtin.apt:
update_cache: true
cache_valid_time: 3600
- name: Install baseline packages
ansible.builtin.apt:
name:
- curl
- gnupg
- ca-certificates
- ufw
- python3-debian
state: present
- name: Set system timezone
ansible.builtin.file:
src: /usr/share/zoneinfo/Europe/Moscow
dest: /etc/localtime
state: link
force: true
notify: Restart cron
Пакет python3-debian в списке не случаен: без него модуль ansible.builtin.deb822_repository, которым мы подключим репозиторий Docker, завершится ошибкой. Это требование модуля, а не прихоть конфигурации, — и именно такие зависимости чаще всего забывают указать в инструкциях.
Сетевые параметры ядра описываются циклом по списку пар «ключ — значение». Модуль ansible.posix.sysctl сам создает отдельный файл, применяет значение и перечитывает его, поэтому вручную редактировать /etc/sysctl.conf не нужно:
- name: Apply kernel network hardening
ansible.posix.sysctl:
name: "{{ item.name }}"
value: "{{ item.value }}"
sysctl_file: /etc/sysctl.d/99-ansible-security.conf
sysctl_set: true
state: present
reload: true
loop:
- { name: net.ipv4.tcp_syncookies, value: "1" }
- { name: net.ipv4.tcp_max_syn_backlog, value: "8192" }
- { name: net.core.somaxconn, value: "8192" }
- { name: net.ipv4.conf.all.rp_filter, value: "1" }
- { name: net.ipv4.conf.all.accept_redirects, value: "0" }
loop_control:
label: "{{ item.name }}"
Последний блок роли — ограничение роста журнала. Шаблон подставляет объем диска и создает файл, а изменение этого файла запускает обработчик:
- name: Deploy journald limits
ansible.builtin.template:
src: journald-limits.conf.j2
dest: /etc/systemd/journald.conf.d/99-limits.conf
owner: root
group: root
mode: "0644"
notify: Restart systemd-journald
# roles/common/templates/journald-limits.conf.j2
[Journal]
SystemMaxUse={{ journald_max_use }}
SystemKeepFree=1G
MaxRetentionSec=2week
Обработчики описываются отдельно и запускаются один раз в конце прогона, даже если их «дернули» пять задач подряд. Это принципиальное отличие от bash-скрипта, где systemctl restart nginx внутри цикла устроит пять перезапусков и пять коротких отказов в обслуживании:
---
# roles/common/handlers/main.yml
- name: Restart systemd-journald
ansible.builtin.systemd_service:
name: systemd-journald
state: restarted
- name: Restart cron
ansible.builtin.systemd_service:
name: cron
state: restarted
Значение journald_max_use выносится в group_vars/all/main.yml, чтобы роль оставалась универсальной и не требовала правок под каждый тариф:
---
# group_vars/all/main.yml
journald_max_use: 500M
ssh_port: 22
ufw_allowed_tcp:
- { port: 22, comment: "SSH" }
- { port: 80, comment: "HTTP" }
- { port: 443, comment: "HTTPS" }
⚠️ Порядок в ролях важнее, чем кажется
Если включить UFW раньше, чем настроен SSH-порт, есть риск потерять доступ к серверу: правило на 22-й порт еще не создано, а политика по умолчанию уже запрещает входящие. Поэтому роль firewall в site.yml стоит после common, но перед сервисными ролями, а первый прогон всегда выполняется с --check --diff и на одном хосте через --limit.
5. Роль firewall: политики UFW, ограничение SSH и правило для HTTP/3
Роль firewall — самый короткий и самый опасный раздел проекта. Ошибка в порядке правил здесь стоит доступа к серверу, поэтому политика по умолчанию и разрешающие правила описываются в одном файле, а сам модуль идемпотентен: повторный запуск не создает дублирующихся записей в /etc/ufw/user.rules.
---
# roles/firewall/tasks/main.yml
- name: Deny all incoming traffic by default
community.general.ufw:
policy: deny
direction: incoming
- name: Allow outbound traffic
community.general.ufw:
policy: allow
direction: outgoing
- name: Rate-limit SSH to slow down brute force
community.general.ufw:
rule: limit
port: "{{ ssh_port }}"
proto: tcp
comment: "SSH (rate limited)"
- name: Allow web ports over TCP
community.general.ufw:
rule: allow
port: "{{ item.port }}"
proto: tcp
comment: "{{ item.comment }}"
loop: "{{ ufw_allowed_tcp }}"
- name: Allow HTTP/3 over UDP
community.general.ufw:
rule: allow
port: "443"
proto: udp
comment: "HTTP/3 QUIC"
- name: Enable ufw on boot and now
community.general.ufw:
state: enabled
Правило limit вместо привычного allow для SSH — не косметика: UFW начинает блокировать IP, который открывает больше шести соединений за тридцать секунд. Для легитимной административной сессии этого достаточно, для перебора паролей — нет. Порог можно изменить в /etc/ufw/user.rules, но для базовой защиты значения по умолчанию работают предсказуемо.
Отдельное правило для UDP-порта 443 нужно только в том случае, если вы действительно включаете HTTP/3. Если QUIC не используется, правило лишнее и только расширяет поверхность атаки — в таком случае просто уберите задачу из роли.
⚠️ UFW не защищает опубликованные порты Docker
Это ограничение, которое регулярно приводит к утечке баз данных наружу. Docker вставляет свои правила в таблицы nat и filter раньше, чем отрабатывает цепочка UFW, поэтому контейнер с директивой ports: "3306:3306" будет доступен из интернета, несмотря на ufw deny. Ansible здесь не спасает: правило нужно проектировать на уровне docker-compose.yml — привязывать служебные порты к 127.0.0.1 и закрывать доступ через цепочку DOCKER-USER. Разбор этой ловушки с готовыми командами есть в материале о том, как закрыть порты Docker от обхода UFW, а типовой набор правил для веб-сервера можно взять в конфигураторе UFW.
Проверка результата выполняется без входа на сервер — модуль возвращает статус, а расширенный список правил читается отдельной командой:
ansible web -b -m ansible.builtin.command -a 'ufw status verbose'
6. Роль nginx: шаблон конфигурации, validate и перезагрузка без простоя
Роль nginx показывает главное преимущество Ansible над копированием файлов через scp. Модуль ansible.builtin.template не только подставляет переменные, но и способен проверить конфигурацию до того, как она попадет на место:
---
# roles/nginx/tasks/main.yml
- name: Install nginx
ansible.builtin.apt:
name: nginx
state: present
- name: Deploy site configuration
ansible.builtin.template:
src: site.conf.j2
dest: /etc/nginx/sites-available/{{ server_name }}.conf
owner: root
group: root
mode: "0644"
validate: 'nginx -t -c %s'
notify: Reload nginx
- name: Enable site
ansible.builtin.file:
src: /etc/nginx/sites-available/{{ server_name }}.conf
dest: /etc/nginx/sites-enabled/{{ server_name }}.conf
state: link
notify: Reload nginx
- name: Ensure nginx is running and enabled
ansible.builtin.systemd_service:
name: nginx
state: started
enabled: true
Параметр validate запускает указанную команду над временной копией файла и записывает результат на место только при успехе. На практике это означает, что синтаксическая ошибка в шаблоне не уронит веб-сервер: задача завершится со статусом failed, старое содержимое останется нетронутым, а в выводе будет ровно та строка, которую вернул nginx -t.
Шаблон получает переменные из group_vars, поэтому один и тот же файл обслуживает все хосты группы:
# roles/nginx/templates/site.conf.j2
server {
listen 80;
listen [::]:80;
server_name {{ server_name }};
access_log /var/log/nginx/{{ server_name }}.access.log;
error_log /var/log/nginx/{{ server_name }}.error.log warn;
location / {
proxy_pass http://127.0.0.1:{{ app_port }};
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
---
# group_vars/all/main.yml — дополнение к предыдущим переменным
server_name: example.com
app_port: 8080
Обработчик выполняет именно reload, а не restart: Nginx перечитывает конфигурацию без разрыва уже установленных соединений. Если задача не изменила файл, обработчик не запустится вовсе — в выводе прогона такой хост останется со статусом ok, и это ровно то поведение, которого мы добиваемся.
---
# roles/nginx/handlers/main.yml
- name: Reload nginx
ansible.builtin.systemd_service:
name: nginx
state: reloaded
Проверить, что после применения шаблона домен отвечает корректно, можно через анализатор цепочек редиректов — он покажет, не появилось ли лишних переходов между HTTP и HTTPS.
Рекомендуемые VDS-провайдеры
Отказоустойчивые сервера с быстрыми NVMe и каналом до 1 Гбит/с
Timeweb Cloud — Быстрые NVMe VDS для control-ноды
Стабильная control-нода для прогонов плейбуков и ночного дрейф-контроля: высокочастотный процессор, быстрый диск и защита от сетевых атак.
Selectel — Серверы для парка однотипных VDS
Инфраструктура уровня Tier III с предсказуемой сетью и резервированием каналов — удобно, когда под управлением Ansible десятки одинаковых хостов.
Beget — Доступные серверы для тестового контура
Отдельный недорогой сервер под стенд, на котором плейбук обкатывается до раскатки на боевой парк.
7. Роль docker: репозиторий через deb822 и запуск стека без Python SDK
Установка Docker из репозитория Ubuntu (docker.io) дает устаревший движок и не содержит плагина Compose v2. Правильный путь — официальный репозиторий Docker, а начиная с Ubuntu 24.04 его корректнее подключать в формате deb822 через модуль ansible.builtin.deb822_repository, а не через устаревший однострочный add-apt-repository.
---
# roles/docker/tasks/main.yml
- name: Ensure apt keyrings directory exists
ansible.builtin.file:
path: /etc/apt/keyrings
state: directory
owner: root
group: root
mode: "0755"
- name: Download Docker signing key
ansible.builtin.get_url:
url: https://download.docker.com/linux/ubuntu/gpg
dest: /etc/apt/keyrings/docker.asc
owner: root
group: root
mode: "0644"
- name: Add Docker repository
ansible.builtin.deb822_repository:
name: docker
types: deb
uris: https://download.docker.com/linux/ubuntu
suites: "{{ ansible_facts['distribution_release'] }}"
components: stable
architectures: amd64
signed_by: /etc/apt/keyrings/docker.asc
enabled: true
state: present
- name: Install Docker Engine and Compose plugin
ansible.builtin.apt:
name:
- docker-ce
- docker-ce-cli
- containerd.io
- docker-buildx-plugin
- docker-compose-plugin
state: present
update_cache: true
notify: Restart docker
Два технических нюанса, на которых чаще всего спотыкаются. Первый: suites берётся из факта ansible_facts['distribution_release'] и на Ubuntu 24.04 раскроется в noble — жестко прописывать кодовое имя в плейбуке не нужно, иначе при обновлении парка придется править роль. Второй: для этого модуля на целевом хосте обязателен пакет python3-debian, который мы установили в роли common именно ради этой задачи.
Разворачивание самого приложения выполняется модулем community.docker.docker_compose_v2. Важное отличие от старого docker_compose: он не требует Python-библиотеки docker на сервере, потому что работает через CLI-плагин docker compose версии 2.18.0 или новее. Именно поэтому в списке пакетов выше присутствует docker-compose-plugin.
- name: Copy compose project to the server
ansible.builtin.copy:
src: files/app/
dest: /opt/app/
owner: root
group: root
mode: preserve
- name: Bring the stack up
community.docker.docker_compose_v2:
project_src: /opt/app
state: present
pull: always
remove_orphans: true
register: compose_result
- name: Show changed services
ansible.builtin.debug:
msg: "Перезапущены сервисы: {{ compose_result.services | selectattr('state', 'eq', 'running') | map(attribute='name') | join(', ') }}"
when: compose_result.changed
⚠️ Группа docker равна root по правам
Добавление пользователя в группу docker удобно, но означает неограниченный доступ к хосту: участник группы может смонтировать / в контейнер и получить root. Для сборочных агентов и сервисных учетных записей это недопустимо. Если группа все же нужна, добавляйте в нее только администратора, а приложения держите под rootless-режимом Docker или под отдельным пользователем без доступа к сокету.
8. Секреты в репозитории: ansible-vault, no_log и защита ключа
Пароли баз данных, токен бота и приватные ключи не должны попадать в Git в открытом виде. Ansible закрывает эту задачу встроенным шифрованием: файл с секретами лежит рядом с ролями, но в репозиторий уходит только зашифрованный блок.
Создадим ключ шифрования и отдельный файл секретов. Ключ хранится вне репозитория и передается в ansible.cfg:
# Ключ шифрования: 32 байта энтропии, права только для владельца
openssl rand -base64 32 > ~/.ansible/vault.key
chmod 600 ~/.ansible/vault.key
# Создание зашифрованного файла секретов
ansible-vault create group_vars/all/vault.yml --vault-password-file ~/.ansible/vault.key
В открывшемся редакторе вводится содержимое с префиксом vault_, чтобы секреты визуально не путались с обычными переменными:
# содержимое group_vars/all/vault.yml (шифруется целиком)
vault_db_password: "CHANGE_ME_strong_password"
vault_telegram_token: "123456789:AAExampleTokenPlaceholder"
vault_telegram_chat_id: "-1001234567890"
Отдельные значения удобнее шифровать точечно, не открывая весь файл. Команда encrypt_string читает значение из стандартного ввода и возвращает готовый блок, который вставляется в обычный YAML:
ansible-vault encrypt_string --stdin-name 'vault_telegram_token' \
--vault-password-file ~/.ansible/vault.key
Чтобы не указывать флаг при каждом запуске, путь к ключу прописывается в конфигурации проекта:
[defaults]
vault_password_file = ~/.ansible/vault.key
Дополнительно закройте вывод значений в логах прогона. Без no_log Ansible печатает аргументы задач, и токен оказывается в тексте лога или в CI-артефакте:
- name: Send deploy notification to Telegram
ansible.builtin.uri:
url: "https://api.telegram.org/bot{{ vault_telegram_token }}/sendMessage"
method: POST
body_format: json
body:
chat_id: "{{ vault_telegram_chat_id }}"
text: "Плейбук применен на {{ inventory_hostname }}"
no_log: true
changed_when: false
В .gitignore проекта обязательно добавьте ключ шифрования, если он лежит внутри каталога, и любые локальные инвентари с реальными адресами:
vault.key
inventory/hosts.local.yml
*.retry
.ansible/
💡 Ротация ключа без переписывания файлов
Если ключ шифрования попал в чужой доступ, выполните ansible-vault rekey group_vars/all/vault.yml — все значения будут перешифрованы новым паролем, а роли и плейбуки останутся без изменений. Полезно держать в репозитории README с одной строкой о том, где хранится ключ и кто имеет к нему доступ: через полгода это сэкономит время при восстановлении доступа.
9. Прогон по парку: --check, serial и контроль дрейфа конфигурации
Первый запуск любого нового плейбука никогда не выполняется «на все серверы сразу». Порядок действий фиксирован и занимает три команды: проверка синтаксиса, пробный прогон на одном хосте и только затем раскатка на группу.
# 1. Синтаксис YAML и разрешение переменных
ansible-playbook site.yml --syntax-check
# 2. Что именно изменится на одном сервере (без применения)
ansible-playbook site.yml --limit vds-web-1 --check --diff
# 3. Раскатка на всю группу
ansible-playbook site.yml
Режим --check прогоняет задачи без изменений, а --diff показывает построчную разницу в файлах. На практике этого достаточно, чтобы увидеть, что шаблон Nginx заменит три строки, а правило фаервола добавится одно, — до того, как что-то произойдет на боевом сервере.
Второй прогон без изменений — главный тест качества плейбука. В итоговой сводке PLAY RECAP у каждого хоста должно быть changed=0. Если счетчик изменений не нулевой, значит какая-то задача не идемпотентна: чаще всего это ansible.builtin.command без параметра creates или шаблон, в который подставляется текущая дата.
Для обновления сервисов на живом парке используйте параметр serial: Ansible будет обрабатывать хосты порциями и переходить к следующей только после успеха на предыдущей. При балансировке на уровне DNS или внешнего прокси это дает обновление без полного отказа:
---
- name: Rolling update of the web tier
hosts: web
become: true
serial: 1
max_fail_percentage: 0
roles:
- nginx
- docker
Значение max_fail_percentage: 0 останавливает прогон при первой же ошибке, не дожидаясь, пока сломанная конфигурация расползется по остальным хостам. Для парка из десяти серверов это ровно то поведение, которое нужно.
Замыкает плейбук уведомление о результате. Задача выполняется один раз на весь прогон и отправляется с control-ноды, поэтому токен не покидает зашифрованный файл:
- name: Report playbook result to Telegram
hosts: localhost
gather_facts: false
tasks:
- name: Send summary
ansible.builtin.uri:
url: "https://api.telegram.org/bot{{ vault_telegram_token }}/sendMessage"
method: POST
body_format: json
body:
chat_id: "{{ vault_telegram_chat_id }}"
text: "Ansible: прогон завершен. Хостов в группе web: {{ groups['web'] | length }}"
no_log: true
changed_when: false
Регулярная проверка дрейфа превращается в одну строку в планировщике control-ноды: раз в сутки плейбук запускается с --check, и любое расхождение сразу видно в логе и в уведомлении. Готовое выражение для расписания удобно собрать в генераторе crontab, чтобы не ошибиться с полями.
# Дрейф-контроль каждую ночь в 03:30
30 3 * * * cd /home/deploy/ansible-vds && ansible-playbook site.yml --check --diff >> /var/log/ansible-drift.log 2>&1
10. Чек-лист внедрения и типичные ошибки
Перед тем как отдать плейбуку управление боевым парком, сверьтесь с таблицей. Все пункты проверяемы и не требуют доверия на слово.
| Параметр | Рекомендуемое значение | Инженерный смысл |
|---|---|---|
| Источник пакета | pipx install --include-deps ansible |
Изолированное окружение, актуальная версия и полный набор коллекций. |
| Проверка перед применением | --check --diff --limit |
Изменения видны до того, как они затронут боевой сервер. |
| Конфигурация сервисов | validate: 'nginx -t -c %s' |
Битый шаблон не попадает на место рабочего файла. |
| Обновление парка | serial: 1 |
Постепенная раскатка вместо одновременного отказа всех хостов. |
| Секреты | ansible-vault + no_log |
Токены не попадают ни в Git, ни в вывод прогона и CI-логи. |
| Идемпотентность | changed=0 при повторе |
Плейбук можно запускать сколько угодно раз без побочных эффектов. |
Пять ошибок, которые встречаются чаще остальных:
- Установка
ansibleчерезapt. Версия в репозитории Ubuntu отстает, а часть коллекций отсутствует — модульcommunity.docker.docker_compose_v2просто не найдется. - Забытый
python3-debian. Модульdeb822_repositoryпадает с невнятной ошибкой про отсутствующий Python-модуль, хотя проблема в одном пакете. - Фаервол раньше SSH-правила. Политика
denyбез разрешенного порта 22 отрезает доступ к серверу, и восстановить его можно только через консоль хостера. - Порты контейнеров, опубликованные на
0.0.0.0. UFW их не прикрывает: база данных оказывается в интернете, и никакой плейбук этого не заметит. - Секреты в обычных
group_vars. Безansible-vaultтокен бота уходит в историю Git навсегда, даже если позже файл удалить.
После первого успешного прогона полезно проверить парк снаружи: убедиться, что открыты только ожидаемые порты и что сертификаты отдаются корректно. Быстрее всего это делается через проверку портов и анализ SSL-сертификата — без SSH-подключения к каждому хосту.
🖥️ Control-нода должна работать круглосуточно
Плейбук, ночной дрейф-контроль и уведомления живут на отдельном сервере, которому нужны стабильный канал, быстрый диск и предсказуемая память. Для парка из нескольких VDS такой хост удобно держать на тарифе с NVMe и защитой от сетевых атак.