microdao-daarion/PRODUCTION-DEPLOYMENT-GUIDE.md

🚀 Production Deployment Guide

Дата: 2026-01-10
Версія: 1.0.0
Статус: Production-ready

---

✅ Pre-flight Checklist

Архітектура (перевірено)

• ✅ Matrix = control-plane
• ✅ NATS JetStream = data-plane
• ✅ Worker Daemon з capability routing
• ✅ Memory Service як write/retrieval boundary
• ✅ Postgres = truth / Qdrant = index

---

🔐 Крок 1: Atomic генерація секретів

ВИКОНАТИ ОДНИМ СЕТОМ, без часткових деплоїв

cd infrastructure/auth
./generate-all-secrets.sh

Результат:

• secrets/nats-operator.jwt — NATS operator JWT
• secrets/nats-system-account.jwt — System account JWT
• secrets/nats-*.jwt — User accounts (memory-service, worker-daemon, matrix-gateway)
• secrets/qdrant-keys.txt — Qdrant API keys
• secrets/memory-jwt-secret.txt — Memory Service JWT secret

⚠️ КРИТИЧНО:

1. Збережіть secrets/ в безпечне місце
2. Завантажте секрети в Vault
3. НЕ комітьте secrets/ в Git!

---

🔒 Крок 2: Auth Enforcement

Перевірка, що всі сервіси вимагають auth:

./infrastructure/auth/enforce-auth.sh

Очікуваний результат:

• ✅ NATS operator JWT налаштовано
• ✅ Memory Service JWT secret існує
• ✅ Qdrant API keys Secret існує
• ✅ Memory Service відхиляє запити без JWT

Якщо перевірки не пройдено:

1. Завантажте секрети в Vault
2. Оновіть External Secrets Operator
3. Застосуйте auth конфігурації

---

🧪 Крок 3: Smoke-test (5 хв)

Базові перевірки:

# Перевірка NATS
kubectl get pods -n nats

# Перевірка streams
kubectl exec -n nats nats-0 -- wget -qO- http://localhost:8222/jsz | python3 -m json.tool | grep streams

# Перевірка Memory Service
kubectl get pods -n daarion -l app=memory-service

Очікування:

• NATS: Running
• Streams: 4+ streams створено
• Memory Service: Running (опціонально)

---

🧪 Крок 4: Full Flow Test (must-pass)

Запуск повного тесту:

./infrastructure/test-full-flow.sh

Очікуваний результат:

1. ✅ NATS JetStream: Running
2. ✅ NATS Streams: 4+ streams
3. ✅ Job creation via NATS: Success
4. ✅ Streams verification: All found

Якщо тест провалено:

• Перевірте логи: kubectl logs -n nats nats-0
• Перевірте streams: kubectl exec -n nats nats-0 -- wget -qO- http://localhost:8222/jsz

---

📊 Крок 5: Observability

Prometheus Alerting Rules

kubectl apply -f infrastructure/observability/prometheus-rules.yaml

Алерти:

• NATSOnlineBacklogHigh — backlog > 1000 (critical)
• NATSRedeliveriesSpike — redeliveries > 100/min (warning)
• WorkerOffline — worker offline > 2 min (critical)
• WorkerEmbedLatencyHigh — P95 > 500ms (warning)

Matrix Alerts Bridge

# Налаштування Matrix ops room
export MATRIX_HOMESERVER=https://matrix.org
export MATRIX_USER=@ops:matrix.org
export MATRIX_PASSWORD=password
export MATRIX_OPS_ROOM_ID=!ops:matrix.org

# Запуск bridge
python3 infrastructure/observability/matrix-alerts-bridge.py

Результат:

• Алерти з Prometheus → Matrix #ops.alerts
• Критичні алерти → негайне повідомлення
• Попередження → щоденний дайджест

---

📋 Крок 6: Policy Layer для пам'яті

Документація: infrastructure/memory-policy/memory-policy-engine.md

Ключові правила:

• Що запам'ятовувати в long-term memory
• Хто має право писати "факт"
• Як підтверджується / видаляється пам'ять
• Retention policies

Реалізація:

• Policy rules в Postgres (memory_policy_rules table)
• Policy Engine в Memory Service
• User feedback механізм

---

🎯 Production Readiness Checklist

Критичні (must-have)

• Всі секрети згенеровано та завантажено в Vault
• Auth enforcement активний (перевірка через enforce-auth.sh)
• Smoke-test пройдено
• Full flow test пройдено
• Prometheus alerting rules застосовано
• Matrix alerts bridge налаштовано

Важливі (should-have)

• Policy engine реалізовано
• Grafana дашборди створено
• SLO/SLA документовано
• Backup/restore стратегія налаштована

Опціональні (nice-to-have)

• NATS кластер (3+ replicas) для HA
• mTLS для Memory Service
• Consul для capability registry

---

📈 SLO/SLA (рекомендовані)

Online Jobs (MM_ONLINE)

• Latency P95: < 300ms
• Availability: 99.9%
• Backlog: < 1000 messages

Offline Jobs (MM_OFFLINE)

• Latency P95: < 60s
• Availability: 99.5%
• Backlog: < 10000 messages

Memory Service

• Latency P95: < 1s
• Availability: 99.9%
• Error rate: < 0.1%

---

🔄 Scale-out (додавання нод)

Процес:

1. Нова нода = тільки worker-daemon
2. Capabilities реєструються автоматично
3. Жодних змін у Matrix / Memory / NATS

Перевірка:

# Перевірка реєстрації
kubectl exec -n daarion postgres-0 -- psql -U daarion -d daarion_main -c "SELECT node_id, tier, status FROM worker_capabilities;"

# Перевірка heartbeat
kubectl exec -n daarion postgres-0 -- psql -U daarion -d daarion_main -c "SELECT node_id, last_heartbeat FROM worker_capabilities WHERE last_heartbeat > NOW() - INTERVAL '2 minutes';"

---

🚨 Incident Response

Якщо NATS backlog росте:

1. Перевірте worker status: kubectl get pods -l app=memory-worker
2. Перевірте metrics: kubectl port-forward -n monitoring prometheus-0 9090:9090
3. Можливо потрібно додати більше воркерів

Якщо worker offline:

1. Перевірте логи: kubectl logs -n daarion memory-worker-xxx
2. Перевірте capability registry: SELECT * FROM worker_capabilities WHERE node_id='xxx';
3. Можливо потрібен перезапуск

Якщо Memory Service недоступний:

1. Перевірте health: curl http://memory-service.daarion:8000/health
2. Перевірте логи: kubectl logs -n daarion memory-service-xxx
3. Перевірте Postgres/Qdrant connectivity

---

📝 Наступні кроки після deployment

1. Перевести 1-2 реальних агентів у повний прод-цикл

   • Не тестових, а реальних
   • Прожити з ними 24-72 години
   • Увімкнені алерти

2. Моніторинг та оптимізація

   • Аналіз метрик
   • Оптимізація latency
   • Налаштування алертів

3. Масштабування

   • Додавання нових нод
   • Оптимізація розподілу навантаження
   • Налаштування HA

---

Документ створено: 2026-01-10 19:30 CET