# CRD - Custom Resource Definition

#kubernetes #api #słownik

## Co to jest?

**Custom Resource Definition (CRD)** to mechanizm Kubernetes pozwalający na **rozszerzenie API klastra o własne typy zasobów**. Po zainstalowaniu CRD, nowy typ zasobu jest traktowany przez API server identycznie jak wbudowane zasoby (Pod, Service, Deployment).

## Jak działa?

```
1. Instalacja CRD YAML → K8s API Server rejestruje nowy typ
2. Użytkownik tworzy instancję → Zapisana w etcd jak każdy zasób
3. Controller obserwuje → Reconciliuje desired state → actual state
```

## Przykład

```yaml
# Definicja CRD
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: agentruns.sympozium.ai
spec:
  group: sympozium.ai
  versions:
    - name: v1alpha1
      served: true
      storage: true
  scope: Namespaced
  names:
    plural: agentruns
    singular: agentrun
    kind: AgentRun
```

```yaml
# Instancja CRD (Custom Resource / CR)
apiVersion: sympozium.ai/v1alpha1
kind: AgentRun
metadata:
  name: my-run
spec:
  task: "Check cluster health"
```

## Kluczowe koncepty

| Koncept | Opis |
|---------|------|
| **CRD** | Definicja typu (schemat) |
| **CR** (Custom Resource) | Instancja danego typu |
| **Controller** | Kod obserwujący CR i realizujący intent |
| **Operator** | Controller + CRD + logika domenowa |
| **Status subresource** | Oddzielny endpoint do aktualizacji statusu |
| **Finalizer** | Blokuje usunięcie do czasu cleanup |
| **Validation** | Schema validation (OpenAPI v3) lub webhook |

## Dlaczego CRD a nie ConfigMap?

| CRD | ConfigMap |
|-----|-----------|
| Typowane, walidowane | Dowolne dane |
| Status subresource | Brak statusu |
| kubectl native (`kubectl get agentruns`) | Wymaga custom tooling |
| RBAC per-resource | RBAC per-configmap |
| Watch API (event-driven) | Polling |
| ownerReferences (GC) | Manualne zarządzanie |

## CRD w Sympozium

Sympozium definiuje **7 CRDs** (API group: `sympozium.ai/v1alpha1`):

| CRD | Opis |
|-----|------|
| [[SympoziumInstance]] | Tożsamość agenta / tenant |
| [[AgentRun]] | Pojedyncze wywołanie agenta |
| [[PersonaPack]] | Bundle pre-konfigurowanych agentów |
| [[SkillPack]] | Portable skills (Markdown + sidecar) |
| [[SympoziumPolicy]] | Polityki governance |
| [[SympoziumSchedule]] | Cron-based recurring tasks |
| [[MCPServer]] | External MCP tool providers |

---

Powiązane: [[Controller i Reconciler]] | [[Finalizer]] | [[ownerReference]]