refactor(ansible): разложить репозиторий по схеме Ansible

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
karpenokandCursor committed 2026-11-08 01:13:36 +07:00
1 parent a23232ac1c
commit 27f15e7bc7
23 files changed
+277 -242

No files matched your search

+24 -20
View File
@@ -30,10 +30,10 @@ jobs:
if [ "$(id -u)" -eq 0 ]; then if [ "$(id -u)" -eq 0 ]; then
apt-get update apt-get update
apt-get install -y git openssh-client ansible-core apt-get install -y git openssh-client ansible-core python3
else else
sudo apt-get update sudo apt-get update
sudo apt-get install -y git openssh-client ansible-core sudo apt-get install -y git openssh-client ansible-core python3
fi fi
rm -rf /tmp/homelab-infra rm -rf /tmp/homelab-infra
@@ -47,24 +47,28 @@ jobs:
printf '%s\n' "${RUNNER_SSH_KEY}" > "${HOME}/.ssh/id_ed25519" printf '%s\n' "${RUNNER_SSH_KEY}" > "${HOME}/.ssh/id_ed25519"
chmod 600 "${HOME}/.ssh/id_ed25519" chmod 600 "${HOME}/.ssh/id_ed25519"
inventory=/tmp/homelab-infra/inventory/hosts.ini cd /tmp/homelab-infra
target=$(awk '{ ansible-inventory -i inventories/prod/hosts.yml --list > /tmp/inventory.json
for (i = 1; i <= NF; i++) { python3 - <<'PY'
if ($i ~ /^ansible_host=/) { import json, subprocess
split($i, a, "=") data = json.load(open("/tmp/inventory.json"))
print a[2] hosts = data.get("netbird", {}).get("hosts", [])
exit hostvars = data.get("_meta", {}).get("hostvars", {})
} targets = []
} for name in hosts:
}' "${inventory}") address = hostvars.get(name, {}).get("ansible_host")
if [ -z "${target}" ]; then if not address:
echo "В inventory/hosts.ini нет ansible_host." >&2 raise SystemExit(f"У {name} нет ansible_host")
exit 1 targets.append(address)
fi if not targets:
echo "Цель из inventory: ${target}" raise SystemExit("В группе netbird нет машин")
ssh-keyscan -H "${target}" >> "${HOME}/.ssh/known_hosts" print("Цели из inventory:", ", ".join(targets))
for address in targets:
subprocess.check_call(["ssh-keyscan", "-H", address], stdout=open(f"{__import__('os').environ['HOME']}/.ssh/known_hosts", "a"))
PY
ansible-playbook /tmp/homelab-infra/services/netbird/playbook.yml \ ansible-playbook playbooks/site.yml \
-i "${inventory}" \ -i inventories/prod/hosts.yml \
--limit netbird \
--private-key "${HOME}/.ssh/id_ed25519" \ --private-key "${HOME}/.ssh/id_ed25519" \
-e "netbird_letsencrypt_email=${NETBIRD_LETSENCRYPT_EMAIL}" -e "netbird_letsencrypt_email=${NETBIRD_LETSENCRYPT_EMAIL}"
+17 -7
View File
@@ -19,15 +19,25 @@
## Как устроена доставка ## Как устроена доставка
Три слоя, и у каждого своё место. Не смешивать их в одном файле. Схема из документации Ansible. Другую не выдумывать.
1. **Хост один на всех.** Плейбук `playbooks/host.yml` готовит любую машину: Docker, базовый firewall, каталоги. Новый VPS попадает в inventory и получает этот плейбук. Задачи хоста не копируются внутрь сервиса. ```
2. **Сервис один на всех хостов, где он нужен.** Каталог `services/<имя>/` хранит Compose и шаблоны. Плейбук `playbooks/<имя>.yml` только доставляет этот сервис и в начале подключает плейбук хоста. Сотня сервисов — сотня таких пар, не сотня описаний машин. inventories/prod/hosts.yml # машины и группы: home, vps и группа сервиса
3. **Кто где стоит — только inventory.** Имя хоста, группа и публичный домен сервиса лежат в `inventory/` и `group_vars/`. Compose, шаблоны и workflow получают их переменными. Не хардкодить адрес и домен в манифесте. inventories/prod/group_vars/ # значения группы. Домен сервиса лежит здесь
inventories/prod/host_vars/ # исключение одной машины, если оно нужно
roles/host/ # подготовка любой машины
roles/<сервис>/ # доставка одного сервиса
playbooks/host.yml
playbooks/<сервис>.yml
playbooks/site.yml # сначала все машины, затем сервисы на свои группы
```
Gitea Actions запускает `ansible-playbook`. Сценарий не ставит пакеты, не правит firewall и не описывает контейнеры. Shell-скрипт не заменяет плейбук. - `ansible_host` в `hosts.yml` — адрес подключения. Не DNS-имя: домашний DNS может подменить имя.
- Роль `host` не копировать в сервис. `site.yml` запускает её до сервисов.
Шаблоны Ansible — `*.j2`. Секреты по-прежнему не в git: только `${VAR}` в Compose и плейсхолдеры в шаблонах. - В роли `host` только общее: Docker и SSH. Порты сервиса и Compose — в роли сервиса.
- Gitea Actions выполняет `ansible-playbook playbooks/site.yml -i inventories/prod/hosts.yml --limit <группа>`. В сценарии нет адресов и имён машин.
- Новая машина — строка в `hosts.yml`. Новый сервис — роль и группа. Не описание машины.
- Шаблоны Ansible — `*.j2`. Секреты не в git.
## Технические стандарты ## Технические стандарты
+8 -9
View File
@@ -14,20 +14,19 @@
``` ```
homelab-infra/ homelab-infra/
├── AGENTS.md # правила для AI-агентов ├── inventories/prod/ # машины, группы площадок и сервисов
├── docs/ ├── roles/host/ # подготовка любой машины
│ └── netbird/ # архитектура NetBird ├── roles/netbird/ # панель NetBird
├── services/ ├── playbooks/ # host.yml, netbird.yml, site.yml
│ └── netbird/ # манифесты management, signal, relay, dashboard ├── docs/netbird/
└── .gitea/ └── .gitea/workflows/
└── workflows/ # пайплайны Gitea Actions
``` ```
Новый сервис — это каталог `services/<имя>/` и, когда решение уже принято, страница в `docs/<имя>/`. Привязка к конкретному хосту появляется в манифесте только там, где без неё нельзя доставить сервис. Новая машина — строка в `inventories/prod/hosts.yml`. Новый сервис — роль `roles/<имя>/` и плейбук `playbooks/<имя>.yml`. Адрес подключения и домен в роли не пишутся.
## Сейчас ## Сейчас
Панель NetBird описана в `services/netbird/` и ставится сценарием `.gitea/workflows/netbird-install.yml` на `central.gunihome.ru`. Состав и решения — в `docs/netbird/design.md`. Панель NetBird — роль `roles/netbird`. Куда её ставить, написано в `inventories/prod/hosts.yml`, группа `netbird`. Запуск — `.gitea/workflows/netbird-install.yml`. Состав сервиса — в `docs/netbird/design.md`.
## Ресурсы ## Ресурсы
+5
View File
@@ -0,0 +1,5 @@
[defaults]
inventory = inventories/prod/hosts.yml
roles_path = roles
retry_files_enabled = false
stdout_callback = yaml
+4 -4
View File
@@ -1,12 +1,12 @@
# NetBird: архитектура overlay-сети # NetBird: архитектура overlay-сети
Статус: **установка панели**. Хост — `central.gunihome.ru`. Эталон файлов лежит в `services/netbird/`. Статус: **установка панели**. Роль — `roles/netbird`. Машина и домен — в `inventories/prod`.
## Задача ## Задача
NetBird — транспортный фундамент новой инфраструктуры. Новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в overlay и только потом получает сервисы. NetBird — транспортный фундамент новой инфраструктуры. Новый хост (VPS, LXC, ВМ, ноутбук) сначала вступает в overlay и только потом получает сервисы.
Сервис не привязан к имени будущей машины. Меняется хост — меняется цель доставки, состав `services/netbird/` остаётся тем же. Сервис не привязан к имени машины. Меняется хост — меняется строка в inventory, роль `roles/netbird/` остаётся той же.
## Компоненты ## Компоненты
@@ -17,7 +17,7 @@ NetBird — транспортный фундамент новой инфрас
| Traefik v3.7.14 | сертификат Let's Encrypt и маршрутизация | 80/tcp, 443/tcp | | Traefik v3.7.14 | сертификат Let's Encrypt и маршрутизация | 80/tcp, 443/tcp |
| Встроенный вход | пользователи панели без отдельного Zitadel | — | | Встроенный вход | пользователи панели без отдельного Zitadel | — |
Манифесты живут в `services/netbird/` и доставляются сценарием Gitea Actions. Официальный установщик — ориентир по составу контейнеров, не способ запуска. Манифесты живут в `roles/netbird/` и доставляются сценарием Gitea Actions. Официальный установщик — ориентир по составу контейнеров, не способ запуска.
## Требования к VPS ## Требования к VPS
@@ -56,7 +56,7 @@ Overlay NetBird — `100.64.0.0/10`.
## Развёртывание ## Развёртывание
1. Цель доставки — `central.gunihome.ru`. Отдельного каталога хоста нет. 1. Цель доставки — `central.gunihome.ru`. Отдельного каталога хоста нет.
2. Сценарий `netbird-install` запускает плейбук `services/netbird/playbook.yml`. Плейбук ставит Docker, открывает порты из таблицы выше и поднимает панель. 2. Сценарий `netbird-install` запускает `playbooks/site.yml` с ограничением на группу `netbird`. Роль `host` ставит Docker, роль `netbird` открывает порты панели и поднимает её.
3. Сертификат выпускает Traefik. Первый администратор создаётся на `/setup`. 3. Сертификат выпускает Traefik. Первый администратор создаётся на `/setup`.
4. Группы и политики из этого документа задаются уже в панели. 4. Группы и политики из этого документа задаются уже в панели.
5. Первый пир — рабочая станция. Проверка: пинг по overlay-адресу и SSH на management по адресу NetBird. 5. Первый пир — рабочая станция. Проверка: пинг по overlay-адресу и SSH на management по адресу NetBird.
+3
View File
@@ -0,0 +1,3 @@
---
# Общий слой переменных площадки prod.
# Адрес подключения здесь не хранится: он лежит в hosts.yml как ansible_host.
+2
View File
@@ -0,0 +1,2 @@
# Публичное имя сервиса. На какой машине он стоит, задаёт группа netbird в hosts.yml.
netbird_domain: central.gunihome.ru
+14
View File
@@ -0,0 +1,14 @@
# Канонический inventory: где машина и чем она является.
# ansible_host — адрес подключения. Это не DNS-имя: домашний DNS может его подменить.
all:
children:
home:
hosts: {}
vps:
hosts:
rus-central:
ansible_host: 45.154.185.208
ansible_user: root
netbird:
hosts:
rus-central:
-3
View File
@@ -1,3 +0,0 @@
# Публичное имя панели. Его видят браузер и сертификат.
# На какой машине она стоит — в inventory/hosts.ini, не здесь.
netbird_domain: central.gunihome.ru
-5
View File
@@ -1,5 +0,0 @@
# Единственное место, где записан адрес машины.
# Сменился IP — меняется ansible_host здесь, сценарии не трогаются.
[netbird]
vps ansible_host=45.154.185.208 ansible_user=root
+7
View File
@@ -0,0 +1,7 @@
---
# Подготовка любой машины из inventory. Сервисы эту роль не копируют, а подключают.
- name: Подготовить машину
hosts: all
gather_facts: false
roles:
- host
+7
View File
@@ -0,0 +1,7 @@
---
# Только панель. Подготовка машины — роль host в playbooks/host.yml.
- name: Установить панель NetBird
hosts: netbird
gather_facts: false
roles:
- netbird
+4
View File
@@ -0,0 +1,4 @@
---
# Полный прогон площадки: все машины, затем каждый сервис на свою группу.
- ansible.builtin.import_playbook: host.yml
- ansible.builtin.import_playbook: netbird.yml
+39
View File
@@ -0,0 +1,39 @@
---
- name: Подготовить Python для Ansible
ansible.builtin.raw: DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-apt
changed_when: false
- name: Собрать факты
ansible.builtin.setup:
- name: Поставить Docker
ansible.builtin.apt:
name:
- docker.io
- docker-compose-v2
- ufw
- ca-certificates
- curl
state: present
update_cache: true
- name: Включить Docker
ansible.builtin.systemd:
name: docker
enabled: true
state: started
- name: Разрешить SSH
ansible.builtin.command: ufw allow OpenSSH
register: ufw_ssh
changed_when: "'added' in (ufw_ssh.stdout | lower)"
- name: Проверить состояние firewall
ansible.builtin.command: ufw status
register: ufw_status
changed_when: false
- name: Включить firewall
ansible.builtin.command: ufw --force enable
when: "'Status: active' not in ufw_status.stdout"
changed_when: true
+6
View File
@@ -0,0 +1,6 @@
---
netbird_dir: /opt/netbird
netbird_ports:
- 80/tcp
- 443/tcp
- 3478/udp
File renamed without changes.
File renamed without changes.
+134
View File
@@ -0,0 +1,134 @@
---
- name: Разрешить порты панели
ansible.builtin.command: ufw allow {{ item }}
register: ufw_rule
changed_when: "'added' in (ufw_rule.stdout | lower)"
loop: "{{ netbird_ports }}"
- name: Поставить openssl
ansible.builtin.apt:
name: openssl
state: present
- name: Создать каталог панели
ansible.builtin.file:
path: "{{ netbird_dir }}"
state: directory
owner: root
group: root
mode: "0700"
- name: Проверить, созданы ли уже ключи
ansible.builtin.stat:
path: "{{ netbird_dir }}/.env"
register: netbird_env
- name: Проверить почту Let's Encrypt
ansible.builtin.assert:
that:
- netbird_letsencrypt_email is defined
- netbird_letsencrypt_email | length > 3
fail_msg: Укажите почту Let's Encrypt при запуске плейбука.
when: not netbird_env.stat.exists
- name: Сгенерировать ключи панели
ansible.builtin.shell: openssl rand -base64 32 | tr -d '\n'
register: netbird_generated_keys
changed_when: false
no_log: true
loop:
- auth
- datastore
- session
when: not netbird_env.stat.exists
- name: Запомнить новые ключи
ansible.builtin.set_fact:
netbird_auth_secret: "{{ netbird_generated_keys.results[0].stdout }}"
netbird_datastore_key: "{{ netbird_generated_keys.results[1].stdout }}"
netbird_session_key: "{{ netbird_generated_keys.results[2].stdout }}"
no_log: true
when: not netbird_env.stat.exists
- name: Прочитать сохранённые ключи
ansible.builtin.slurp:
src: "{{ netbird_dir }}/.env"
register: netbird_env_raw
no_log: true
when: netbird_env.stat.exists
- name: Разобрать сохранённые ключи
ansible.builtin.set_fact:
netbird_auth_secret: "{{ env_map['NETBIRD_AUTH_SECRET'] }}"
netbird_datastore_key: "{{ env_map['NETBIRD_DATASTORE_KEY'] }}"
netbird_session_key: "{{ env_map['NETBIRD_SESSION_KEY'] }}"
netbird_letsencrypt_email: "{{ env_map['NETBIRD_LETSENCRYPT_EMAIL'] }}"
vars:
env_lines: "{{ (netbird_env_raw.content | b64decode).splitlines() | reject('equalto', '') | list }}"
env_map: "{{ dict(env_lines | map('split', '=', 1)) }}"
no_log: true
when: netbird_env.stat.exists
- name: Записать .env
ansible.builtin.template:
src: env.j2
dest: "{{ netbird_dir }}/.env"
owner: root
group: root
mode: "0600"
no_log: true
when: not netbird_env.stat.exists
- name: Положить манифест панели
ansible.builtin.copy:
src: compose.yaml
dest: "{{ netbird_dir }}/compose.yaml"
owner: root
group: root
mode: "0644"
- name: Собрать dashboard.env
ansible.builtin.template:
src: dashboard.env.j2
dest: "{{ netbird_dir }}/dashboard.env"
owner: root
group: root
mode: "0644"
- name: Собрать config.yaml
ansible.builtin.template:
src: config.yaml.j2
dest: "{{ netbird_dir }}/config.yaml"
owner: root
group: root
mode: "0600"
no_log: true
- name: Поднять панель
ansible.builtin.command: docker compose up -d
args:
chdir: "{{ netbird_dir }}"
register: compose_up
changed_when: "'Started' in compose_up.stderr or 'Created' in compose_up.stderr or 'Recreated' in compose_up.stderr"
- name: Показать состояние контейнеров
ansible.builtin.command: docker compose ps
args:
chdir: "{{ netbird_dir }}"
register: compose_ps
changed_when: false
- name: Дождаться ответа панели
ansible.builtin.command: >
curl -sk --resolve {{ netbird_domain }}:443:127.0.0.1
-o /dev/null -w '%{http_code}'
https://{{ netbird_domain }}/
register: panel_http
changed_when: false
retries: 30
delay: 10
until: panel_http.stdout in ['200', '302']
- name: Итог установки
ansible.builtin.debug:
msg: "{{ compose_ps.stdout_lines + ['Первый вход: https://' + netbird_domain + '/setup'] }}"
File renamed without changes.
+3 -16
View File
@@ -1,18 +1,5 @@
# services/netbird # NetBird
Эталон панели NetBird `0.82.0` для `https://central.gunihome.ru`. Роль: `roles/netbird`. Плейбук: `playbooks/netbird.yml`.
Установку делает Ansible-плейбук `playbook.yml`. Сценарий Gitea Actions только запускает его. Состав контейнеров совпадает с официальным установщиком релиза v0.82.0: `netbird-server`, панель и Traefik. Адрес машины и имя сайта здесь не хранятся. Они лежат в `inventories/prod/hosts.yml` и `inventories/prod/group_vars/netbird.yml`.
| Файл | Назначение |
| --- | --- |
| `playbook.yml` | Плейбук: пакеты, firewall, ключи, запуск панели |
| `compose.yaml` | Сервисы, порты `80/tcp`, `443/tcp`, `3478/udp` |
| `templates/config.yaml.j2` | Шаблон сервера. Ключи подставляет плейбук |
| `templates/env.j2` | Шаблон `.env` для Compose |
| `templates/dashboard.env.j2` | Адреса панели. Имя берётся из `inventory/group_vars/netbird.yml` |
| `.env.example` | Имена переменных без значений |
`.env` и готовый `config.yaml` остаются на хосте в `/opt/netbird`. В git их нет. Повторный прогон не пересоздаёт ключи и не удаляет тома `netbird_data` и `netbird_traefik_letsencrypt`.
Кнопка запуска — сценарий `.gitea/workflows/netbird-install.yml`. В его журнале виден вывод плейбука: каждая задача отдельной строкой. После зелёного прогона первый администратор создаётся в браузере на `https://central.gunihome.ru/setup`.
-178
View File
@@ -1,178 +0,0 @@
---
# Плейбук панели NetBird. Его запускает сценарий Gitea Actions.
# Повторный прогон не пересоздаёт ключи и не удаляет данные панели.
- name: Установить панель NetBird
hosts: netbird
gather_facts: false
vars:
netbird_dir: /opt/netbird
tasks:
- name: Подготовить Python для Ansible
ansible.builtin.raw: DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y python3 python3-apt
changed_when: false
- name: Собрать факты
ansible.builtin.setup:
- name: Поставить Docker и firewall
ansible.builtin.apt:
name:
- docker.io
- docker-compose-v2
- ufw
- openssl
- ca-certificates
- curl
state: present
update_cache: true
- name: Включить Docker
ansible.builtin.systemd:
name: docker
enabled: true
state: started
- name: Разрешить порты панели
ansible.builtin.command: ufw allow {{ item }}
register: ufw_rule
changed_when: "'added' in (ufw_rule.stdout | lower)"
loop:
- OpenSSH
- 80/tcp
- 443/tcp
- 3478/udp
- name: Проверить состояние firewall
ansible.builtin.command: ufw status
register: ufw_status
changed_when: false
- name: Включить firewall
ansible.builtin.command: ufw --force enable
when: "'Status: active' not in ufw_status.stdout"
changed_when: true
- name: Создать каталог панели
ansible.builtin.file:
path: "{{ netbird_dir }}"
state: directory
owner: root
group: root
mode: "0700"
- name: Проверить, созданы ли уже ключи
ansible.builtin.stat:
path: "{{ netbird_dir }}/.env"
register: netbird_env
- name: Проверить почту Let's Encrypt
ansible.builtin.assert:
that:
- netbird_letsencrypt_email is defined
- netbird_letsencrypt_email | length > 3
fail_msg: Укажите почту Let's Encrypt при запуске плейбука.
when: not netbird_env.stat.exists
- name: Сгенерировать ключи панели
ansible.builtin.shell: openssl rand -base64 32 | tr -d '\n'
register: netbird_generated_keys
changed_when: false
no_log: true
loop:
- auth
- datastore
- session
when: not netbird_env.stat.exists
- name: Запомнить новые ключи
ansible.builtin.set_fact:
netbird_auth_secret: "{{ netbird_generated_keys.results[0].stdout }}"
netbird_datastore_key: "{{ netbird_generated_keys.results[1].stdout }}"
netbird_session_key: "{{ netbird_generated_keys.results[2].stdout }}"
no_log: true
when: not netbird_env.stat.exists
- name: Прочитать сохранённые ключи
ansible.builtin.slurp:
src: "{{ netbird_dir }}/.env"
register: netbird_env_raw
no_log: true
when: netbird_env.stat.exists
- name: Разобрать сохранённые ключи
ansible.builtin.set_fact:
netbird_auth_secret: "{{ env_map['NETBIRD_AUTH_SECRET'] }}"
netbird_datastore_key: "{{ env_map['NETBIRD_DATASTORE_KEY'] }}"
netbird_session_key: "{{ env_map['NETBIRD_SESSION_KEY'] }}"
netbird_letsencrypt_email: "{{ env_map['NETBIRD_LETSENCRYPT_EMAIL'] }}"
vars:
env_lines: "{{ (netbird_env_raw.content | b64decode).splitlines() | reject('equalto', '') | list }}"
env_map: "{{ dict(env_lines | map('split', '=', 1)) }}"
no_log: true
when: netbird_env.stat.exists
- name: Записать .env
ansible.builtin.template:
src: env.j2
dest: "{{ netbird_dir }}/.env"
owner: root
group: root
mode: "0600"
no_log: true
when: not netbird_env.stat.exists
- name: Положить манифест панели
ansible.builtin.copy:
src: "{{ playbook_dir }}/compose.yaml"
dest: "{{ netbird_dir }}/compose.yaml"
owner: root
group: root
mode: "0644"
- name: Собрать dashboard.env
ansible.builtin.template:
src: dashboard.env.j2
dest: "{{ netbird_dir }}/dashboard.env"
owner: root
group: root
mode: "0644"
- name: Собрать config.yaml
ansible.builtin.template:
src: config.yaml.j2
dest: "{{ netbird_dir }}/config.yaml"
owner: root
group: root
mode: "0600"
no_log: true
- name: Поднять панель
ansible.builtin.command: docker compose up -d
args:
chdir: "{{ netbird_dir }}"
register: compose_up
changed_when: "'Started' in compose_up.stderr or 'Created' in compose_up.stderr or 'Recreated' in compose_up.stderr"
- name: Показать состояние контейнеров
ansible.builtin.command: docker compose ps
args:
chdir: "{{ netbird_dir }}"
register: compose_ps
changed_when: false
- name: Дождаться ответа панели
ansible.builtin.command: >
curl -sk --resolve {{ netbird_domain }}:443:127.0.0.1
-o /dev/null -w '%{http_code}'
https://{{ netbird_domain }}/
register: panel_http
changed_when: false
retries: 30
delay: 10
until: panel_http.stdout in ['200', '302']
- name: Итог установки
ansible.builtin.debug:
msg: "{{ compose_ps.stdout_lines + ['Первый вход: https://' + netbird_domain + '/setup'] }}"