han-app/VM3_signoz/Signoz/docs/RUNBOOK.ru.md

Runbook развёртывания SigNoz (ВМ3)

Это единственный исполняемый runbook раскатки self-hosted SigNoz для HAN Chat. Команды выполняет оператор; repository automation их не запускает.

ВМ3 — private/no-egress узел по arch-06-service-hosting-security.md: после приёмки нет internet ingress, нет постоянного internet egress, UI не публикуется, OTLP доступен только из приватной сети. Раскатка не завершена, пока не закрыт lockdown и обе группы проверок (снаружи и из private network).

Эксплуатация UI, разбор инцидентов и алерты — в SIGNOZ_RUNBOOK.md. Подключение приложений — BACKEND_OTLP.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:

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:

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 ещё есть):

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.

На ВМ:

cd /opt/signoz
sed -i 's/\r$//' scripts/*.sh
chmod +x scripts/*.sh

Не копируйте .env, ключи и pours/. Постоянные правки портов вносятся только в casting.yaml, затем снова запускается 20-deploy-signoz.sh.

4. Приватный интерфейс

Сохраните диагностику по NETWORK.md. Default route должен остаться на публичном eth0; у eth1 gateway нет.

cd /opt/signoz
sudo ./scripts/05-configure-private-network.sh

Пока netplan try ждёт 120 секунд, во второй сессии проверьте:

ip -br -4 address show eth1
ip route get 192.168.0.1

С ВМ1. ICMP в SG обычно закрыт, ping не используйте:

ssh -i ~/.ssh/hansel-private -o ConnectTimeout=5 root@192.168.0.5

Подтверждайте Netplan Enter только после успешного SSH с ВМ1.

5. Preflight и Docker

Исходящий интернет на этом шаге ещё нужен.

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.

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. Первый администратор

На рабочей станции:

ssh signoz-ui -N

Откройте http://127.0.0.1:8080, создайте организацию и администратора. Пароль не сохраняйте в репозитории и history. Затем на ВМ3:

cd /opt/signoz
sudo docker compose -f pours/deployment/compose.yaml restart ingester

Без этого шага TCP 4317 может слушаться, а телеметрия — не приниматься.

8. Verify стека

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:

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 и доступен так:

ssh -i C:\Users\MI\.ssh\hansel -L 8080:127.0.0.1:8080 root@<IP_ВМ3> -N

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:

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:

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 доступ:

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. Штатное обслуживание и обновление

Проверка:

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.

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.

После приёмки ежедневная работа — SIGNOZ_RUNBOOK.md. Dashboards и paging alerts создавайте только после baseline, не в этом же окне раскатки.