Kubernetes CRD Design Review

Perform a deterministic design + contract review for Kubernetes CRDs (the generated CRD YAML is the compiled API contract).

Inputs

Accept at least one of:

• CRD YAML (full manifest) or a CRD diff
• Go API types and/or kubebuilder markers used to generate the CRD
• A short description of intended API semantics and controller behavior

If key info is missing, ask for it before concluding compatibility/migration:

• Whether a controller exists, what it owns, and whether it writes status
• Whether this is a new API or a change to an existing API
• Served versions, storage version, and existing clients
• Whether objects already exist in clusters (migration needed?)
• Any GitOps/SSA constraints (patch strategy, desired stable identities)

Workflow (always follow this order)

1) Identify scope

• Identify group, kind(s), version(s), and whether this is new vs change.
• Identify controller existence and ownership boundaries.
• If reviewing Go types, confirm which generated CRD YAML(s) correspond to them.

2) Contract integrity checks (spec/status + controller operability)

• Spec vs status boundary
  • spec = user intent / desired state.
  • status = controller-observed state.
  • Flag lifecycle/state-machine fields in spec if the controller owns transitions.
• Require subresources.status when a controller exists and writes status
• Conditions + observedGeneration
  • Recommend status.conditions using Kubernetes conventions.
  • Recommend status.observedGeneration for tooling/GitOps correctness.
  • Treat Conditions as a map keyed by type (not a chronological list): avoid duplicate type entries and prefer schema markers that enable map semantics for SSA/GitOps.
  • Prefer a single high-signal summary condition (Ready for long-running resources; Succeeded for bounded execution) and keep other Conditions secondary.
  • Prefer state-style Condition types (adjectives/past tense like Ready, Degraded, Succeeded). Transition-style names are usually less clear, but can be acceptable for long-running transitions if modeled as an observed state with consistent True/False/Unknown semantics.
  • Avoid state-machine style status.phase for new APIs; prefer Conditions.
  • Remember status is typically written via the /status subresource with separate RBAC.

If needed, load ./references/conditions-and-status.md

3) Schema correctness (prevent invalid stored objects)

Review the OpenAPI v3 schema (prefer the generated CRD YAML/diff):

• Required fields for true invariants

• Enums for constrained strings

• Defaulting and nullable behavior

• Cross-field invalid combinations

  • If the schema cannot express it with basic validation, suggest CEL (x-kubernetes-validations) with minimal, targeted rules.

• Object references & relationships

  • When a field refers to another Kubernetes object, check that naming and schema follow Kubernetes API conventions:
    • Object references: use fooRef / fooRefs (structured object(s)), also do this if only the name is needed (please load ./references/object-references.md for more details on the recommended naming conventions)
    • Name-only references are acceptable for existing situations (e.g. fooName (string)), do NOT use this for new developemnts.
  • Watch for cross-namespace references (security boundary) and for leaking copied values from the referenced object into spec/status.

If needed, load ./references/object-references.md. If needed, load ./references/validation-and-cel.md.

4) GitOps/SSA ergonomics

Focus on patchability and stable diffs:

• List semantics for arrays of objects
  • If items have stable identity (e.g., name, id), prefer map-like lists:
    • x-kubernetes-list-type: map
    • x-kubernetes-list-map-keys: ["..."]
• Identify ordering sensitivity and full-array replacement hazards.

If needed, load ./references/list-semantics-gitops-ssa.md.

5) Operator UX (kubectl)

• Review/add additionalPrinterColumns for operator-facing UX:
  • Ready / health signal
  • Status message / reason
  • Key spec fields
• Do not duplicate default AGE.

If needed, load ./references/printer-columns.md.

6) Compatibility & migration impact (mandatory)

Always include an explicit compatibility assessment.

• Classify change as non-breaking vs potentially breaking.
• Consider more than removals:
  • tightening validation
  • type changes
  • list semantic changes
  • defaulting changes
  • semantic behavior changes
• If version evolution is involved:
  • serving multiple versions
  • conversion webhook need
  • storage version migration reminders
  • deprecation playbook

If needed, load ./references/versioning-and-migrations.md.

7) Summarize

• Provide ranked risks + why they matter.
• Provide actionable changes + snippets.
• Provide a minimal, PR-sized improvement plan.
• Provide a copy/paste PR review template block.

Output format (always use this template)

What’s good

• …

Top risks (ranked)

1. … — why it matters: …
2. … — why it matters: …
3. … — why it matters: …

Recommended changes (actionable)

• Change: …
  • Why: …
  • Snippet:

    # ...
    

Compatibility & migration impact (mandatory)

• Breaking? Yes/No
• Why: …
• If breaking or risky:
  • Migration / deprecation steps:
    1. …
    2. …
  • Rollout plan checklist:
    • …
    • …
  • Versioning notes: served versions, storage version, conversion considerations

Minimal improvement plan (PR-sized)

1. …
2. …
3. …

PR-ready review template (copy/paste)

Load and reuse the canonical template in ./references/review-template.md. If it does not match the context, adapt it but keep the same section headings.