Правки различные

2026-08-26 11:05:32 +03:00
parent c1e49fb15d
commit 728b9826a3
36 changed files with 722 additions and 1986 deletions
@@ -0,0 +1,407 @@
+# Runbook развёртывания SigNoz (ВМ3)
+
+Это единственный исполняемый runbook раскатки self-hosted SigNoz для HAN Chat.
+Команды выполняет оператор; repository automation их не запускает.
+
+ВМ3 — private/no-egress узел по
+[`arch-06-service-hosting-security.md`](../../../architectory/arch-06-service-hosting-security.md):
+после приёмки нет internet ingress, нет постоянного internet egress, UI не
+публикуется, OTLP доступен только из приватной сети. Раскатка не завершена,
+пока не закрыт lockdown и обе группы проверок (снаружи и из private network).
+
+Эксплуатация UI, разбор инцидентов и алерты — в
+[`SIGNOZ_RUNBOOK.md`](SIGNOZ_RUNBOOK.md). Подключение приложений —
+[`BACKEND_OTLP.md`](BACKEND_OTLP.md). Сеть и группы безопасности —
+[`NETWORK.md`](NETWORK.md).
+
+## 0. Назначение, инвентарь и stop conditions
+
+Каталог репозитория: `HAN_chat_specification/VM3_signoz/Signoz/`.
+Рабочий каталог на ВМ: `/opt/signoz`. Compose Foundry создаёт в
+`pours/deployment/compose.yaml`; этот каталог принадлежит runtime ВМ и не
+хранится в git.
+
+Текущее окружение (подставьте актуальные значения, если они изменились):
+
+| Узел | Публичный IP | Приватный IP |
+|---|---|---|
+| ВМ1 HAN Chat (jump) | `135.106.164.58` | `192.168.0.1` |
+| ВМ2 Processing | — | `192.168.0.4` |
+| ВМ3 SigNoz | `135.106.166.7` только на bootstrap | `192.168.0.5` |
+
+Порты:
+
+- OTLP/gRPC: `192.168.0.5:4317` — основной ingest ВМ1 и ВМ2;
+- OTLP/HTTP: `192.168.0.5:4318` — диагностика, после приёмки можно закрыть;
+- UI/API: `127.0.0.1:8080` на ВМ3, доступ только через SSH-туннель;
+- ClickHouse `8123/9000`, PostgreSQL `5432`, ClickHouse Keeper `9181` наружу
+  не публикуются.
+
+SSH-ключи (не коммитьте private keys):
+
+- jump/ВМ1: `C:\Users\MI\.ssh\hansel`;
+- приватный вход на ВМ3: `C:\Users\MI\.ssh\hansel-private`.
+
+Stop condition: нет приватного `192.168.0.5`, MAC `eth1` не совпал, нет
+исходящего HTTPS на bootstrap, заняты `8080/4317/4318`, Compose публикует
+служебный порт на `0.0.0.0`, не создан первый администратор SigNoz, verify
+скрипт завершился ошибкой, нет альтернативного SSH через jump, нет snapshot
+диска перед lockdown/обновлением.
+
+Запрещены: `docker compose down -v`, `docker volume prune`,
+`docker system prune --volumes`; ручное редактирование `pours/`;
+`rsync --delete` без исключений `pours/` и `casting.yaml.lock`; публикация
+`8080/4317/4318` на всех интерфейсах; постоянный public SSH «на будущее».
+
+Текущие host-скрипты выполняются от `root`. Роли `deploy`/`admin` из arch-06
+на ВМ3 ещё не автоматизированы; не имитируйте их вручную поверх Foundry.
+
+## 1. Предварительные условия (облако)
+
+До копирования файлов на ВМ подготовьте вне Compose:
+
+1. Fresh Ubuntu 24.04, минимум 4 GiB RAM (лучше 8 GiB) и 30 GiB свободно
+   в `/opt`. Для эксплуатации ClickHouse закладывайте запас диска под
+   retention.
+2. Private subnet `192.168.0.0/24` с ВМ1, ВМ2 и managed PostgreSQL.
+   Приватный адрес ВМ3 — `192.168.0.5`.
+3. Временный public IP только на окно bootstrap. Cloud SG на этом этапе:
+   SSH TCP 22 с trusted ops CIDR, исходящий HTTPS/DNS к Docker Hub, GitHub,
+   `signoz.io`, Ubuntu archive. Порты `8080/4317/4318/5432/8123/9000/9181`
+   из интернета запрещены.
+4. После lockdown целевая SG:
+   - TCP 22 от jump/приватной подсети (`192.168.0.1` или SG ВМ1);
+   - TCP 4317 от приватных IP/SG ВМ1 и ВМ2;
+   - TCP 4318 только если оставлен HTTP ingest;
+   - никакого internet ingress;
+   - internet egress закрыт, кроме согласованного break-glass окна.
+5. Зафиксируйте MAC приватного NIC. Скрипт
+   `05-configure-private-network.sh` по умолчанию ждёт
+   `eth1` / `fa:16:3e:b6:c6:70`. Если MAC другой — передайте
+   `PRIVATE_MAC` явно, не правьте cloud-init `eth0`.
+
+## 2. SSH-доступ оператора
+
+На Windows добавьте в `C:\Users\MI\.ssh\config`:
+
+```sshconfig
+Host han-jump
+    HostName 135.106.164.58
+    User root
+    IdentityFile C:\Users\MI\.ssh\hansel
+
+Host signoz-bootstrap
+    HostName 135.106.166.7
+    User root
+    IdentityFile C:\Users\MI\.ssh\hansel
+
+Host signoz-private
+    HostName 192.168.0.5
+    User root
+    IdentityFile C:\Users\MI\.ssh\hansel-private
+    ProxyJump han-jump
+
+Host signoz-ui
+    HostName 192.168.0.5
+    User root
+    IdentityFile C:\Users\MI\.ssh\hansel-private
+    ProxyJump han-jump
+    LocalForward 8080 127.0.0.1:8080
+```
+
+До lockdown: `ssh signoz-bootstrap`. После появления приватного адреса
+проверьте `ssh signoz-private`, не закрывая bootstrap-сессию. Для UI:
+
+```powershell
+ssh signoz-ui -N
+```
+
+Откройте `http://127.0.0.1:8080`. Туннель обязан указывать на loopback
+**ВМ3**. Не используйте `-L 8080:192.168.0.5:8080` через jump: UI слушает
+`127.0.0.1:8080` на SigNoz, а не на `192.168.0.5`.
+
+## 3. Передача каталога на ВМ
+
+С WSL, не закрывая исключений. `pours/` и `casting.yaml.lock` создаёт
+Foundry на ВМ; без исключений `rsync --delete` уничтожит runtime.
+
+Первичная установка (публичный IP ещё есть):
+
+```bash
+rsync -rltD --no-perms --no-owner --no-group -ivc \
+  --exclude='.env' \
+  --exclude='dist/' \
+  --exclude='secrets/' \
+  --exclude='pours/' \
+  --exclude='casting.yaml.lock' \
+  -e "ssh -i ~/.ssh/hansel" \
+  /mnt/c/Users/MI/Documents/Assistent/HAN_chat_specification/VM3_signoz/Signoz/ \
+  root@135.106.166.7:/opt/signoz/
+```
+
+Повторная синхронизация после lockdown — через jump (`signoz-private`) и
+с `--delete`, сохранив те же exclude.
+
+На ВМ:
+
+```bash
+cd /opt/signoz
+sed -i 's/\r$//' scripts/*.sh
+chmod +x scripts/*.sh
+```
+
+Не копируйте `.env`, ключи и `pours/`. Постоянные правки портов вносятся
+только в `casting.yaml`, затем снова запускается `20-deploy-signoz.sh`.
+
+## 4. Приватный интерфейс
+
+Сохраните диагностику по [`NETWORK.md`](NETWORK.md). Default route должен
+остаться на публичном `eth0`; у `eth1` gateway нет.
+
+```bash
+cd /opt/signoz
+sudo ./scripts/05-configure-private-network.sh
+```
+
+Пока `netplan try` ждёт 120 секунд, во **второй** сессии проверьте:
+
+```bash
+ip -br -4 address show eth1
+ip route get 192.168.0.1
+```
+
+С ВМ1. ICMP в SG обычно закрыт, `ping` не используйте:
+
+```bash
+ssh -i ~/.ssh/hansel-private -o ConnectTimeout=5 root@192.168.0.5
+```
+
+Подтверждайте Netplan Enter только после успешного SSH с ВМ1.
+
+## 5. Preflight и Docker
+
+Исходящий интернет на этом шаге ещё нужен.
+
+```bash
+cd /opt/signoz
+sudo PRIVATE_IP=192.168.0.5 ./scripts/00-check-vm.sh
+sudo ./scripts/10-install-docker.sh
+```
+
+`00-check-vm.sh` требует Ubuntu 24.04, ≥4 GiB RAM, ≥30 GiB в `/opt`, адрес
+`192.168.0.5`, DNS/HTTPS к Docker Hub, GitHub и SigNoz, свободные
+`8080/4317/4318`. Любой `FAIL` — stop.
+
+## 6. Первый запуск SigNoz
+
+`casting.yaml` обязан содержать bind `192.168.0.5:4317/4318` и
+`127.0.0.1:8080`. Скрипт остановится, если Foundry опубликует эти порты на
+`0.0.0.0`.
+
+```bash
+cd /opt/signoz
+sudo PRIVATE_IP=192.168.0.5 ./scripts/20-deploy-signoz.sh
+```
+
+Ожидается: `foundryctl gauge/forge`, `compose pull/up`, UI health на
+`http://127.0.0.1:8080/api/v1/health` за ≤5 минут. Контейнеры `running` ещё
+не означают готовый ingest: до создания организации OpAMP не выдаёт
+ingester рабочую OTLP-конфигурацию.
+
+## 7. Первый администратор
+
+На рабочей станции:
+
+```powershell
+ssh signoz-ui -N
+```
+
+Откройте `http://127.0.0.1:8080`, создайте организацию и администратора.
+Пароль не сохраняйте в репозитории и history. Затем на ВМ3:
+
+```bash
+cd /opt/signoz
+sudo docker compose -f pours/deployment/compose.yaml restart ingester
+```
+
+Без этого шага TCP `4317` может слушаться, а телеметрия — не приниматься.
+
+## 8. Verify стека
+
+```bash
+cd /opt/signoz
+sudo PRIVATE_IP=192.168.0.5 ./scripts/30-verify-signoz.sh
+sudo docker compose -f pours/deployment/compose.yaml ps -a
+ss -lntp '( sport = :8080 or sport = :4317 or sport = :4318 )'
+```
+
+Ожидается healthy PostgreSQL, ClickHouse Keeper, ClickHouse, SigNoz UI;
+TCP `4317` на `192.168.0.5`; HTTP `4318` принимает пустой OTLP JSON;
+`8080` только на `127.0.0.1`. Любой `FAIL` — смотрите
+`docker compose -f pours/deployment/compose.yaml logs --tail=200`, не
+продолжайте к firewall/lockdown.
+
+С ВМ1 и ВМ2:
+
+```bash
+timeout 3 bash -c 'exec 3<>/dev/tcp/192.168.0.5/4317' \
+  && echo 'OTLP gRPC reachable'
+```
+
+## 9. Host firewall и cloud SG
+
+Скрипт интерактивный: введите `APPLY` только после второй живой SSH-сессии.
+Он сбрасывает UFW и ставит:
+
+- TCP 22 с любого источника — allow-list IP задаёте в SG/файрволе
+  приватной сети провайдера;
+- TCP 4317 и 4318 на `192.168.0.5` только из `192.168.0.0/24` (ВМ1 и ВМ2);
+- 8080 не открывается. UI остаётся на `127.0.0.1:8080` и доступен так:
+
+```powershell
+ssh -i C:\Users\MI\.ssh\hansel -L 8080:127.0.0.1:8080 root@<IP_ВМ3> -N
+```
+
+```bash
+cd /opt/signoz
+sudo PRIVATE_IP=192.168.0.5 \
+  PRIVATE_CIDR=192.168.0.0/24 \
+  ./scripts/40-configure-firewall.sh
+```
+
+UFW INPUT не фильтрует все Docker-публикации. Источник OTLP дополнительно
+держите в SG. `casting.yaml` биндит OTLP на приватный IP, UI — на loopback.
+
+В SG не открывайте публично 8080/5432/8123/9000/9181. SSH 22 режьте
+источником на стороне провайдера, не на UFW.
+
+## 10. Подключение ВМ1 и ВМ2
+
+Не считайте раскатку ВМ3 законченной по одной проверке TCP `4317`. Канал ingest
+настраивается на application VM по [`BACKEND_OTLP.md`](BACKEND_OTLP.md):
+
+```dotenv
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
+OTEL_REMOTE_ENDPOINT=192.168.0.5:4317
+OTEL_REMOTE_AUTH_HEADER=
+OTEL_REMOTE_TLS_INSECURE=true
+```
+
+`OTEL_REMOTE_TLS_INSECURE=true` допустим только в этой изолированной
+приватной сети. После recreate collector на каждой VM отправьте canary
+traces и найдите в SigNoz:
+
+```text
+service.name = han-chat-otlp-smoke
+service.namespace = han-chat
+deployment.environment = production-like
+```
+
+Collector сохраняет около 10% успешных traces: для smoke нужно порядка
+100 traces, не 10. End-to-end и outage/recovery acceptance описаны в
+`BACKEND_OTLP.md`; без них отсутствие ошибок в UI не доказывает здоровье
+HAN Chat.
+
+## 11. Snapshot, reboot gate и lockdown
+
+До удаления public IP:
+
+1. `ssh signoz-private` открывается отдельной сессией.
+2. Туннель `signoz-ui` показывает UI, администратор существует.
+3. `30-verify-signoz.sh` без ошибок.
+4. С ВМ1 и ВМ2 доступен `192.168.0.5:4317`.
+5. В SigNoz есть свежий canary или production-like trace.
+6. Все критичные контейнеры `running`/`healthy`.
+7. Создан snapshot диска ВМ3.
+8. В SG нет публичного доступа к служебным портам.
+
+Reboot gate. Не закрывайте jump/console доступ:
+
+```bash
+cd /opt/signoz
+sudo ./scripts/30-verify-signoz.sh
+sudo systemctl is-enabled docker.service
+sudo systemctl reboot
+```
+
+После reconnect через `signoz-private` повторите verify, `compose ps`,
+слушатели портов и canary с ВМ1.
+
+Lockdown по arch-06:
+
+- удалите public IP `135.106.166.7`;
+- уберите internet ingress из SG, включая public SSH;
+- закройте общий internet egress (DNS/NTP/private OTLP остаются);
+- с внешней сети SSH и `8080/4317` недоступны;
+- из private network SSH через jump и OTLP `4317` работают;
+- bootstrap installer-файлы и ненужные package caches можно удалить.
+
+Раскатка не завершена, пока lockdown не зафиксирован. Постоянно оставлять
+public IP «для обновлений» запрещено.
+
+## 12. Штатное обслуживание и обновление
+
+Проверка:
+
+```bash
+cd /opt/signoz
+sudo ./scripts/30-verify-signoz.sh
+sudo docker compose -f pours/deployment/compose.yaml ps
+sudo docker compose -f pours/deployment/compose.yaml logs --since=30m
+df -h
+docker system df
+```
+
+Не редактируйте `pours/` вручную. Изменение bind-адресов — только
+`casting.yaml` + `20-deploy-signoz.sh`.
+
+Обновление — break-glass по arch-06: временный исходящий HTTPS к Docker Hub,
+GitHub и SigNoz, минимальное окно, затем повтор lockdown.
+
+```bash
+cd /opt/signoz
+# 1. snapshot диска
+# 2. временный egress
+sudo df -h
+sudo ./scripts/20-deploy-signoz.sh
+sudo ./scripts/30-verify-signoz.sh
+# 3. проверить сохранность старых traces/metrics
+# 4. закрыть egress
+```
+
+Перед обновлением синхронизируйте git-каталог на ВМ с теми же exclude, что
+в §3. После обновления повторите smoke canary с ВМ1.
+
+## 13. Rollback и потеря ВМ
+
+Откат приложения: предыдущий проверенный `casting.yaml` + повтор
+`20-deploy-signoz.sh` **без** `-v`. Данные живут в Docker volumes ClickHouse
+и PostgreSQL; их удаление — потеря телеметрии.
+
+Потеря ВМ3: новая Ubuntu 24.04 этим runbook, тот же приватный `192.168.0.5`
+(или согласованная смена endpoint на ВМ1/ВМ2), новые volumes пустые.
+Исторические traces не восстанавливаются без snapshot диска. Collectors на
+ВМ1/ВМ2 fail-open для бизнеса и буферизуют в bounded queue; это не замена
+SigNoz.
+
+Компрометация host: не «чистите» ВМ. Изолируйте, сохраните evidence,
+ротируйте доступ и раскатывайте заново из trusted image.
+
+## 14. Acceptance record
+
+Сохраните без паролей:
+
+- дата/UTC окна, исполнитель, approver;
+- публичный IP bootstrap и факт его удаления;
+- приватный IP, MAC `eth1`, правила SG и `ufw status`;
+- вывод `00-check-vm.sh` и `30-verify-signoz.sh`;
+- `docker compose ps` и image ids;
+- факт создания организации/администратора (без секрета);
+- ссылка на canary trace `han-chat-otlp-smoke`;
+- snapshot id, reboot gate, lockdown checks снаружи и из private network;
+- следующее согласованное окно для dashboards/alerts по
+  [`MVP_DASHBOARDS_ALERTS.md`](MVP_DASHBOARDS_ALERTS.md).
+
+После приёмки ежедневная работа — [`SIGNOZ_RUNBOOK.md`](SIGNOZ_RUNBOOK.md).
+Dashboards и paging alerts создавайте только после baseline, не в этом же
+окне раскатки.