DevOps и инфраструктура 22 мин чтения 2026-10-29

Автоматизация парка VDS с Ansible: единый плейбук для Nginx, UFW, sysctl и Docker вместо ручных SSH-сессий

Практическое руководство по автоматизации нескольких VDS с Ansible 14.5.0 и ansible-core 2.21.5: структура проекта и инвентарь, роли для UFW, sysctl, Nginx и Docker, секреты через ansible-vault, проверка через --check --diff и раскатка с serial без простоя.

Инженерная редакция SysKit Проверено инженерами SysKit.ru

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

Конфигурация
2 vCPU 3.3 ГГц • 4 ГБ RAM • 50 ГБ NVMe • Трафик без лимита
Премиум Tier III
🔷

Selectel — Серверы для парка однотипных VDS

Инфраструктура уровня Tier III с предсказуемой сетью и резервированием каналов — удобно, когда под управлением Ansible десятки одинаковых хостов.

Конфигурация
2 vCPU • 4 ГБ RAM • 60 ГБ NVMe • Защита от DDoS
Быстрый старт
🟠

Beget — Доступные серверы для тестового контура

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

Конфигурация
2 vCPU 3.0 ГГц • 2 ГБ RAM • 30 ГБ NVMe • Бесплатные бэкапы

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 при повторе Плейбук можно запускать сколько угодно раз без побочных эффектов.

Пять ошибок, которые встречаются чаще остальных:

  1. Установка ansible через apt. Версия в репозитории Ubuntu отстает, а часть коллекций отсутствует — модуль community.docker.docker_compose_v2 просто не найдется.
  2. Забытый python3-debian. Модуль deb822_repository падает с невнятной ошибкой про отсутствующий Python-модуль, хотя проблема в одном пакете.
  3. Фаервол раньше SSH-правила. Политика deny без разрешенного порта 22 отрезает доступ к серверу, и восстановить его можно только через консоль хостера.
  4. Порты контейнеров, опубликованные на 0.0.0.0. UFW их не прикрывает: база данных оказывается в интернете, и никакой плейбук этого не заметит.
  5. Секреты в обычных group_vars. Без ansible-vault токен бота уходит в историю Git навсегда, даже если позже файл удалить.

После первого успешного прогона полезно проверить парк снаружи: убедиться, что открыты только ожидаемые порты и что сертификаты отдаются корректно. Быстрее всего это делается через проверку портов и анализ SSL-сертификата — без SSH-подключения к каждому хосту.

🖥️ Control-нода должна работать круглосуточно

Плейбук, ночной дрейф-контроль и уведомления живут на отдельном сервере, которому нужны стабильный канал, быстрый диск и предсказуемая память. Для парка из нескольких VDS такой хост удобно держать на тарифе с NVMe и защитой от сетевых атак.

Инструменты SysKit по теме статьи

Бесплатные утилиты для проверки и диагностики вашего сервера

Вопросы и ответы (FAQ)

Популярные вопросы вебмастеров и сисадминов по данной теме

Чем ansible-core отличается от пакета ansible и что ставить на control-ноду?
ansible-core — это минимальное ядро с движком и встроенными модулями (актуальная версия 2.21.5). Пакет ansible версии 14.5.0 ставит это же ядро и добавляет полный набор коллекций: community.general, community.docker, ansible.posix. Для практической работы с UFW, Docker Compose и sysctl нужен именно community-пакет: модули community.general.ufw и community.docker.docker_compose_v2 в голое ядро не входят. Устанавливайте через pipx install --include-deps ansible — на Ubuntu 24.04 прямой pip install в системный Python блокируется механизмом PEP 668.
Почему UFW не закрывает порты Docker-контейнеров и как это исправить через Ansible?
Docker вставляет собственные правила в таблицы nat и filter раньше, чем применяется цепочка UFW, поэтому контейнер с директивой ports: "3306:3306" доступен из интернета даже при политике deny. Ansible это не исправляет: проблема решается на уровне docker-compose.yml — служебные порты публикуются только на 127.0.0.1, а внешний доступ закрывается правилами в цепочке DOCKER-USER. Проверить результат можно модулем ansible.builtin.command с командой ufw status verbose и внешним сканированием портов.
Как прогнать плейбук на боевом парке серверов без простоя?
Последовательность из трех шагов: ansible-playbook site.yml --syntax-check, затем ansible-playbook site.yml --limit vds-web-1 --check --diff на одном хосте, и только после этого полный прогон. Для обновления ролей на живом парке задайте в play параметр serial: 1 — Ansible обработает хосты по одному, а max_fail_percentage: 0 остановит прогон при первой ошибке. Конфигурации сервисов защищает параметр validate у модуля template: битый шаблон не попадет на место рабочего файла.

Читайте также в блоге SysKit

Смежные руководства и полезные технические статьи