CRD & Operator Language

A CRD is the schema declaration that tells the Kubernetes API server: "accept and store objects of this new kind." The custom resource instances themselves are the data; the CRD is the type definition.

Without a CRD, kubectl will reject any resource with an unknown kind. Once the CRD is installed, operators can create, update, list, and delete custom resources using the full Kubernetes API and kubectl — including label selectors, namespace scoping, and RBAC. CRDs are the foundation of the operator pattern: they give operators a declarative interface their users can interact with using familiar tooling. Examples: cert-manager installs a Certificate CRD; Prometheus Operator installs a PrometheusRule CRD.

Key vocabulary:
• CRD (CustomResourceDefinition) — extends the Kubernetes API with a new resource kind and its schema
• custom resource (CR) — an instance of a type defined by a CRD; stored and managed by Kubernetes
• OpenAPI v3 schema — the validation schema embedded in a CRD that enforces field types and constraints

The operator reconciliation loop is the "observe, compare, act" cycle: watch for change events → read the current state → compare with the desired state → take the smallest corrective action needed → repeat.

This is the same pattern every core Kubernetes controller uses (Deployment controller, ReplicaSet controller, etc.). Operators extend it with domain-specific logic. For a database operator, reconciliation might mean: "spec says 3 replicas at version 15.2, actual state is 3 replicas at version 15.1 → trigger a rolling upgrade." The operator encodes operational knowledge (how to safely upgrade this database) as code, removing the need for manual runbooks. Key terms: watch (listen for events), reconcile (bring actual to desired), idempotent (safe to run multiple times).

Key vocabulary:
• reconciliation loop — the operator's core cycle: observe → diff → act → repeat
• desired state — the configuration declared in the custom resource spec
• actual state — what currently exists in the cluster; may differ from desired during transitions

Custom resource fields should be documented in two places: the CRD's OpenAPI schema (for validation and kubectl explain output) and the operator README (for example manifests and human-readable context).

When a field has an OpenAPI description, running kubectl explain BackupPolicy.spec.retentionDays displays that description directly in the terminal — giving operators instant documentation without leaving their workflow. The description should include: what the field controls, valid range, default value, and what happens when it is omitted. The README example should show a complete, working BackupPolicy manifest so operators can copy-paste and adapt it rather than guessing at field combinations.

Key vocabulary:
• OpenAPI v3 schema — embedded in the CRD; provides field descriptions, types, and validation rules
• kubectl explain — CLI command that displays schema and description for any resource field
• default value — the value used when the field is omitted; must be documented explicitly in CR schemas

The status subresource is the operator's window into the health of what it manages — it is written by the operator, not by Kubernetes, and reflects the operator's own assessment of the controlled resource's state.

The conditions array in status follows the Kubernetes conventions for condition types: type (e.g., Available, Progressing, Degraded), status (True/False/Unknown), reason (a camelCase code), message (human-readable explanation), and observedGeneration (which version of the spec this status reflects). When interpreting a Degraded condition, look at: (1) the reason field for a machine-readable code, (2) the message field for the human-readable explanation, and (3) the operator logs for full context. Never ignore status fields — they are the operator's primary communication channel.

Key vocabulary:
• status subresource — written by the operator to reflect the current health of the managed resource
• conditions — structured health indicators in status; each has type, status, reason, message
• observedGeneration — the spec generation the operator last reconciled; helps detect stale status

The key question is: does managing this application require human operational knowledge that must be enacted procedurally — if yes, that knowledge belongs in an operator; if the lifecycle is purely declarative, Helm is sufficient.

Helm upgrades by applying a new rendered manifest — excellent for stateless apps where "new version = apply new YAML." But a PostgreSQL upgrade might require: checking current replication lag, promoting a standby to primary, draining connections, running pg_upgrade, then reattaching replicas — a sequence that cannot be expressed in a single kubectl apply. Operators encode these procedures as code. This is why projects like PGO (PostgreSQL Operator), CloudNativePG, and Redis Operator exist. A common heuristic: if your runbook has conditional logic or depends on live state, it belongs in an operator.

Key vocabulary:
• stateful workload — an application with persistent identity, storage, and ordered lifecycle requirements
• operational logic — procedural knowledge about how to safely manage a system (backups, upgrades, failover)
• runbook — a documented procedure for operating a system; operators turn runbooks into executable code