Kubernetes Foundations

Kubernetes Foundations comprises the conceptual and architectural building blocks that underlie the Kubernetes platform: the design principles, core abstractions, and system properties that make container orchestration possible at scale. These foundations explain why Kubernetes is structured the way it is, independent of any single feature or API object, and provide the vocabulary needed to reason about how the platform behaves.

Design Principles

Declarative Configuration

Kubernetes is built around a declarative model in which users specify the desired end state of a system rather than the sequence of steps required to reach it. The platform is responsible for determining and executing whatever actions are necessary to move from the current state to the desired state. This contrasts with imperative systems, where an operator must explicitly script each transition.

Level-Triggered, Not Edge-Triggered

Kubernetes controllers are level-triggered: they continuously evaluate the current state of the system against the desired state, rather than reacting only to discrete change events. This property gives the system resilience against missed events, restarts, and partial failures, since any controller can recover simply by re-observing the current state.

Composability Over Monoliths

Rather than exposing a small number of large, rigid abstractions, Kubernetes exposes a set of small, composable primitives, Pods, Services, Volumes, and Labels, that can be combined to build higher-level behavior. Complex workload types such as Deployments and StatefulSets are themselves built as controllers layered on top of these primitives, rather than being special-cased inside the core system.

The API Machinery

Resources and the API Server

Every object in Kubernetes, whether built in or user defined, is represented as a resource exposed through a uniform RESTful API served by the kube-apiserver. Each resource has a kind, an API version, and a schema. Clients read and write objects by sending HTTP requests to resource-specific endpoints, and the API server persists the resulting state to etcd.

The Watch Mechanism

Clients and controllers observe changes to resources through a watch mechanism, an efficient, long-lived HTTP connection over which the API server streams change events as they occur. This mechanism underlies the entire controller model: rather than polling for changes, controllers register watches and react to the resulting stream of add, update, and delete events, while still periodically resyncing to guard against missed events.

Labels and Selectors

Labels are key-value pairs attached to objects, used to organize and select subsets of resources. Label selectors allow controllers and Services to identify the set of objects they are responsible for, decoupling the identity of a workload from any specific naming scheme.

Core System Properties

Self-Healing

Because controllers continuously reconcile actual state toward desired state, the system automatically responds to failures: a Pod that terminates unexpectedly, a node that becomes unreachable, or a container that fails a health check triggers automatic corrective action such as rescheduling or restarting the affected workload.

Horizontal Scalability

The architecture separates the concerns of scheduling, networking, and storage so that additional worker nodes can be added to a cluster to increase capacity without requiring changes to the applications running on it. Workloads themselves can be scaled by adjusting the replica count of a controller, with the system distributing the resulting Pods across available nodes.

Infrastructure Abstraction

Kubernetes presents a consistent API regardless of the underlying infrastructure, whether bare metal, virtual machines, or a specific cloud provider. Provider-specific behavior, such as load balancer provisioning or volume attachment, is isolated behind well-defined interfaces (the Container Runtime Interface, Container Network Interface, and Container Storage Interface), allowing the same manifests to function across heterogeneous environments.

Lifecycle of an Object

1. A client submits a manifest describing a desired object to the API server.
2. The API server validates the request, applies admission control, and persists the object to etcd.
3. Relevant controllers observe the new or changed object through the watch mechanism.
4. Each controller compares the desired state encoded in the object against the current state of the cluster.
5. Controllers issue further API requests to create, update, or delete dependent objects until the observed state converges with the desired state.

kubectl explain pod.spec
kubectl get events --sort-by=.metadata.creationTimestamp
kubectl describe deployment codartium-app

Why These Foundations Matter

Understanding these underlying principles, declarative state, level-triggered reconciliation, composable primitives, and a uniform watchable API, makes it possible to reason correctly about the behavior of any higher-level Kubernetes object or extension. Custom Resource Definitions, Operators, and third-party controllers all build on the same foundational mechanics, so a solid grasp of these fundamentals generalizes across the entire ecosystem rather than being tied to any single feature.