alirezarezvani/claude-skills / engineering/skills/kubernetes-operator
kubernetes-operator
VerifiedUse when building a Kubernetes operator or CRD (controller-runtime, kubebuilder, operator-sdk, KOPF), before writing the controller. Validates CRDs with crd_validator.py, lints reconcile loops with reconcile_lint.py and scores OperatorHub capability level.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
| assets/crd_template.yaml | config | 2.6 KB |
| assets/reconcile_skeleton.go | script | 4.0 KB |
| references/crd_design.md | markdown | 6.8 KB |
| references/operator_pattern.md | markdown | 7.0 KB |
| references/reconcile_loop.md | markdown | 7.1 KB |
| references/tooling_landscape.md | markdown | 7.5 KB |
| scripts/crd_validator.pyexecutable | script | 5.8 KB |
| scripts/operator_capability_audit.pyexecutable | script | 5.8 KB |
| scripts/reconcile_lint.pyexecutable | script | 6.3 KB |
references/crd_design.md
View on GitHub# CRD design
Custom Resource Definitions (CRDs) define the API surface of your operator. A bad CRD design locks you into hard-to-evolve schemas, forces wrapper APIs, and creates user-facing UX problems via `kubectl`.
## Anatomy of a production CRD
```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: myapps.apps.example.com # plural.group
spec:
group: apps.example.com
names:
kind: MyApp # PascalCase
plural: myapps # lowercase
singular: myapp # lowercase
listKind: MyAppList # KindList
shortNames: [ma] # optional
scope: Namespaced # or Cluster (justify)
versions:
- name: v1alpha1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
properties:
spec:
type: object
required: [version]
properties:
version:
type: string
pattern: '^[0-9]+\.[0-9]+\.[0-9]+$'
replicas:
type: integer
minimum: 1
maximum: 100
default: 3
status:
type: object
properties:
phase:
type: string
enum: [Pending, Running, Failed]
conditions:
type: array
items:
type: object
required: [type, status, lastTransitionTime]
properties:
type: { type: string }
status: { type: string, enum: ["True", "False", "Unknown"] }
reason: { type: string }
message: { type: string }
lastTransitionTime: { type: string, format: date-time }
observedGeneration: { type: integer }
subresources:
status: {} # CRITICAL — see below
scale: # if scaling is meaningful
specReplicasPath: .spec.replicas
statusReplicasPath: .status.readyReplicas
additionalPrinterColumns:
- name: Phase
type: string
jsonPath: .status.phase
- name: Ready
type: string
jsonPath: .status.conditions[?(@.type=="Ready")].status
- name: Age
type: date
jsonPath: .metadata.creationTimestamp
```
## Required structural elements
### 1. Status subresource — `subresources.status: {}`
Without it:
- `r.Status().Update(ctx, obj)` doesn't work — falls back to `r.Update`
- Status updates re-trigger spec reconcile → loop
- RBAC can't be split between spec writers and status writers
**Always declare it.**
### 2. Conditions array
Use the standard `metav1.Condition` shape. Required fields: `type`, `status`, `lastTransitionTime`. Recommended: `reason`, `message`, `observedGeneration`.
Conventional condition types:
- `Ready` — overall readiness
- `Reconciling` — controller is actively working
- `Degraded` — operating but with reduced capability
- `Progressing` — change in progress (mostly for Deployments-style flows)
Use `meta.SetStatusCondition()` from `k8s.io/apimachinery/pkg/api/meta` — don't write to the slice directly.
### 3. observedGeneration
Track which spec generation the controller has acted on:
```go
status.ObservedGeneration = obj.Generation
```
Lets users tell whether status reflects the latest spec or a previous one.
### 4. Printer columns
`kubectl get myapp` UX is determined by `additionalPrinterColumns`. Always include:
- `Phase` or `Ready` (status)
- `Age` (so users know when it was created)
Optionally: replicas, version, key spec field.
### 5. Validation in the schema, not the controller
Express constraints declaratively:
| Constraint | OpenAPI |
|---|---|
| Range | `minimum`/`maximum` |
| String pattern | `pattern: '^...$'` |
| Enum | `enum: [Pending, Running]` |
| Required field | `required: [...]` |
| Default value | `default: 3` |
| Min/max length | `minLength`/`maxLength` |
Reserve controller validation for cross-field rules and external dependencies (e.g., "this name is taken in our DB").
### 6. Avoid `x-kubernetes-preserve-unknown-fields: true`
It disables structural validation. Sometimes needed (e.g., raw `kubectl apply` patches), but never at the spec root. Use it sparingly on a single sub-tree.
## Versioning strategy
CRDs evolve. Plan from day 1:
| Stage | Version | Stability | Allowed changes |
|---|---|---|---|
| Internal preview | `v1alpha1` | None | Anything; document breaking changes |
| Beta | `v1beta1` | Some | Additive only; deprecate fields |
| GA | `v1` | Strong | Additive only; never remove fields |
Conversion webhook required when:
- Multiple versions are served simultaneously
- A field's shape changed between versions
For simple field renames, `x-kubernetes-conversion-strategy: None` works.
## Scope: Namespaced vs Cluster
Default to **Namespaced**. Cluster-scoped CRDs:
- Can't be RBAC-restricted by namespace
- Can't have `OwnerReferences` from namespaced parents
- Are appropriate only for cluster-wide resources (`StorageClass`-like things)
If your operator manages namespace-bound things (apps, databases, queues), use Namespaced.
## Naming
- **Group**: `<domain>.<reverse-domain>` — e.g., `apps.example.com`. Don't use generic groups (`com`, `io`).
- **Kind**: PascalCase, singular, descriptive — `MyApp`, `Database`, `Cache`. Avoid `MyAppResource` (the `Resource` suffix is implicit).
- **Plural**: lowercase, plural — `myapps`, `databases`, `caches`.
- **Short name**: 2-3 letters; check for conflicts with built-in resources.
## Validation tooling
- `kubectl apply --dry-run=server` — validates against your CRD
- `kubectl explain <kind>.<field>` — shows what your schema documents
- `crd_validator.py` — this skill's tool, structural rules
## Documentation in the schema
Use the `description` field on every property. `kubectl explain` reads it:
```yaml
properties:
replicas:
type: integer
minimum: 1
description: |
Number of replicas to run. Production deployments should use ≥3.
Increases above 100 require quota approval.
```
## Anti-patterns
- **Top-level `x-kubernetes-preserve-unknown-fields: true`** — defeats validation
- **No `scope:` declared** — defaults to namespaced but make intent explicit
- **No printer columns** — `kubectl get` shows only `NAME AGE`
- **Conditions written by hand** (not via `SetStatusCondition`) — easy to lose `lastTransitionTime`
- **Status fields that duplicate spec** — keep them separate
- **Using `metadata.annotations` to encode operator state** — use status fields
- **Single huge CRD with 50+ fields** — split into multiple CRDs (e.g., MyApp + MyAppBackup + MyAppRestore)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |