Deep Dive into Kubernetes kubelet: Code Structure, Pod Lifecycle, and Core Modules

Background – Reading source code repeatedly provides deeper understanding than second‑hand knowledge, especially for complex systems like Kubernetes.

Version – The analysis targets Kubernetes v1.13, the version the author works with most frequently.

Overview – The kubelet component lives under the /pkg/kubelet directory of the Kubernetes repository. Its top‑level sub‑directories include modules such as apis/ , cadvisor/ , certificate/ , checkpoint/ , client/ , cloudresource/ , cm/ , config/ , container/ , eviction/ , images/ , kuberuntime/ , lease/ , metrics/ , network/ , pod/ , preemption/ , probe/ , qos/ , remote/ , secret/ , server/ , stats/ , status/ , util/ , volumemanager/ , and many others, each handling a specific aspect of node‑level container management.

The author proposes to follow the pod lifecycle as a guiding thread and lists key questions such as how pods are created, how their state is synced, how containers are launched via the API, how configmaps, secrets, volumes, and networking are managed, and how pods are deleted.

Pod Lifecycle – While a pod’s full lifecycle starts at the controller, this article focuses on what happens after the pod is scheduled to a node (i.e., when nodeName is set).

Starting from kubelet.go – The file /pkg/kubelet/kubelet.go defines the Kubelet struct, the constructor NewMainKubelet , and the main execution method Run(updates <-chan kubetypes.PodUpdate) . The Run method performs the following initialization steps:

Initializes kl.logServer .

Validates kl.kubeClient (may be nil if the apiserver is started by the kubelet).

Starts kl.cloudResourceManager .

Calls kl.initializeModules , which registers Prometheus metrics, creates required directories, sets up container log directories, and starts sub‑modules such as kl.imageManager , kl.serverCertificateManager , kl.oomWatcher , and kl.resourceAnalyzer .

Starts the volume manager kl.volumeManager .

If the apiserver is running, launches goroutines for node status sync, a one‑time immediate sync, and the node lease controller.

Starts goroutines for container runtime uptime sync, iptables rule sync, the pod killer, status manager, probe manager, the PLEG (Pod Lifecycle Event Generator), and finally the main sync loop kl.syncLoop .

The kl.syncLoop receives a <-chan kubetypes.PodUpdate and a SyncHandler interface. The interface is defined as:

// SyncHandler is an interface implemented by Kubelet, for testability
type SyncHandler interface {
    HandlePodAdditions(pods []*v1.Pod)
    HandlePodUpdates(pods []*v1.Pod)
    HandlePodRemoves(pods []*v1.Pod)
    HandlePodReconcile(pods []*v1.Pod)
    HandlePodSyncs(pods []*v1.Pod)
    HandlePodCleanups() error
}

Within kl.syncLoopIteration four channels are observed:

- configCh       <-chan kubetypes.PodUpdate   // triggers Add, Update, Remove, Reconcile
- syncCh         <-chan time.Time           // periodic resync, triggers Syncs
- housekeepingCh <-chan time.Time           // periodic cleanup, triggers Cleanups
- plegCh         <-chan *pleg.PodLifecycleEvent // triggers Syncs

Thus, configCh drives the four core operations (Add, Update, Remove, Reconcile), while syncCh and plegCh invoke HandlePodSyncs , and housekeepingCh invokes HandlePodCleanups . The article raises further questions about how these channels are populated, the relationship between HandlePodSyncs and the other handlers, the distinction between cleanup and removal, and the purpose of periodic sync and housekeeping.

Additional feature‑level topics mentioned include metrics collection, remote command implementation, eviction logic, and CRI integration.

For further reading, the author links to several related posts on Kubernetes networking, ingress, and personal experience summaries.