initial commit

08-Słownik-K8s/CRD - Custom Resource Definition.md

@@ -0,0 +1,87 @@
+# 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]]