📚 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