k8s-crd-design

Kubernetes CRD Design Patterns

Use these patterns when designing and implementing CRDs, webhooks, controllers, and RBAC for Kubernetes operators.

1. Problem Framing

Before writing code, answer:

• Summarize the user problem in one sentence.
• List the CRD's top 3 responsibilities.
• Identify safety risks (what could go wrong if the controller misbehaves?).

2. CRD Schema Design

Propose a CRD with:

• Spec fields: Required fields with types and validation markers. Use kubebuilder markers (+kubebuilder:validation:*).
• Status fields: Observed state, conditions, and last-reconciled generation.
• Defaults: Use +kubebuilder:default:= markers for sensible defaults.
• Validation: Use +kubebuilder:validation:Enum, +kubebuilder:validation:Minimum, +kubebuilder:validation:Pattern as appropriate.
• Printer columns: Add +kubebuilder:printcolumn for useful kubectl get output.

Example pattern:

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
type MyResource struct {
    metav1.TypeMeta   `json:",inline"`
    metav1.ObjectMeta `json:"metadata,omitempty"`
    Spec              MyResourceSpec   `json:"spec,omitempty"`
    Status            MyResourceStatus `json:"status,omitempty"`
}

3. Webhook Design

Validating Webhook

• Block invalid creates and updates.
• Enforce immutable fields on update.
• Validate cross-field constraints.
• Return clear error messages.

Mutating Webhook

• Only default safe, optional fields.
• Never mutate fields the user explicitly set.
• Add labels/annotations the controller needs.
• Keep mutations minimal and predictable.

Failure Policy

• Dev: Ignore (don't block the cluster if webhook is down)
• Production: Fail (safety over availability)

4. Reconcile Loop Outline