Ansible Controller

Каркас для деплоя ПО на удалённые машины через Ansible: плейбуки, переменные хостов, скрипты (tools/), Makefile-обёртки и REST-демон для оркестрации локальных запусков ansible-playbook.

Полная документация: docs/README.md. Для AI-агентов: AGENTS.md.

Требования

Компонент	Назначение
Ansible + ansible-galaxy	Запуск плейбуков и установка ролей
uv	Создаётся через make prepare
fzf	Интерактивный выбор хостов в make (brew install fzf)
GNU readlink	Для set-vars.sh на macOS (brew install coreutils)

Быстрый старт

make prepare
. ./tools/set-vars.sh
./tools/get-roles.sh traefik server-common

| Таргет | Описание |
|--------|----------|
| `prepare` | uv, `.venv`, зависимости демона |
| `daemon` | REST API (Swagger: `/docs`) |
| `sshconfig` | SSH config на localhost |
| `docker-services` | Деплой docker-services |
| `traefik` | Деплой Traefik |

`fzf` нужен только если `HOST` не задан. Скрытые каталоги в `host_vars/` (`.examples` и т.п.) не попадают в выбор.

```bash
make daemon
DAEMON_HOST=0.0.0.0 DAEMON_PORT=9000 make daemon

make docker-services                                    # fzf
HOST=ru01.example.com make traefik
HOST=ru01.example.com,us03.example.com make docker-services

export HOST=router.example.com
make traefik

Список хостов: ./tools/nodes_list.sh.

Плейбуки

Каталоги: backups, configuration, databases, exporters, logs, monitoring, services, utils, vpns.

Типичный плейбук — один run-*.yml на одну Galaxy-роль:

#!/usr/bin/env -S ansible-playbook -e @vars/extra.yaml
---
- name: Configure target servers
  hosts: traefik
  roles:
    - { role: sorrowless.traefik, tags: ['traefik'] }

Композитные стеки — в корне playbooks/ как run-*-full.yml (19 файлов), например run-minimal-full.yml, run-mail-full.yml:

- name: Ensure TLS certificates
  import_playbook: services/run-tls.yml

./playbooks/run-minimal-full.yml -l myhost.example.com --tags common
find playbooks -name 'run-*.yml' | sort

Каталог: docs/reference/playbooks-catalog.md.

Переменные и vault

. ./tools/set-vars.sh    # become + vault (+ mitogen если установлен)

Плейбуки подключают vars/extra.yaml. Vault: tools/get-vault-pass через ansible.cfg.

Примеры host vars: host_vars/.examples/.

Ускорение: mitogen

ansible-playbook tools/switch-to-mitogen.yml
. ./tools/set-vars.sh

См. docs/reference/roles-lists.md.

Make

make help

Таргет	Описание
prepare	uv, .venv, зависимости демона
daemon	REST API (Swagger: /docs)
sshconfig	SSH config на localhost
docker-services	Деплой docker-services
traefik	Деплой Traefik

fzf нужен только если HOST не задан. Скрытые каталоги в host_vars/ (.examples и т.п.) не попадают в выбор.

make daemon
DAEMON_HOST=0.0.0.0 DAEMON_PORT=9000 make daemon

make docker-services                                    # fzf
HOST=ru01.example.com make traefik
HOST=ru01.example.com,us03.example.com make docker-services

export HOST=router.example.com
make traefik

Список хостов: ./tools/nodes_list.sh.

Плейбуки

Каталоги: backups, configuration, databases, exporters, logs, monitoring, services, utils, vpns.

Типичный плейбук — один run-*.yml на одну Galaxy-роль:

API и curl-примеры: daemon/readme.md, docs/guides/provisioner-daemon.md.

CI

Скрипт tools/ci-script.py анализирует git diff, скачивает роли и генерирует ansible-команды. Маппинг vars → playbooks: tools/ci-config.yml.

python tools/ci-script.py --preview --target_branch main
python tools/ci-script.py --apply --target_branch main

Пример маппинга в ci-config.yml:

20beb2b6f218fd14db6e92ac00a48170d021b9a7

mappings:
  scrape_configs_*.yml:
    playbooks/monitoring/run-vmagent.yml: {}

  docker.yml:
    playbooks/services/run-docker.yml:
      priority: 30

См. docs/guides/ci-automation.md.

Примеры сценариев

Сценарий	Документ
Минимальный сервер	docs/examples/minimal-server.md
Traefik	docs/examples/traefik-deploy.md
Мониторинг	docs/examples/monitoring-stack.md

Лицензия

Apache 2.0

Автор

Stan Bogatkin