# K8S Crd Design

> Design CRD schemas, webhooks, reconcile loops, status models, and RBAC for Kubernetes operators. Use when Codex needs to define or review the API shape and control-plane behavior of a Kubebuilder-style operator.

- Skill: `majiayu000/k8s-crd-design` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/k8s-crd-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/k8s-crd-design/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/k8s-crd-design

---


# Kubernetes CRD Design Patterns

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

## Problem Framing

Before writing code:

- Summarize the user problem in one sentence.
- List the CRD's top three responsibilities.
- Identify safety risks if the controller misbehaves.

## CRD Schema Design

Propose:

- `spec` fields with types, validation markers, and requiredness
- `status` fields for observed state, conditions, and generation tracking
- default markers for safe optional fields
- validation markers for enum, minimum, pattern, and cross-field rules
- printer columns for useful `kubectl get` output

Enable the status subresource when the CR reports status.

## Webhook Design

### Validating Webhook

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

### Mutating Webhook

- Default only safe, optional fields.
- Do not overwrite explicit user input.
- Add only predictable labels or annotations the controller depends on.

### Failure Policy

- Use `Ignore` in local dev if availability matters more than strict enforcement.
- Use `Fail` when the environment requires safety over availability.

## Reconcile Loop

Follow this sequence:

1. Fetch the CR.
2. Handle deletion and finalizers.
3. Compute desired state from the spec.
4. Create, update, or delete owned resources.
5. Update status and conditions.
6. Requeue only when needed.

Keep the reconcile function idempotent and level-triggered.

## RBAC Minimization

Grant only the verbs and resources the controller needs:

- CRD: `get`, `list`, `watch`, `patch`, `update` on status if used
- owned resources: the minimal CRUD verbs actually exercised
- events: `create` and `patch`

Avoid wildcards and cluster-wide scope unless the resource model requires it.

## Test Outline

Minimum coverage:

- table-driven unit tests for reconcile logic
- envtest or equivalent integration tests for webhook validation
- valid and invalid sample CRs for manual verification