Unlock Kubernetes Secrets: A Go Source Dive into Its Core Architecture

Why Dive into Kubernetes Source Code

For Go developers and cloud engineers, merely using kubectl is not enough; understanding the internals through the actual Go implementation reveals how the system achieves declarative state convergence, high availability, and extensibility.

Key Concepts Overview

Kubernetes is a declarative state‑tuning system : users declare the desired state, controllers and Kubelet drive the cluster toward it.

API Server is the single source of truth : all components read and write through it, never communicating directly.

client‑go Informer provides low‑latency event streams without polling, reducing API server load.

All controllers share a common pattern : watch events → enqueue → reconcile → retry/idempotent handling.

Kubelet is the node‑level executor : it turns pod specifications into running containers.

Control Loop Explained

The core reconciliation loop runs forever, pulling keys from a work queue, invoking the reconcile function, handling errors with rate‑limited retries, and marking the work as done.

for { // daemon loop
    key := queue.Get() // block until an item
    err := reconcile(key) // compare actual vs desired state
    if err != nil {
        queue.AddRateLimited(key) // retry with back‑off
    }
    queue.Done(key) // mark completion
}

This loop is the heart of every controller, ensuring convergence rather than issuing imperative commands.

Informer Event Flow

Informers act as a local, real‑time cache that watches the API server, stores events in a DeltaFIFO queue, and broadcasts them to registered handlers.

APIServer (source) --watch--> Reflector (mover) --> DeltaFIFO (queue) --> SharedInformer (cache + broadcaster) --> Handlers (event callbacks)

Controller Reconcile Logic

Controllers translate the desired replica count into concrete actions: create pods when actual < desired, delete pods when actual > desired.

func (c *Controller) reconcile(key string) error {
    deploy := c.lister.Get(key)
    actual := countPods(deploy) // current state
    desired := deploy.Spec.Replicas // desired state
    if actual < desired {
        createPod()
    } else if actual > desired {
        deletePod()
    }
    return nil
}

Kubelet Execution Path

Kubelet turns pod specifications into running containers through a series of components.

PodWorkers : one worker per pod, ensuring serialized processing.

syncLoop : watches pod updates, PLEG events, and probes.

PLEG : detects container state changes from the container runtime.

RuntimeManager : invokes the CRI (e.g., containerd) to create or delete containers.

Pod update → PodWorkers queue → syncPod → create sandbox → create container → probe checks

Extensibility: CRDs and Admission Webhooks

Custom Resource Definitions (CRDs) extend the API by registering a new GroupVersionKind (GVK) in the API server’s runtime scheme, reusing the same RESTStorage path as built‑in resources and persisting to etcd.

Admission webhooks intercept requests before they are stored, allowing mutating or validating logic.

Request → Mutating webhook (add fields) → Validating webhook (check) → write to etcd

Minimal Controller Example

A tiny controller can be built with a shared informer factory, an event handler, and the usual start‑and‑wait pattern.

// Create an informer factory
factory := informers.NewSharedInformerFactory(clientset, 0)
// Get a Pod informer
podInformer := factory.Core().V1().Pods().Informer()
// Register event handler
podInformer.AddEventHandler(cache.ResourceEventHandlerFuncs{
    AddFunc: func(obj interface{}) {
        fmt.Println("[Add]", obj.(*v1.Pod).Name)
    },
})
// Start informers and wait for cache sync
factory.Start(stopCh)
factory.WaitForCacheSync(stopCh)

Running this prints "[Add] podexample" for each new pod, illustrating the generic controller pattern.

Conclusion

Kubernetes’s design revolves around a declarative model, a perpetual control loop, and event‑driven components. The API server acts as the truth hub, informers stream changes, controllers reconcile state, and Kubelet executes workloads. This architecture yields self‑healing, extensible, and highly modular clusters, and mastering these pieces opens the door to deeper topics such as scheduler internals, custom plugins, and advanced API‑server extensions.