📚 Production Deployment Guide: повна інструкція
- Atomic генерація секретів - Auth enforcement checklist - Smoke-test та Full flow test - Observability setup - Policy layer документація - SLO/SLA рекомендації - Scale-out інструкції - Incident response Система готова до production deployment!
This commit is contained in:
Apple
255
PRODUCTION-DEPLOYMENT-GUIDE.md
Normal file
255
PRODUCTION-DEPLOYMENT-GUIDE.md
Normal file
@@ -0,0 +1,255 @@
|
|||||||
|
# 🚀 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 генерація секретів
|
||||||
|
|
||||||
|
**ВИКОНАТИ ОДНИМ СЕТОМ, без часткових деплоїв**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./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 хв)
|
||||||
|
|
||||||
|
**Базові перевірки:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Перевірка 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)
|
||||||
|
|
||||||
|
**Запуск повного тесту:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Налаштування 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
|
||||||
|
|
||||||
|
**Перевірка:**
|
||||||
|
```bash
|
||||||
|
# Перевірка реєстрації
|
||||||
|
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*
|
||||||
Reference in New Issue
Block a user