CRDs as New Scripture

Doctrine

A CRD is a new contract with the cluster. Once created, it becomes part of the archive: stored in etcd, watched by controllers, and operated by humans under stress.

Kubblai doctrine: you do not add new scripture casually.

Schema as enforcement, not documentation

OpenAPI schemas are not for aesthetics. They enable validation, defaulting, pruning, and clients. A weak schema creates undefined behavior that becomes folklore.

Define constraints, required fields, and patterns. Make invalid states unrepresentable.

Versioning and conversion: governance over time

CRDs live longer than teams. Versions, deprecations, and conversions are inevitable. A conversion webhook is a production dependency that must be monitored and failure-tested.

If you cannot upgrade the CRD safely, you have created institutional risk.

• Minimize disruptive schema changes.
• Document and enforce deprecation timelines.
• Test conversions and rollback behavior.

Status and conditions: the testimony of custom controllers

If a CRD is operated by humans, it needs conditions. Conditions need reason strings, last transition times, and stable semantics. Otherwise operators will guess.

Treat status as an API: stable, observable, and designed for incident use.

Cost accounting

CRDs consume etcd and watch capacity. Large spec/status fields and high-frequency updates multiply cost. The operator’s discipline is to measure and budget these costs.

A custom API is a privilege; budget accordingly.