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/reconcile_loop.md
View on GitHub# The reconcile loop
Reconcile is the heart of an operator. Most operator bugs are reconcile-loop bugs. The patterns below are deterministic — copy them.
## Skeleton — `Reconcile(ctx, req)`
```go
func (r *MyAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
log := log.FromContext(ctx)
// 1. Fetch the CR
var cr appsv1alpha1.MyApp
if err := r.Get(ctx, req.NamespacedName, &cr); err != nil {
if apierrors.IsNotFound(err) {
return ctrl.Result{}, nil // CR is gone; nothing to do
}
return ctrl.Result{}, err // transient error → requeue
}
// 2. Handle deletion via finalizer
if !cr.DeletionTimestamp.IsZero() {
return r.reconcileDelete(ctx, &cr)
}
if !controllerutil.ContainsFinalizer(&cr, finalizerName) {
controllerutil.AddFinalizer(&cr, finalizerName)
return ctrl.Result{}, r.Update(ctx, &cr)
}
// 3. Mark Reconciling
meta.SetStatusCondition(&cr.Status.Conditions, metav1.Condition{
Type: "Reconciling", Status: metav1.ConditionTrue,
Reason: "InProgress", Message: "Converging to desired state",
ObservedGeneration: cr.Generation,
})
// 4. Do the work, idempotently
res, err := r.reconcileNormal(ctx, &cr)
// 5. Update status (always — even on error)
if statusErr := r.Status().Update(ctx, &cr); statusErr != nil {
log.Error(statusErr, "failed to update status")
return res, errors.Join(err, statusErr)
}
return res, err
}
```
## The 5-step shape
1. **Fetch the CR.** Handle `NotFound` cleanly — the CR may have been deleted between event and reconcile.
2. **Handle deletion.** If `DeletionTimestamp` is set, run cleanup, remove finalizer, return.
3. **Set Reconciling condition.** Mark that the controller is working.
4. **Do work idempotently.** Use `CreateOrUpdate`, compare desired-vs-actual, only act on differences.
5. **Update status.** Even on error — partial progress is signal.
## Idempotence patterns
### Pattern: CreateOrUpdate
```go
deployment := &appsv1.Deployment{ObjectMeta: metav1.ObjectMeta{Name: cr.Name, Namespace: cr.Namespace}}
op, err := controllerutil.CreateOrUpdate(ctx, r.Client, deployment, func() error {
deployment.Spec.Replicas = &cr.Spec.Replicas
deployment.Spec.Template.Spec.Containers = buildContainers(&cr.Spec)
return controllerutil.SetControllerReference(&cr, deployment, r.Scheme)
})
if err != nil { return ctrl.Result{}, err }
log.Info("deployment", "operation", op) // "created", "updated", or "unchanged"
```
This pattern is idempotent by construction.
### Pattern: SetControllerReference
Always set the OwnerReference so cascading deletion works:
```go
controllerutil.SetControllerReference(&cr, child, r.Scheme)
```
### Pattern: Finalizer for external resources
```go
const finalizerName = "myapp.apps.example.com/finalizer"
func (r *MyAppReconciler) reconcileDelete(ctx context.Context, cr *appsv1alpha1.MyApp) (ctrl.Result, error) {
if !controllerutil.ContainsFinalizer(cr, finalizerName) {
return ctrl.Result{}, nil
}
if err := r.deleteExternalResources(ctx, cr); err != nil {
return ctrl.Result{RequeueAfter: 30 * time.Second}, err
}
controllerutil.RemoveFinalizer(cr, finalizerName)
return ctrl.Result{}, r.Update(ctx, cr)
}
```
## Error handling and requeue
| Situation | Return |
|---|---|
| Permanent error (bad spec) | `ctrl.Result{}, nil` + condition with reason |
| Transient error (API timeout, throttling) | `ctrl.Result{}, err` (auto-requeue with backoff) |
| Need a retry in N seconds | `ctrl.Result{RequeueAfter: 30*time.Second}, nil` |
| Done; no follow-up | `ctrl.Result{}, nil` |
**Don't use `time.Sleep` inside reconcile.** It blocks the work queue, starving other reconciles. Use `RequeueAfter`.
## Status update patterns
```go
// Set a condition
meta.SetStatusCondition(&cr.Status.Conditions, metav1.Condition{
Type: "Ready", Status: metav1.ConditionTrue,
Reason: "AllReady", Message: "all components healthy",
ObservedGeneration: cr.Generation,
})
// Track observed generation
cr.Status.ObservedGeneration = cr.Generation
// Update status — uses /status subresource
if err := r.Status().Update(ctx, &cr); err != nil { ... }
```
**Never** call `r.Update(ctx, &cr)` to update status. It uses the spec subresource, which the user owns.
## Read once, decide, act
Don't observe the world repeatedly during reconcile. The cache is read-only and consistent within a single reconcile pass:
```go
// Good: read once, decide, act
var pods corev1.PodList
r.List(ctx, &pods, client.InNamespace(cr.Namespace), client.MatchingLabels{"app": cr.Name})
desired := computeDesired(&cr, &pods)
applyDesired(ctx, r.Client, desired)
// Bad: observe-act-observe-act
for _, container := range cr.Spec.Containers {
pod := r.Get(...) // re-reading the cache
if needsRestart(pod) {
r.Delete(...)
pod = r.Get(...) // again
...
}
}
```
## Predicates — filter events you don't care about
```go
func (r *MyAppReconciler) SetupWithManager(mgr ctrl.Manager) error {
return ctrl.NewControllerManagedBy(mgr).
For(&appsv1alpha1.MyApp{}).
Owns(&appsv1.Deployment{}).
WithEventFilter(predicate.GenerationChangedPredicate{}). // ignore status-only updates
Complete(r)
}
```
`GenerationChangedPredicate` skips reconciles when only status changed — important to avoid loops.
## Leader election
Always enable leader election when running >1 controller replica:
```go
mgr, _ := manager.New(cfg, manager.Options{
LeaderElection: true,
LeaderElectionID: "myapp-operator-leader",
})
```
Without it: split-brain. Two controllers both think they own the resource and fight.
## Performance — bounded reconcile time
A reconcile pass should complete in <30s for typical work, <2min for heavy work. Longer = the work queue starves other reconciles.
If work takes longer:
- Break into phases; emit `RequeueAfter` between them
- Move long-running work to a separate process (Job)
- Cache expensive computations on `cr.Status`
## Logging conventions
```go
log := log.FromContext(ctx).WithValues("phase", "create-deployment")
log.Info("creating deployment", "name", cr.Name)
log.Error(err, "failed to create deployment")
```
- Use `log.FromContext(ctx)` — picks up controller-runtime's contextual logger
- Use `Info` for normal flow, `Error` for retryable failures
- Add structured fields, not formatted strings
## Anti-patterns checklist
- `time.Sleep` inside reconcile → starves queue; use `RequeueAfter`
- `os.Exit` / `log.Fatal` → kills the controller; return an error
- `panic` → same; return an error
- `r.Update` to set status → use `r.Status().Update`
- `r.Update` of the CR while the user could be editing it → use `r.Status().Update` or use Patch
- Reading the same resource multiple times in one reconcile → read once
- Reconcile body > 80 lines → extract `reconcileXxx` subroutines per phase
- HTTP calls without `ctx` → can't cancel during shutdown
- No requeue path for transient errors → silent failures
- Missing `OwnerReferences` on children → cascading deletion broken
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 |