docs: add when/when-not to all Kubernetes patterns
This commit is contained in:
@@ -106,6 +106,44 @@ func (c *Scheduler) Reconcile(ctx context.Context, key string) error {
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- The operation is truly one-shot with no ongoing state to maintain (e.g., a CLI tool, a migration script)
|
||||
- You're building a simple request/response service where each request is independent
|
||||
- The "desired state" changes so frequently that reconciliation would always be stale (use streaming/event-driven instead)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Over-engineered: a controller for sending one-time notifications
|
||||
type NotificationController struct {
|
||||
queue workqueue.TypedRateLimitingInterface[string]
|
||||
}
|
||||
|
||||
func (c *NotificationController) Reconcile(ctx context.Context, key string) error {
|
||||
notification, _ := c.lister.Get(key)
|
||||
if notification.Status.Sent {
|
||||
return nil // already sent
|
||||
}
|
||||
err := c.sendEmail(notification)
|
||||
if err == nil {
|
||||
notification.Status.Sent = true
|
||||
c.client.Update(ctx, notification)
|
||||
}
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:**
|
||||
```go
|
||||
// Simple job processor: one-time work doesn't need continuous reconciliation
|
||||
func processNotification(ctx context.Context, notification Notification) error {
|
||||
return sendEmail(notification)
|
||||
}
|
||||
```
|
||||
|
||||
**Why:** The controller pattern adds substantial complexity (informers, caches, workqueue, leader election). If your state doesn't drift — if once you do the thing, it stays done — a simple worker or job queue is far more appropriate.
|
||||
|
||||
### Key Properties
|
||||
1. **Level-triggered, not edge-triggered** — the sync loop reads current state, not diffs
|
||||
2. **Idempotent** — running sync twice produces the same result
|
||||
@@ -182,6 +220,75 @@ if !cache.WaitForNamedCacheSyncWithContext(ctx, dc.dListerSynced, dc.rsListerSyn
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Triggers:**
|
||||
- Multiple components in the same process need to read the same Kubernetes resources
|
||||
- You're building a controller that reacts to state changes but needs fast local reads
|
||||
- API server load is a concern (you have many controllers or high-frequency reads)
|
||||
|
||||
**Example — before:**
|
||||
```go
|
||||
// Every reconcile calls the API server directly — O(controllers × syncs/sec) load
|
||||
func (c *Controller) Reconcile(ctx context.Context, key string) error {
|
||||
pod, err := c.client.CoreV1().Pods(ns).Get(ctx, name, metav1.GetOptions{})
|
||||
if err != nil { return err }
|
||||
|
||||
nodes, err := c.client.CoreV1().Nodes().List(ctx, metav1.ListOptions{})
|
||||
if err != nil { return err }
|
||||
// ... reconcile
|
||||
}
|
||||
```
|
||||
|
||||
**Example — after:**
|
||||
```go
|
||||
// Reads from local cache — zero API server load for reads
|
||||
func (c *Controller) Reconcile(ctx context.Context, key string) error {
|
||||
pod, err := c.podLister.Pods(ns).Get(name) // local cache
|
||||
if err != nil { return err }
|
||||
|
||||
nodes, err := c.nodeLister.List(labels.Everything()) // local cache
|
||||
if err != nil { return err }
|
||||
// ... reconcile (only writes hit the API server)
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- You're building a short-lived CLI tool or one-shot script (informers need time to sync)
|
||||
- You need strongly consistent reads (informer cache is eventually consistent — may lag by seconds)
|
||||
- You only access a resource once or twice (the overhead of List+Watch isn't justified)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// One-shot migration script using informers — overkill
|
||||
func main() {
|
||||
factory := informers.NewSharedInformerFactory(client, 0)
|
||||
podInformer := factory.Core().V1().Pods()
|
||||
factory.Start(ctx.Done())
|
||||
factory.WaitForCacheSync(ctx.Done())
|
||||
|
||||
pods, _ := podInformer.Lister().List(labels.Everything())
|
||||
for _, pod := range pods {
|
||||
migratePod(pod)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:**
|
||||
```go
|
||||
// Just list directly — you only need the data once
|
||||
func main() {
|
||||
pods, _ := client.CoreV1().Pods("").List(ctx, metav1.ListOptions{})
|
||||
for _, pod := range pods.Items {
|
||||
migratePod(&pod)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why:** Informers are designed for long-running processes that continuously react to changes. For one-shot reads, a direct List call is simpler, faster to start, and uses less memory.
|
||||
|
||||
---
|
||||
|
||||
## 3. Workqueue: Typed Rate-Limiting Queue
|
||||
@@ -242,6 +349,39 @@ if err != nil {
|
||||
queue.Done(key)
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- Order of processing matters (the workqueue doesn't guarantee FIFO for rate-limited items)
|
||||
- Each event carries unique payload data that must be processed individually (workqueue only stores keys, not event data)
|
||||
- You have a single producer and single consumer with no contention (a plain channel suffices)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Using workqueue for ordered log processing — wrong tool
|
||||
queue := workqueue.NewTypedRateLimitingQueue[string](limiter)
|
||||
|
||||
// Each log line is unique and order matters
|
||||
queue.Add("log-line-1")
|
||||
queue.Add("log-line-2")
|
||||
queue.Add("log-line-3")
|
||||
// Problem: if "log-line-1" fails and gets rate-limited,
|
||||
// "log-line-2" processes first → out of order
|
||||
```
|
||||
|
||||
**Better alternative:**
|
||||
```go
|
||||
// Ordered processing needs a simple buffered channel or sequential queue
|
||||
logs := make(chan LogEntry, 1000)
|
||||
for entry := range logs {
|
||||
if err := processLog(entry); err != nil {
|
||||
retryWithBackoff(entry) // handle retry inline, preserving order
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why:** The workqueue's strength is deduplication and rate-limited retry for key-based reconciliation. If your items are unique (not deduplicate-able) or ordering matters, use a channel or ordered queue instead.
|
||||
|
||||
### The Dirty/Processing Dance
|
||||
|
||||
```go
|
||||
@@ -326,6 +466,67 @@ func (dc *DeploymentController) deleteDeployment(logger klog.Logger, obj interfa
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Triggers:**
|
||||
- You're writing a delete event handler for a Kubernetes informer
|
||||
- Your system uses List+Watch and must handle watch disconnection gracefully
|
||||
- You need to process all deletions, including those that occurred during downtime
|
||||
|
||||
**Example — before:**
|
||||
```go
|
||||
// Naive delete handler — breaks silently during watch reconnection
|
||||
func (c *Controller) onDelete(obj interface{}) {
|
||||
pod := obj.(*v1.Pod) // PANIC: obj might be DeletedFinalStateUnknown
|
||||
c.cleanup(pod)
|
||||
}
|
||||
```
|
||||
|
||||
**Example — after:**
|
||||
```go
|
||||
// Tombstone-aware delete handler — handles all cases
|
||||
func (c *Controller) onDelete(obj interface{}) {
|
||||
pod, ok := obj.(*v1.Pod)
|
||||
if !ok {
|
||||
tombstone, ok := obj.(cache.DeletedFinalStateUnknown)
|
||||
if !ok {
|
||||
runtime.HandleError(fmt.Errorf("unexpected object type: %T", obj))
|
||||
return
|
||||
}
|
||||
pod, ok = tombstone.Obj.(*v1.Pod)
|
||||
if !ok {
|
||||
runtime.HandleError(fmt.Errorf("tombstone contained non-Pod: %T", tombstone.Obj))
|
||||
return
|
||||
}
|
||||
}
|
||||
c.cleanup(pod)
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- You're not using informers (direct API calls return concrete types, never tombstones)
|
||||
- Your delete handler only enqueues a key for reconciliation (the reconciler will discover the deletion via a NotFound error from the lister — tombstone handling in the handler is optional)
|
||||
- You're building a non-Kubernetes system (this is specific to client-go's watch semantics)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Tombstone handling in a reconciler that already handles "not found"
|
||||
func (c *Controller) Reconcile(ctx context.Context, key string) error {
|
||||
obj, err := c.lister.Get(key)
|
||||
if errors.IsNotFound(err) {
|
||||
// Object was deleted — clean up
|
||||
return c.handleDeletion(key)
|
||||
}
|
||||
// No need for tombstone logic here — the lister never returns tombstones
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:** Tombstone handling belongs in event handler callbacks (AddFunc/UpdateFunc/DeleteFunc), not in the reconcile loop. The reconciler discovers deletions through "not found" errors from the lister.
|
||||
|
||||
**Why:** Tombstones are an artifact of the event delivery mechanism. If your architecture already handles "object doesn't exist" as a valid reconciliation state, you don't need to explicitly handle tombstones everywhere.
|
||||
|
||||
---
|
||||
|
||||
## 5. Controller Expectations Pattern
|
||||
@@ -352,6 +553,79 @@ type ControllerExpectationsInterface interface {
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Triggers:**
|
||||
- Your controller creates or deletes child resources and uses informer cache to count them
|
||||
- You observe duplicate creates/deletes during rapid reconciliation
|
||||
- There's a visible lag between your write and the cache reflecting the new state
|
||||
|
||||
**Example — before:**
|
||||
```go
|
||||
// Without expectations: reconcile loop creates duplicates
|
||||
func (c *RSController) Reconcile(ctx context.Context, key string) error {
|
||||
rs, _ := c.rsLister.Get(key)
|
||||
pods, _ := c.podLister.Pods(rs.Namespace).List(selector)
|
||||
|
||||
diff := int(*rs.Spec.Replicas) - len(pods)
|
||||
if diff > 0 {
|
||||
// Cache hasn't caught up from last reconcile → creates AGAIN
|
||||
for i := 0; i < diff; i++ {
|
||||
c.client.CoreV1().Pods(rs.Namespace).Create(ctx, newPod(), ...)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
**Example — after:**
|
||||
```go
|
||||
// With expectations: skip reconcile until cache catches up
|
||||
func (c *RSController) Reconcile(ctx context.Context, key string) error {
|
||||
if !c.expectations.SatisfiedExpectations(logger, key) {
|
||||
return nil // still waiting for previous creates to appear in cache
|
||||
}
|
||||
|
||||
rs, _ := c.rsLister.Get(key)
|
||||
pods, _ := c.podLister.Pods(rs.Namespace).List(selector)
|
||||
|
||||
diff := int(*rs.Spec.Replicas) - len(pods)
|
||||
if diff > 0 {
|
||||
c.expectations.ExpectCreations(logger, key, diff)
|
||||
for i := 0; i < diff; i++ {
|
||||
_, err := c.client.CoreV1().Pods(rs.Namespace).Create(ctx, newPod(), ...)
|
||||
if err != nil {
|
||||
c.expectations.CreationObserved(logger, key) // decrement on failure
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- Your controller only updates existing resources (no creates/deletes of children)
|
||||
- You use server-side apply or optimistic concurrency (conflicts are resolved by the API server)
|
||||
- Your reconciliation is idempotent even with stale cache (e.g., "ensure this ConfigMap has these contents" — creating it twice returns AlreadyExists)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Expectations for a controller that only patches status — unnecessary
|
||||
func (c *StatusController) Reconcile(ctx context.Context, key string) error {
|
||||
if !c.expectations.SatisfiedExpectations(logger, key) {
|
||||
return nil // This gate adds nothing — we're only patching, not creating
|
||||
}
|
||||
obj, _ := c.lister.Get(key)
|
||||
return c.client.Status().Patch(ctx, obj, patch)
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:** Just patch directly. Status updates via patch are idempotent and don't create duplicate resources. Expectations only matter when create/delete timing could cause over-provisioning.
|
||||
|
||||
**Why:** Expectations add bookkeeping complexity. They solve a specific problem: cache lag causing duplicate creates/deletes. If your controller doesn't create or delete child resources, the problem doesn't exist.
|
||||
|
||||
---
|
||||
|
||||
## 6. OwnerReference / Controller Ref Manager Pattern
|
||||
@@ -392,6 +666,72 @@ func (m *BaseControllerRefManager) ClaimObject(ctx context.Context, obj metav1.O
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Triggers:**
|
||||
- Your controller creates child resources that should be garbage-collected when the parent is deleted
|
||||
- Multiple controllers might "compete" for ownership of the same resources (e.g., label selector changes)
|
||||
- You need to handle adoption: a resource's owner was deleted but the resource still exists
|
||||
|
||||
**Example — before:**
|
||||
```go
|
||||
// Manual cleanup — fragile, misses edge cases
|
||||
func (c *Controller) deleteParent(ctx context.Context, parent *MyResource) error {
|
||||
children, _ := c.childLister.List(labelsForParent(parent))
|
||||
for _, child := range children {
|
||||
c.client.Delete(ctx, child.Name, metav1.DeleteOptions{})
|
||||
}
|
||||
return c.client.Delete(ctx, parent.Name, metav1.DeleteOptions{})
|
||||
// What if we crash between deleting children and parent?
|
||||
// What if labels change and we miss some children?
|
||||
}
|
||||
```
|
||||
|
||||
**Example — after:**
|
||||
```go
|
||||
// OwnerReference + garbage collector handles cleanup automatically
|
||||
func (c *Controller) createChild(ctx context.Context, parent *MyResource) error {
|
||||
child := &v1.Pod{
|
||||
ObjectMeta: metav1.ObjectMeta{
|
||||
OwnerReferences: []metav1.OwnerReference{
|
||||
*metav1.NewControllerRef(parent, myGVK),
|
||||
},
|
||||
},
|
||||
}
|
||||
_, err := c.client.CoreV1().Pods(parent.Namespace).Create(ctx, child, metav1.CreateOptions{})
|
||||
return err
|
||||
// When parent is deleted, GC automatically deletes all children
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- Child resources should outlive their parent (e.g., PersistentVolumes that persist after the PVC is deleted)
|
||||
- Resources are truly independent — no parent/child lifecycle relationship exists
|
||||
- You're working outside Kubernetes (OwnerReferences are a Kubernetes API concept)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Setting owner reference on a shared ConfigMap used by many controllers
|
||||
func (c *Controller) ensureSharedConfig(ctx context.Context, parent *MyResource) error {
|
||||
cm := &v1.ConfigMap{
|
||||
ObjectMeta: metav1.ObjectMeta{
|
||||
Name: "shared-config",
|
||||
OwnerReferences: []metav1.OwnerReference{
|
||||
*metav1.NewControllerRef(parent, myGVK), // WRONG: shared resource
|
||||
},
|
||||
},
|
||||
}
|
||||
// Problem: when this parent is deleted, the shared ConfigMap is garbage-collected,
|
||||
// breaking all other controllers that depend on it
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:** Shared resources should not have owner references. Use finalizers on the parent to perform cleanup only of resources that are truly owned, or use labels + a dedicated cleanup controller.
|
||||
|
||||
**Why:** OwnerReferences create a hard lifecycle coupling: parent deletion cascades to children. This is exactly right for "this ReplicaSet owns these Pods" but catastrophic for shared resources.
|
||||
|
||||
---
|
||||
|
||||
## 7. Leader Election Pattern
|
||||
@@ -438,6 +778,42 @@ func main() {
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- Your workload can be safely sharded across replicas (e.g., each replica handles a different namespace)
|
||||
- The work is read-only or idempotent at the individual item level (multiple readers are fine)
|
||||
- You only ever run one replica (single-instance deployment — leader election is pointless overhead)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Leader election for a metrics collector that only reads
|
||||
func main() {
|
||||
leaderelection.RunOrDie(ctx, leaderelection.LeaderElectionConfig{
|
||||
Lock: resourceLock,
|
||||
Callbacks: leaderelection.LeaderCallbacks{
|
||||
OnStartedLeading: func(ctx context.Context) {
|
||||
collectMetrics(ctx) // reads metrics from nodes — safe to run on all replicas
|
||||
},
|
||||
},
|
||||
})
|
||||
// Problem: 2 of 3 replicas sit idle, collecting no metrics
|
||||
}
|
||||
```
|
||||
|
||||
**Better alternative:**
|
||||
```go
|
||||
// All replicas collect metrics (sharded by node or running in parallel)
|
||||
func main() {
|
||||
nodes := getAssignedNodes() // shard assignment via consistent hashing
|
||||
for _, node := range nodes {
|
||||
go collectMetricsForNode(ctx, node)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why:** Leader election serializes all work to one instance. This is correct for writes that would conflict, but wasteful for reads or shardable work. Use it only when concurrent execution would cause correctness problems.
|
||||
|
||||
### Why
|
||||
Controller-manager runs multiple replicas for HA. Only one should reconcile to avoid conflicts.
|
||||
|
||||
@@ -520,3 +896,74 @@ func init() {
|
||||
runtime.Must(utilfeature.DefaultMutableFeatureGate.AddVersioned(defaultVersionedKubernetesFeatureGates))
|
||||
}
|
||||
```
|
||||
|
||||
### When to Use
|
||||
|
||||
**Triggers:**
|
||||
- You ship a binary to many environments (clusters, customers) that need different feature sets
|
||||
- New features are risky and must be progressively rolled out (alpha → beta → GA)
|
||||
- You need to disable a feature at runtime without redeploying (kill switch)
|
||||
- Multiple versions of your software coexist, and features must have version-aware behavior
|
||||
|
||||
**Example — before:**
|
||||
```go
|
||||
// Compile-time flags or environment variables — no lifecycle, no versioning
|
||||
func reconcile(ctx context.Context, obj *MyResource) error {
|
||||
if os.Getenv("ENABLE_NEW_SCHEDULING") == "true" {
|
||||
return newSchedulingLogic(ctx, obj)
|
||||
}
|
||||
return oldSchedulingLogic(ctx, obj)
|
||||
}
|
||||
// Problem: no structured lifecycle. How do you deprecate this? When is it safe to remove?
|
||||
```
|
||||
|
||||
**Example — after:**
|
||||
```go
|
||||
const NewSchedulingAlgorithm featuregate.Feature = "NewSchedulingAlgorithm"
|
||||
|
||||
// Registered with lifecycle metadata
|
||||
var defaultFeatureGates = map[featuregate.Feature]featuregate.FeatureSpec{
|
||||
NewSchedulingAlgorithm: {Default: false, PreRelease: featuregate.Alpha}, // v1.28
|
||||
// Later: {Default: true, PreRelease: featuregate.Beta} // v1.30
|
||||
// Later: {LockToDefault: true, PreRelease: featuregate.GA} // v1.32
|
||||
}
|
||||
|
||||
func reconcile(ctx context.Context, obj *MyResource) error {
|
||||
if featuregate.DefaultFeatureGate.Enabled(NewSchedulingAlgorithm) {
|
||||
return newSchedulingLogic(ctx, obj)
|
||||
}
|
||||
return oldSchedulingLogic(ctx, obj)
|
||||
}
|
||||
```
|
||||
|
||||
### When NOT to Use
|
||||
|
||||
**Don't use this when:**
|
||||
- You have a simple application with one deployment target (just use config or env vars)
|
||||
- The "feature" is actually user-facing configuration (use a config field on the resource, not a gate)
|
||||
- You can safely always enable the feature (no risk, no need for a kill switch)
|
||||
|
||||
**Over-application example:**
|
||||
```go
|
||||
// Feature gate for a trivial log format change — overkill
|
||||
const JSONLogging featuregate.Feature = "JSONLogging"
|
||||
|
||||
func setupLogger() {
|
||||
if featuregate.DefaultFeatureGate.Enabled(JSONLogging) {
|
||||
log.SetFormatter(JSONFormatter{})
|
||||
} else {
|
||||
log.SetFormatter(TextFormatter{})
|
||||
}
|
||||
}
|
||||
// This never needs alpha/beta/GA lifecycle. It's just config.
|
||||
```
|
||||
|
||||
**Better alternative:**
|
||||
```go
|
||||
// Simple configuration flag
|
||||
type Config struct {
|
||||
LogFormat string `json:"logFormat"` // "json" or "text"
|
||||
}
|
||||
```
|
||||
|
||||
**Why:** Feature gates add cognitive overhead (registry, lifecycle stages, version tracking). They're justified for behavioral changes that carry risk and need graduated rollout. For simple configuration choices with no risk dimension, a config field is clearer and simpler.
|
||||
|
||||
Reference in New Issue
Block a user