# Controller i Reconciler

#kubernetes #architecture #operator #słownik

## Co to jest?

**Controller** to pętla kontrolna w Kubernetes obserwująca stan zasobów i **doprowadzająca rzeczywisty stan do pożądanego** (desired state → actual state). **Reconciler** to funkcja wywoływana gdy stan zasobu zmienia się.

## Wzorzec reconciliation

```
Desired state (CRD spec) → Controller → Actual state (K8s resources)

Pętla:
  1. Observe: Watch API server for changes
  2. Diff: Compare desired vs actual
  3. Act: Create/update/delete resources
  4. Repeat
```

## Kluczowe koncepty

| Koncept | Opis |
|---------|------|
| **Watch** | Subskrypcja na eventy (create/update/delete) |
| **Work queue** | Kolejka zasobów do reconciliation |
| **Reconcile()** | Funkcja wywoływana per zasób |
| **Requeue** | "Sprawdź mnie ponownie za N sekund" |
| **Idempotent** | Reconcile() musi być bezpieczne do wielokrotnego wywołania |
| **Level-triggered** | Reaguje na **stan**, nie na **event** |

## Level-triggered vs edge-triggered

```
Edge-triggered: "Coś się zmieniło!" → reaguj na zmianę
Level-triggered: "Jaki jest aktualny stan?" → doprowadź do desired

Kubernetes Controllers = LEVEL-TRIGGERED
  → Nie ważne CO się zmieniło
  → Ważne JAKI jest stan i JAKI powinien być
  → Resilient na missed events
```

## controller-runtime

Sympozium używa `sigs.k8s.io/controller-runtime` - framework Go dla Kubernetes controllers:

```go
type AgentRunReconciler struct {
    client.Client
    Scheme *runtime.Scheme
    Log    logr.Logger
}

func (r *AgentRunReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 1. Fetch resource
    // 2. Compare desired vs actual
    // 3. Create/update/delete
    // 4. Update status
    return ctrl.Result{RequeueAfter: 10 * time.Second}, nil
}
```

## Controllers w Sympozium

| Controller | Zasób | Co reconciliuje |
|------------|-------|-----------------|
| AgentRunReconciler | [[AgentRun]] | [[Job]]/Sandbox CR, RBAC, ConfigMaps |
| SympoziumInstanceReconciler | [[SympoziumInstance]] | Channel [[Deployment|Deployments]], memory |
| PersonaPackReconciler | [[PersonaPack]] | Instances, Schedules, memory |
| SkillPackReconciler | [[SkillPack]] | ConfigMaps ze skills |
| SympoziumScheduleReconciler | [[SympoziumSchedule]] | AgentRun na schedule |
| MCPServerReconciler | [[MCPServer]] | Deployments, Services |

Więcej: [[Control Plane]] | [[Cykl życia AgentRun]]

---

Powiązane: [[CRD - Custom Resource Definition]] | [[Control Plane]] | [[Finalizer]]