Kubernetes Operator Design and Reconcile Repair
Design CRDs and repair operator reconcile loops with explicit ownership, safe retries, finalizers, status, and failure tests.
Before & after
Same prompt, same agent — the only difference is the skill.
Building a Kubernetes operator is a complex task. You'll need to understand the operator pattern and how custom resources work. You should start by defining your Custom Resource Definition that describes what you want to manage. Then you'll need to build a controller that watches for changes to your CRD and takes action. The controller logic needs to reconcile the desired state with the actual state in your cluster. You'll probably want to use a framework like Operator SDK or Kubebuilder to help with the scaffolding. Testing your operator thoroughly is important. You should also think about logging, error handling, and edge cases. Would you like guidance on any particular part of the operator development process?
OPERATOR SCAFFOLD: DatabaseBackup CRD to Cloud Storage
CRD DEFINITION
apiVersion: storage.example.com/v1
kind: DatabaseBackup
metadata: name: prod-postgres-daily
spec:
database: postgresql-prod
schedule: 0 2 * * * (2 AM daily)
destination: s3://backups/prod-db
retention: 30 (days)
compressionFormat: gzip
RECONCILE LOOP FLOW
Watch event: DatabaseBackup created/updated
Fetch current: Is backup job running? Last backup timestamp?
Desired state: According to spec, when is next backup due?
Action: If due, create Kubernetes Job manifest
Job: Runs pg_dump, uploads to S3, updates status.lastBackupTime
Status patch: DatabaseBackup shows lastBackupTime, nextBackupTime, backupSize
Cleanup: Delete completed Job after 24 hours
Error handling: Set status Failed, trigger alert if backup fails
VALIDATION & LINTING
CRD validator: Checks cron syntax, retention positive, path valid
Reconcile linter: Detects loops, missing Owner References
Test suite: Unit tests for state transitions, integration with fake apiserver
CAPABILITY LEVEL AUDIT
Level 1: Install and auto-backup (reconcile complete)
Level 2: Restore from backup (secondary RestoreRequest CRD controller)
Level 3: Multi-region failover (replica destinations in spec)
Current: Level 1. Roadmap: Level 2 next release
DEPLOYMENT
Controller image: backup-operator:v1.0.0
RBAC: ClusterRole for core/jobs, storage.example.com/backups
Usage: kubectl apply -f DatabaseBackup.yamlAbout this skill
Your operator works on the first reconcile, then creates duplicates, keeps updating status, or leaves resources stuck behind a finalizer. This skill designs the CRD contract and traces the controller through retries, stale reads, restarts, deletion, and upgrades so those failures become concrete fixes.
What it does
- Designs CRD schemas with validation, defaults, list semantics, status conditions, and version migration considerations.
- Turns a reconcile loop into an explicit convergence process with ownership checks, bounded work, and safe external side effects.
- Diagnoses hot loops, missing watch events, resource-version conflicts, duplicate resources, and stuck deletion.
- Chooses among controller-runtime, Kubebuilder, Operator SDK, Kopf, and declarative controller approaches based on the lifecycle being managed.
- Produces failure tests for repeated reconciles, crash recovery, concurrent edits, child deletion, and external API outages.
- Audits operator maturity using evidence from installation, upgrades, lifecycle management, observability, and autonomous recovery.
What you get
A scoped implementation, repair patch, or operator design with the CRD contract, reconciliation behavior, ownership and deletion policy, and specific tests. Reviews identify the failure mechanism and smallest useful correction rather than returning a generic Kubernetes checklist.
Best for
Engineers building custom controllers, platform teams reviewing operator designs, and maintainers debugging operators that manage Kubernetes children or external services.
SKILL.md preview
---
name: kubernetes-operator-design-and-reconcile-repair
description: Design Kubernetes Operator CRDs and implement or repair reconciliation using explicit ownership, crash-safe side effects, finalizers, status conditions, and failure-path tests. Use when the user says "build an operator", "review this CRD", "my reconcile loop keeps running", "my operator creates duplicate resources", "this custom resource is stuck terminating", "choose an operator framework", "make this controller safe to retry", or "audit our operator's capability level".
---
# Kubernetes Operator Design and Reconcile Repair
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.