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

<code>kubectl create deployment nginx-deployment --image nginx -n test</code>

<code>kubectl scale deployment nginx-deployment --replicas 5 -n test</code>

Imperative object configuration Create a nginx.yaml file, then run:

<code>kubectl create -f nginx.yaml</code>

Modify the replicas field and apply:

<code>kubectl replace -f nginx.yaml</code>

Declarative object configuration

<code>kubectl apply -f nginx.yaml</code>

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.