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

# 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

# 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

2.4 KiB Raw Blame History