How Does Kubernetes Turn YAML into Live Objects? A Deep Dive into Declarative APIs

Kubernetes Objects and API Overview

Kubernetes (K8s) stores all resource objects in etcd through the K8s API. Objects are created, modified, or deleted via the API, whether using the kubectl CLI or programmatic clients.

Imperative vs Declarative Management

Three ways to create a Deployment running an Nginx container in the test namespace and scale it to five replicas are demonstrated:

Imperative command

kubectl create deployment nginx-deployment --image nginx -n test

kubectl scale deployment nginx-deployment --replicas 5 -n test

Imperative object configuration Create a nginx.yaml file, then run: kubectl create -f nginx.yaml Modify the replicas field and apply: kubectl replace -f nginx.yaml Declarative object configuration kubectl apply -f nginx.yaml Declarative configuration stores the desired state in a YAML manifest, enabling audit trails and version control.

K8s Object Structure

Each object contains spec (desired state) and status (current state). The API server validates, stores, and persists objects in etcd. Core fields include apiVersion, kind, metadata, and spec.

API Server Processing Pipeline

When a YAML manifest is submitted, the API server performs:

Submission: POST request conversion.

Filtering & pre‑processing: authentication, authorization, audit.

Routing: match Group, Version, and Resource (e.g., /apis/batch/v2alpha1/cronjobs).

Creation: convert to a super‑version object, admit, validate, and store in the registry.

Persistence: serialize and write to etcd.

Controller Pattern and Reconciliation Loop

Kubernetes uses a controller pattern where controllers continuously compare spec and status. If they differ, the controller takes actions to drive the system toward the desired state.

Sensors (Reflector, Informer, Indexer) watch the API server, cache objects, and feed events to controllers.

Example: Scaling a Deployment

The Reflector watches for Deployment changes, the Informer updates the cache and enqueues the key, and the worker compares spec.replicas with the actual pod count, creates new Pods if needed, and updates status until convergence.

Summary

Declarative APIs provide built‑in state tracking, making them the primary interaction model for Kubernetes.

In production, objects are defined in YAML; spec and status are the critical sections.

The controller‑based reconciliation loop, driven by declarative specifications, enables automated, self‑healing operations.