Add service registry, shared roles and unified reverse proxy

Collect the facts about all 14 services -- VMID, node, address, ports, domain, pinned images, resources, backup and monitoring participation -- into group_vars/all/services.yml. Values are taken from the existing playbooks; gaps are marked null rather than invented. Replace reverse-proxy-{gitea,vaultwarden,grimmory}.yml with a single playbook iterating over registry entries that declare a domain. It keeps every check the three had, preserves grimmory's richer Caddy block byte-for-byte, and restarts Caddy once when any site changed instead of up to three times. Verified with --check --diff against ru-vps: ok=6 changed=0, so it reproduces the current Caddyfile exactly. Add two roles factoring out the skeleton duplicated across the pve-* playbooks: lxc_docker_host (packages, /dev/fuse assertion, fuse-overlayfs storage driver, UFW baseline) and compose_service (compose file, systemd unit, config validation, health check). They are not wired into any playbook yet -- migrating a live service is a separate, per-service step; compose_service/README.md shows the Gitea example and spells out what actually changes on the host. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GTocXkGUUazHdKKd3r9k71
2026-08-26 22:10:16 +03:00
parent ec3b736250
commit 9725d3ea7c
15 changed files with 1503 additions and 218 deletions
@@ -0,0 +1,133 @@
+# compose_service
+
+Раскладывает Docker Compose стек и systemd-юнит, который им управляет.
+Обобщение того, что делает `playbooks/pve-grimmory.yml`; такой же по форме
+код продублирован в `roles/monitoring_server` и `roles/uptime_kuma`
+(`grep -rn "up -d --remove-orphans"` — четыре копии одного юнита).
+
+## Что делает
+
+1. Создаёт корневой каталог сервиса и, при необходимости, каталоги данных
+   с нужными owner/group/mode.
+2. Генерирует `.env` **один раз** под `umask 077`: статические пары из
+   `compose_service_env_static` и случайные секреты
+   (`openssl rand -hex`) для имён из `compose_service_env_generated`.
+   Задача целиком под `no_log: true`; права форсируются в `0600`.
+   Повторный прогон существующий `.env` не перетирает — иначе поменялся бы
+   пароль работающей БД.
+3. Кладёт `compose.yml` из inline-строки или из Jinja-шаблона.
+4. Ставит systemd-юнит `Type=oneshot`, `RemainAfterExit=yes`,
+   `ExecStart=docker compose up -d --remove-orphans`,
+   `ExecStop=docker compose down`.
+5. `daemon-reload` через handler + немедленный `meta: flush_handlers`
+   (перечитать юнит надо ДО `systemctl start`, а не в конце play).
+6. Валидирует конфигурацию: `docker compose config --quiet`, `no_log: true`
+   — при ошибке вывод подставляет значения из `.env`.
+7. Стартует сервис, перезапуская его только если изменился `compose.yml`,
+   юнит или сработал внешний триггер (`compose_service_restart_triggers`).
+8. Ждёт health-endpoint через `uri` с `retries`/`until`.
+
+## Переменные
+
+Полный список — в `defaults/main.yml`. Обязательные: `compose_service_name`
+и ровно один из `compose_service_compose_content` /
+`compose_service_compose_template` (проверяется `assert` в начале роли).
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `compose_service_name` | — | имя сервиса и systemd-юнита |
+| `compose_service_root` | `/opt/<name>` | корень стека |
+| `compose_service_compose_content` | `""` | inline `compose.yml` |
+| `compose_service_compose_template` | `""` | путь к Jinja-шаблону |
+| `compose_service_directories` | `[]` | каталоги данных |
+| `compose_service_env_static` | `{}` | пары для `.env` |
+| `compose_service_env_generated` | `[]` | имена случайных секретов |
+| `compose_service_after` / `_requires` | `[]` | доп. юниты в `After=`/`Requires=` |
+| `compose_service_restart_triggers` | `[]` | внешние причины рестарта |
+| `compose_service_health_url` | `""` | URL health-check (пусто — пропустить) |
+
+## Пример использования — как выглядел бы Gitea на новых ролях
+
+`playbooks/pve-gitea.yml` сейчас 231 строка. На ролях `pve_lxc` +
+`lxc_docker_host` + `compose_service` содержательная часть сводится
+примерно к такому (сам стек Gitea пока НЕ мигрирован — это следующий этап):
+
+```yaml
+---
+- name: Create the Gitea LXC on cloud-pc
+  hosts: localhost
+  connection: local
+  gather_facts: false
+  vars:
+    gitea: "{{ homelab_services.gitea }}"
+  roles:
+    - role: pve_lxc
+      pve_lxc_vmid: "{{ gitea.vmid }}"
+      pve_lxc_node: "{{ gitea.node }}"
+      pve_lxc_hostname: "{{ gitea.hostname }}"
+      pve_lxc_ip: "{{ gitea.ip }}/24"
+      pve_lxc_disk: "{{ gitea.lxc.disk }}"
+      pve_lxc_cores: "{{ gitea.lxc.cores }}"
+      pve_lxc_memory: "{{ gitea.lxc.memory }}"
+      pve_lxc_swap: "{{ gitea.lxc.swap }}"
+      pve_lxc_startup: "{{ gitea.lxc.startup }}"
+      pve_lxc_ostemplate: "{{ gitea.lxc.ostemplate }}"
+
+- name: Configure the Gitea service
+  hosts: gitea
+  gather_facts: true
+  vars:
+    gitea: "{{ homelab_services.gitea }}"
+  roles:
+    - role: lxc_docker_host
+      lxc_docker_host_extra_packages: [sqlite3, rsync]
+      lxc_docker_host_ufw_service_rules:
+        - port: "3000"
+          sources: ["{{ homelab_lan_cidr }}", "{{ openvpn_network_cidr }}"]
+        - port: "2222"
+          sources: ["{{ homelab_lan_cidr }}", "{{ openvpn_network_cidr }}"]
+
+    - role: compose_service
+      compose_service_name: gitea
+      compose_service_root: /opt/gitea
+      compose_service_description: Gitea Compose stack
+      compose_service_directories:
+        - {path: /opt/gitea/data, owner: "1000", group: "1000", mode: "0750"}
+      compose_service_env_static:
+        USER_UID: "1000"
+        USER_GID: "1000"
+      compose_service_compose_content: |
+        services:
+          gitea:
+            image: {{ gitea.images[0] }}
+            container_name: gitea
+            environment:
+              USER_UID: "${USER_UID}"
+              USER_GID: "${USER_GID}"
+            ports:
+              - "3000:3000"
+              - "2222:22"
+            volumes:
+              - /opt/gitea/data:/data
+            restart: unless-stopped
+      compose_service_health_url: http://127.0.0.1:3000/api/healthz
+      compose_service_health_retries: 24
+      compose_service_health_delay: 5
+```
+
+Около 30 строк `vars` вместо 231 строки процедурного кода, и все факты
+(vmid, узел, адрес, ресурсы, digest образа) берутся из реестра
+`homelab_services`, а не дублируются в плейбуке.
+
+### Что при такой миграции меняется на живом хосте
+
+Это не чистый рефакторинг, поэтому мигрировать нужно осознанно:
+
+* `docker run` в `ExecStart=` заменяется на compose-стек — контейнер
+  пересоздаётся, юнит `gitea.service` меняет тип на `oneshot`.
+* появляется `/opt/gitea/.env`, которого раньше не было;
+* `--pull never` и явный `docker pull` по digest заменяются на `image:`
+  в compose — политику закрепления образов надо перенести отдельно.
+
+Поэтому перевод существующих сервисов вынесен в отдельный этап и делается
+по одному сервису, с бэкапом и `--check --diff` перед реальным прогоном.
@@ -0,0 +1,70 @@
+---
+# ============================================================================
+# roles/compose_service — раскладка Docker Compose стека + systemd-юнита.
+# Обобщает то, что делает pve-grimmory.yml (compose.yml, .env с секретами,
+# oneshot-юнит, валидация, health-check).
+# ============================================================================
+
+# --- Обязательное ----------------------------------------------------------
+# Имя сервиса. Оно же имя systemd-юнита (<name>.service) и имя каталога
+# по умолчанию. Роль падает с понятным сообщением, если не задано.
+compose_service_name: ""
+
+# Содержимое compose.yml. Ровно один из двух способов:
+#   compose_service_compose_content  — готовая строка (можно собрать в vars);
+#   compose_service_compose_template — путь к Jinja-шаблону в вызывающей роли
+#                                      или в playbooks/templates.
+compose_service_compose_content: ""
+compose_service_compose_template: ""
+
+# --- Раскладка на диске ----------------------------------------------------
+compose_service_root: "/opt/{{ compose_service_name }}"
+compose_service_root_mode: "0750"
+compose_service_owner: root
+compose_service_group: root
+compose_service_compose_file: compose.yml
+compose_service_compose_mode: "0644"
+
+# Дополнительные каталоги данных. Формат:
+#   - {path: /opt/grimmory/data, owner: "1000", group: "1000", mode: "0750"}
+compose_service_directories: []
+
+# --- Файл окружения --------------------------------------------------------
+compose_service_env_path: "{{ compose_service_root }}/.env"
+compose_service_env_mode: "0600"
+
+# Пары ключ-значение, записываемые в .env как есть.
+compose_service_env_static: {}
+# Имена переменных, значения которых генерируются `openssl rand -hex` ОДИН РАЗ.
+# Файл .env создаётся только если его ещё нет: повторный прогон не перетирает
+# уже используемые пароли. Чтобы поменять секрет — удалите .env вручную.
+compose_service_env_generated: []
+compose_service_env_secret_bytes: 32
+
+# Необязательный .env.example для документирования формата (без секретов!).
+compose_service_env_example: ""
+compose_service_env_example_mode: "0644"
+
+# --- systemd ---------------------------------------------------------------
+compose_service_description: "{{ compose_service_name }} Compose stack"
+# Дополнительные юниты в After= / Requires= (docker.service уже включён).
+compose_service_after: []
+compose_service_requires: []
+compose_service_unit_path: "/etc/systemd/system/{{ compose_service_name }}.service"
+compose_service_docker_binary: /usr/bin/docker
+compose_service_enabled: true
+# Дополнительные условия рестарта: список булевых значений от вызывающего
+# (например, результат pull образа).
+compose_service_restart_triggers: []
+
+# --- Валидация и health-check ---------------------------------------------
+# `docker compose config --quiet` перед стартом. Выполняется с no_log,
+# потому что вывод при ошибке может содержать значения из .env.
+compose_service_validate: true
+
+# URL health-check после старта. Пустая строка — проверка пропускается.
+compose_service_health_url: ""
+compose_service_health_status: [200]
+compose_service_health_retries: 24
+compose_service_health_delay: 5
+compose_service_health_follow_redirects: safe
@@ -0,0 +1,7 @@
+---
+# Юнит должен быть перечитан ДО задачи enable/start, поэтому вызывающая роль
+# сразу после установки юнита делает `meta: flush_handlers`.
+- name: Reload systemd for compose services
+  ansible.builtin.systemd:
+    daemon_reload: true
+  listen: compose_service_daemon_reload
@@ -0,0 +1,4 @@
+---
+# Зависимостей у роли нет: подготовка хоста и раскладка стека независимы
+# и подключаются в нужном порядке из плейбука.
+dependencies: []
@@ -0,0 +1,173 @@
+---
+- name: Validate compose_service parameters
+  ansible.builtin.assert:
+    that:
+      - compose_service_name | length > 0
+      - (compose_service_compose_content | length > 0)
+        != (compose_service_compose_template | length > 0)
+    fail_msg: >-
+      Задайте compose_service_name и ровно один из
+      compose_service_compose_content / compose_service_compose_template.
+
+- name: Ensure the service root directory exists
+  ansible.builtin.file:
+    path: "{{ compose_service_root }}"
+    state: directory
+    owner: "{{ compose_service_owner }}"
+    group: "{{ compose_service_group }}"
+    mode: "{{ compose_service_root_mode }}"
+
+- name: Ensure the service data directories exist
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: directory
+    owner: "{{ item.owner | default(compose_service_owner) }}"
+    group: "{{ item.group | default(compose_service_group) }}"
+    mode: "{{ item.mode | default('0750') }}"
+  loop: "{{ compose_service_directories }}"
+  loop_control:
+    label: "{{ item.path }}"
+
+# --- Файл окружения --------------------------------------------------------
+# Создаётся один раз под umask 077. Секреты никогда не попадают в вывод:
+# задача целиком под no_log.
+- name: Generate the environment file once
+  ansible.builtin.shell: |
+    set -eu
+    umask 077
+    if [ -e {{ compose_service_env_path | quote }} ]; then
+      exit 0
+    fi
+    : > {{ compose_service_env_path | quote }}
+    {% for key, value in compose_service_env_static.items() %}
+    printf '%s\n' {{ (key ~ '=' ~ value) | quote }} >> {{ compose_service_env_path | quote }}
+    {% endfor %}
+    {% for key in compose_service_env_generated %}
+    printf '%s=%s\n' {{ key | quote }} "$(openssl rand -hex {{ compose_service_env_secret_bytes }})" >> {{ compose_service_env_path | quote }}
+    {% endfor %}
+    printf created
+  args:
+    executable: /bin/sh
+  register: compose_service_env_result
+  changed_when: compose_service_env_result.stdout == 'created'
+  no_log: true
+  when: >-
+    compose_service_env_static | length > 0 or
+    compose_service_env_generated | length > 0
+
+- name: Enforce the environment file permissions
+  ansible.builtin.file:
+    path: "{{ compose_service_env_path }}"
+    owner: "{{ compose_service_owner }}"
+    group: "{{ compose_service_group }}"
+    mode: "{{ compose_service_env_mode }}"
+  when: >-
+    compose_service_env_static | length > 0 or
+    compose_service_env_generated | length > 0
+
+- name: Install the environment example
+  ansible.builtin.copy:
+    dest: "{{ compose_service_env_path }}.example"
+    owner: "{{ compose_service_owner }}"
+    group: "{{ compose_service_group }}"
+    mode: "{{ compose_service_env_example_mode }}"
+    content: "{{ compose_service_env_example }}"
+  when: compose_service_env_example | length > 0
+
+# --- compose.yml -----------------------------------------------------------
+- name: Install the Compose configuration from inline content
+  ansible.builtin.copy:
+    dest: "{{ compose_service_root }}/{{ compose_service_compose_file }}"
+    owner: "{{ compose_service_owner }}"
+    group: "{{ compose_service_group }}"
+    mode: "{{ compose_service_compose_mode }}"
+    content: "{{ compose_service_compose_content }}"
+  when: compose_service_compose_content | length > 0
+  register: compose_service_compose_inline
+
+- name: Install the Compose configuration from a template
+  ansible.builtin.template:
+    src: "{{ compose_service_compose_template }}"
+    dest: "{{ compose_service_root }}/{{ compose_service_compose_file }}"
+    owner: "{{ compose_service_owner }}"
+    group: "{{ compose_service_group }}"
+    mode: "{{ compose_service_compose_mode }}"
+  when: compose_service_compose_template | length > 0
+  register: compose_service_compose_templated
+
+- name: Record whether the Compose configuration changed
+  ansible.builtin.set_fact:
+    compose_service_compose_changed: >-
+      {{ (compose_service_compose_inline.changed | default(false)) or
+         (compose_service_compose_templated.changed | default(false)) }}
+
+# --- systemd ---------------------------------------------------------------
+- name: Install the systemd unit
+  ansible.builtin.copy:
+    dest: "{{ compose_service_unit_path }}"
+    owner: root
+    group: root
+    mode: "0644"
+    content: |
+      [Unit]
+      Description={{ compose_service_description }}
+      Wants=network-online.target
+      After=network-online.target docker.service{{ (' ' ~ compose_service_after | join(' ')) if compose_service_after else '' }}
+      Requires=docker.service{{ (' ' ~ compose_service_requires | join(' ')) if compose_service_requires else '' }}
+
+      [Service]
+      Type=oneshot
+      RemainAfterExit=yes
+      WorkingDirectory={{ compose_service_root }}
+      ExecStart={{ compose_service_docker_binary }} compose -f {{ compose_service_root }}/{{ compose_service_compose_file }} up -d --remove-orphans
+      ExecStop={{ compose_service_docker_binary }} compose -f {{ compose_service_root }}/{{ compose_service_compose_file }} down
+
+      [Install]
+      WantedBy=multi-user.target
+  register: compose_service_unit
+  notify: compose_service_daemon_reload
+
+- name: Apply the pending systemd daemon reload
+  ansible.builtin.meta: flush_handlers
+
+# --- Валидация -------------------------------------------------------------
+# no_log: сообщение об ошибке `docker compose config` подставляет значения
+# переменных из .env.
+- name: Validate the Compose configuration
+  ansible.builtin.command:
+    argv:
+      - "{{ compose_service_docker_binary }}"
+      - compose
+      - -f
+      - "{{ compose_service_root }}/{{ compose_service_compose_file }}"
+      - config
+      - --quiet
+  args:
+    chdir: "{{ compose_service_root }}"
+  changed_when: false
+  no_log: true
+  when: compose_service_validate
+
+# --- Запуск ----------------------------------------------------------------
+- name: Enable and start the service
+  ansible.builtin.systemd:
+    name: "{{ compose_service_name }}"
+    enabled: "{{ compose_service_enabled }}"
+    state: "{{ 'restarted' if compose_service_needs_restart else 'started' }}"
+  vars:
+    compose_service_needs_restart: >-
+      {{ (compose_service_compose_changed | bool) or
+         (compose_service_unit.changed | default(false)) or
+         (compose_service_restart_triggers | select | list | length > 0) }}
+
+- name: Wait for the service health endpoint
+  ansible.builtin.uri:
+    url: "{{ compose_service_health_url }}"
+    status_code: "{{ compose_service_health_status }}"
+    follow_redirects: "{{ compose_service_health_follow_redirects }}"
+    return_content: false
+  register: compose_service_health
+  retries: "{{ compose_service_health_retries }}"
+  delay: "{{ compose_service_health_delay }}"
+  until: compose_service_health.status in (compose_service_health_status | map('int') | list)
+  when: compose_service_health_url | length > 0