k8s-controller

Guide Kubernetes controller implementation with controller-runtime and Kubebuilder.

Updated Jan 23, 2026
One-click install
npx skills add https://github.com/pokgak/agent-skills --skill k8s-controller
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: k8s-controller
Source: https://github.com/pokgak/agent-skills/tree/main/skills/k8s-controller
Command: npx skills add https://github.com/pokgak/agent-skills --skill k8s-controller

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Kubernetes controllers often fail in production due to non-idempotent reconciliation, broken finalizer lifecycles, incorrect RBAC, missed watch events, or inefficient workqueue patterns. This skill helps you design and review controller-runtime and Kubebuilder operators that behave correctly under deletes, conflicts, retries, and high event volume.

Core Features & Use Cases

  • Production-grade reconciliation patterns: level-based reconciliation, NotFound handling, and strict idempotency guidance.
  • Correct deletion behavior: finalizer setup, cleanup flow, and safe finalizer removal timing.
  • Controller-runtime setup and watch correctness: predicates, MaxConcurrentReconciles, and safe secondary resource requeue mapping without fragile API calls.
  • Error handling and retries: selecting the right requeue mechanism and handling optimistic concurrency with RetryOnConflict patterns.
  • RBAC/CRD design best practices: kubebuilder marker examples for status subresources, finalizers intent, and validation/print columns.
  • Performance and testing strategy: avoid blocking I/O in Reconcile, reduce API load via selectors/indexing, and test with fake clients + kind-based functional verification.

Quick Start

Use the k8s-controller skill when you are implementing or reviewing a Kubernetes controller and want to apply reliable reconcile, finalizer, RBAC, and watch patterns.

Frequently Asked Questions about k8s-controller

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement level-based idempotent reconciliation in a Kubernetes controller?

Level-based idempotent reconciliation ensures your Kubernetes controller processes the current desired state rather than specific event sequences. This approach handles NotFound resources gracefully and safely retries conflicts without duplicate side effects.

What is the best way to handle finalizer cleanup and deletion in controller-runtime?

Finalizer cleanup in controller-runtime requires adding the finalizer during initial reconciliation, executing deletion logic, and removing the finalizer only after successful cleanup to prevent resource leaks and ensure safe deletion behavior.

How do I configure watch predicates and MaxConcurrentReconciles in Kubebuilder?

Configure watch predicates in Kubebuilder using SetupWithManager to filter irrelevant events, and set MaxConcurrentReconciles to control parallel reconciliation workers, ensuring efficient workqueue processing without overwhelming the API server.

Why does my Kubernetes operator miss watch events or fail under high event volume?

Kubernetes operators miss watch events or fail under high volume due to incorrect predicates, blocking I/O in Reconcile, or inefficient workqueue patterns. Use level-based reconciliation and non-blocking operations to handle surges reliably.

How do I write RBAC markers and CRD validation rules with Kubebuilder?

Write RBAC markers and CRD validation rules in Kubebuilder using kubebuilder markers on your Go types, specifying status subresources, finalizer intent, and print columns to ensure correct permissions and custom resource definitions.

How do I test Kubernetes controllers with fake clients and Kind-based functional verification?

Test Kubernetes controllers using fake clients for unit testing reconciliation logic and Kind clusters for functional verification, validating controller-runtime behavior against real API server semantics and CRD validation rules.