initial commit

02-Architektura/Control Plane.md

@@ -0,0 +1,88 @@
+# Control Plane
+
+#sympozium #architektura #control-plane
+
+## Komponenty
+
+Control Plane Sympozium składa się z następujących komponentów:
+
+### Controller Manager
+Serce systemu. Zawiera **6 [[Controller i Reconciler|reconcilerów]]** + 2 routery:
+
+| Reconciler | CRD | Odpowiedzialność |
+|------------|-----|------------------|
+| `AgentRunReconciler` | AgentRun | Tworzy Job/Sandbox CR, monitoruje lifecycle, zbiera wyniki |
+| `SympoziumInstanceReconciler` | SympoziumInstance | Zarządza kanałami, memory, web endpoints |
+| `PersonaPackReconciler` | PersonaPack | Stampuje instancje, schedules, memory z packów |
+| `SkillPackReconciler` | SkillPack | Generuje ConfigMapy ze skilli |
+| `SympoziumPolicyReconciler` | SympoziumPolicy | Zarządza politykami |
+| `SympoziumScheduleReconciler` | SympoziumSchedule | Tworzy AgentRuns wg harmonogramu cron |
+| `MCPServerReconciler` | MCPServer | Deployuje i probeuje MCP serwery |
+
+**Routery** (reagują na eventy NATS):
+- `ChannelRouter` - przetwarza wiadomości z kanałów → tworzy AgentRun
+- `ScheduleRouter` - obsługuje `schedule.upsert` z agentów → tworzy/aktualizuje SympoziumSchedule
+
+### API Server
+- HTTP + WebSocket API
+- Serwuje embedded web UI (React)
+- Czyta annotacje node'ów (inference discovery)
+- Sesje i historia w PostgreSQL
+
+### [[Admission Webhook]]
+- Enforces `SympoziumPolicy` przy tworzeniu AgentRun
+- Waliduje sandbox requirements, tool gating, feature gates
+- Działa at admission time, nie at runtime
+
+### [[NATS JetStream]]
+- Durable pub/sub event bus
+- Decouples kanały od control plane
+- Replay capability dla niezawodności
+
+## Warstwa danych
+
+| Magazyn | Zastosowanie |
+|---------|-------------|
+| **etcd** | [[CRD - Custom Resource Definition|CRD]] state (via K8s API) |
+| **PostgreSQL** | Sesje, historia konwersacji |
+| **SQLite + FTS5** | Persistent memory agentów (na PVC) |
+| **[[ConfigMap i Secret\|ConfigMaps]]** | Skills, legacy memory |
+| **[[ConfigMap i Secret\|Secrets]]** | Klucze API providerów |
+
+## Przepływ reconciliation
+
+```
+User/Channel → Wiadomość
+    ↓
+Channel Pod → NATS (channel.message.received)
+    ↓
+Channel Router → Tworzy AgentRun CR
+    ↓
+AgentRun Reconciler:
+  1. Walidacja polityki (SympoziumPolicy)
+  2. Tworzenie input ConfigMap (task + system prompt)
+  3. Rozwiązywanie skill sidecars (SkillPack CRDs)
+  4. Rozwiązywanie MCP serverów
+  5. Tworzenie Job/Sandbox CR z:
+     - Agent container
+     - IPC bridge sidecar
+     - Skill sidecars (z auto-provisioned RBAC)
+     - MCP bridge sidecar (opcjonalnie)
+     - Sandbox sidecar (opcjonalnie)
+  6. Monitorowanie faz: Pending → Running → Succeeded/Failed
+  7. Zbieranie wyników z logów poda
+  8. Ekstrakcja memory updates
+  9. Czyszczenie RBAC i zasobów
+```
+
+## Metryki OTel
+
+Controller eksportuje metryki OpenTelemetry:
+- `sympozium.agent.runs` - counter zakończonych runów
+- `sympozium.agent.duration_ms` - histogram czasu trwania
+- `sympozium.errors` - counter błędów
+- `sympozium.web_endpoint.serving` - aktywne deployments server-mode
+
+---
+
+Powiązane: [[Cykl życia Agent Pod]] | [[NATS JetStream - Event Bus]] | [[Orchestrator - PodBuilder i Spawner]]