Kubernetes API and Object Model Scope

Kubernetes API and Object Model Scope refers to the boundaries and organizing principles that define what the Kubernetes API actually covers, how the resources it exposes are structured, and how that structure relates to the broader system's behavior — establishing that Kubernetes is, at its core, a declarative, object-oriented API for expressing cluster state rather than an imperative command interface for issuing operational instructions. Understanding this scope is what allows every other Kubernetes concept, from Pods to controllers to custom resources, to be understood as instances of the same small set of underlying patterns rather than as unrelated, special-cased features.

The API as the Single Source of Truth

Everything Is an API Object

Virtually every piece of cluster state that Kubernetes manages — workloads, networking configuration, storage, policy, and even cluster extension mechanisms — is represented as a structured API object stored durably in the cluster's backing store (etcd, accessed exclusively through the API server), meaning there is no meaningful Kubernetes state that exists outside of this object model.

Declarative Rather Than Imperative

The scope of the API is deliberately declarative: clients express a desired end state by writing or updating an object's spec, rather than issuing commands describing a sequence of actions to perform, and it is left to controllers observing that object to determine and carry out whatever actions are needed to make reality match the declared spec.

The Common Object Structure

TypeMeta and ObjectMeta

Every Kubernetes object shares a common structural skeleton: TypeMeta identifies what kind of object it is and which API version defines it, while ObjectMeta carries identity and bookkeeping information common to all objects — name, namespace, labels, annotations, a unique identifier, a resource version, owner references, and finalizers — regardless of whether the object represents a Pod, a Service, or a custom resource.

Spec and Status Separation

Most objects further divide their type-specific content into a spec, representing the desired state a client wants, and a status, representing the last observed actual state as reported by the responsible controller; this separation, enforced at the API level through separate subresources for many built-in types, is what allows RBAC to distinguish who may declare desired state from who may report observed state.

API Groups and Versioning

Why API Groups Exist

The API is partitioned into groups — such as the core group (historically unnamed, containing types like Pod and Service), apps, batch, networking.k8s.io, and many others — allowing related resource types to evolve together and allowing entirely new groups to be added, including by third parties, without requiring changes to unrelated parts of the API surface.

Version Stability Levels

Within a group, each resource type is exposed under one or more versions following a maturity convention — alpha versions that may change or disappear without notice, beta versions that are more stable but not yet guaranteed, and stable versions (typically v1) that carry strong backward-compatibility guarantees — and this versioning scope is what allows the API to evolve continuously without breaking existing clients relying on stable versions.

Cluster-Scoped Versus Namespace-Scoped Resources

Namespace as a Partitioning Boundary

Most workload-related resource types are namespace-scoped, meaning each instance belongs to exactly one Namespace and is only uniquely identified by the combination of its name and namespace, which is the primary mechanism the object model provides for partitioning a single cluster into multiple logically isolated environments.

Cluster-Scoped Resources

Certain resource types — Nodes, PersistentVolumes, ClusterRoles, and Namespaces themselves among them — exist outside any namespace, uniquely identified by name alone across the whole cluster, reflecting that these resources represent cluster-wide infrastructure or policy rather than anything meaningfully scoped to a single application or team.

Extending the Object Model

Custom Resource Definitions

The scope of the API and object model is not fixed to its built-in types; CustomResourceDefinitions allow new resource types to be registered dynamically, following the exact same TypeMeta/ObjectMeta/spec/status structural conventions and becoming addressable through the same API server, kubectl, and RBAC machinery as any built-in type.

Aggregated API Servers

For cases requiring behavior beyond what CRDs alone support, the object model's scope can be extended further through aggregated API servers, which implement the Kubernetes API conventions independently while being registered to appear as a seamless part of the same overall API surface to clients.