BLOG20a: What is Kubernetes API

BLOG10: What is Kubernetes API Objects?

Kubernetes API – Deep Dive Training Syllabus

---

** Module 1 — Kubernetes API Fundamentals**

1. What is the Kubernetes API?

• Kubernetes is “API-first”: control plane is entirely RESTful

• API server architecture

• Declarative vs imperative API

• Difference between Kubernetes API and kubectl CLI

2. API Objects & Data Model

• Resources (Pods, Deployments, Services, etc.)

• Objects vs controllers

• Object metadata: name, namespace, labels, annotations, uid, resourceVersion

• Spec vs Status fields

3. API Server Components

• Aggregated API server

• kube-apiserver flags

• Admission chain (mutating, validating)

• Conversion webhooks

---

** Module 2 — API Groups & Versioning**

4. API Groups

• Core group (legacy)

• Named groups (apps/, rbac.authorization.k8s.io/, batch/, etc.)

• Why groups exist

5. API Versioning

• v1, v1alpha1, v1beta1

• Deprecation policy

• Stability guarantees

• How client-go handles API versions

6. Discovery API

• /apis and /api endpoints

• How kubectl queries the discovery API

• Using curl to list resources via the discovery endpoint

---

** Module 3 — HTTP Mechanics of Kubernetes API**

7. REST Endpoints

• Resource endpoints

• /api/v1/namespaces/{namespace}/pods

• /apis/apps/v1/deployments

• Verbs (HTTP methods → Kubernetes verbs)

8. HTTP Verbs and Their Meaning

• GET → list, read

• POST → create

• PATCH (strategic, JSON merge, JSON patch)

• PUT → replace

• DELETE → delete/gracePeriod

9. CRUD Example Using curl

• Create Pod/Deployment

• Patch image

• Delete resource

• Watch API (streaming responses)

---

** Module 4 — API Authentication & Authorization**

10. Authentication

• Tokens (Bearer, ServiceAccount)

• OIDC authentication

• Certificates (x509 client auth)

11. Authorization (RBAC Deep Dive)

• API verbs

• ClusterRoles vs Roles

• Impersonation

12. Admission Control

• Mutating admission

• Validating admission

• webhooks

---

** Module 5 — OpenAPI & Documentation**

13. Kubernetes OpenAPI Schema

• Schema definitions

• Discovering API using OpenAPI

• Generating clients from OpenAPI

14. kubectl explain (Documentation)

• How kubectl uses OpenAPI behind the scenes

• Using kubectl explain --recursive

• Mapping doc to API resources

---

** Module 6 — API Machinery Internals**

15. API Server Storage

• etcd storage structure

• Storage version vs served version

• Why storage version is important

16. Conversion & Defaulting

• Internal API version

• Defaulting logic in API server

• Conversion webhooks for CRDs

17. Garbage Collection

• OwnerReferences

• Finalizers

• Controller patterns

---

** Module 7 — Custom Resource Definitions (CRDs)**

18. Understanding CRDs

• CRD YAML anatomy

• Specifying schema (structural schemas)

• AdditionalPrinterColumns

• Categories

19. Custom Controllers & Operators

• Controller-runtime

• Writing reconcilers

• Event handling

20. Versioned CRDs

• v1alpha1, v1beta1, v1 for CRDs

• Storage version

• Conversion webhooks for backward compatibility

---

** Module 8 — Advanced API Topics**

21. API Aggregation Layer

• When to use aggregated APIs

• kube-aggregator

• Installing APIService documents

22. Server-Side Apply

• Field ownership

• managedFields

• Conflict detection

23. Dynamic Admission / Dynamic Resources

• Dynamic clients

• Unstructured objects

• Dynamic informers

---

** Module 9 — API Performance & Security**

24. API Server Performance

• API QPS limits

• Caching layers

• Informers vs direct API calls

25. API Security Best Practices

• Avoid wildcards in RBAC

• Using short-lived tokens

• Securing service accounts

• Webhook security

---

✔️ Summary: Topics You Requested (Included Above)

Requested Topic	Module
API groups	Module 2
Versioning	Module 2
CLI documentation (kubectl explain)	Module 5
CRDs	Module 7
API-first design	Covered across Modules 1–9

---

Objects vs Controllers (The Core of Kubernetes Architecture)

Kubernetes Objects = Desired State (WHAT you want)

Kubernetes objects are declarative definitions stored in the API server. They describe what the system should look like.

Examples of objects:

• Pod

• Deployment

• Service

• ConfigMap

• Secret

• PersistentVolumeClaim

• CronJob

• Ingress

Each object is stored in etcd, and the API server exposes them via REST.

Think of objects as:

"I want this state."

---

Kubernetes Controllers = Make Desired State Reality (HOW to achieve it)

Controllers are background loops that continuously watch objects and reconcile the actual state to match the desired state.

Controllers run inside:

• kube-controller-manager

• cloud-controller-manager

• custom operators

• CRD controllers

Think of controllers as:

“I will make sure the cluster behaves like the object definition.”

They use a famous pattern called:

Reconciliation Loop (Control Loop)

1. Watch objects

2. Compare desired state vs actual state

3. Take action to fix the difference

---

💡 Best Real-world Example: Deployment vs ReplicaSet vs Pods

** Deployment (Object)**

This YAML:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: nginx

This is ONLY a desired state declaration:

"I want 3 Pods running template X."

The Deployment itself does nothing.

---

** Deployment Controller (Controller)**

The Deployment controller sees the Deployment object and takes actions:

What it does:

• Creates a ReplicaSet

• Ensures ReplicaSet matches Deployment template

• Handles rolling updates

• Manages rollout history

• Scales Pods

• Ensures correct number of Pods always exist

What it does NOT do:

• It does NOT create Pods directly

• It does NOT run containers

• It does NOT check node health

Those are handled by other controllers.

---

** ReplicaSet (Object)**

ReplicaSet stores the desired state:

"I must maintain N running Pods of this template."

ReplicaSet is also just an object — it stores desired state like:

replicas: 3

---

** ReplicaSet Controller (Controller)**

This controller actually manages Pods.

What it does:

• Creates Pods if less than required

• Deletes Pods if more than required

• Watches Pod health

• Ensures labeling matches selector

It is the one that ensures the Pod count matches your declared number.

---

** Pod (Object)**

A Pod is just a declaration:

“Run a container with this image + resources + volumes.”

Pod does not run anything by itself.

---

** Kubelet (Controller on each node)**

The kubelet reads PodSpec assigned to that node and:

• Pulls container image

• Runs container via container runtime

• Restarts containers if they die

• Reports Pod status

• Mounts volumes

• Executes liveness/readiness probes

It is a node-level controller.

---

Summary of the Example

Component	Type	Responsibility
Deployment	Object	Desired number of Pods + update strategy
Deployment Controller	Controller	Manages RS & rollouts
ReplicaSet	Object	Stores target replica count
ReplicaSet Controller	Controller	Ensures exact number of Pods
Pod	Object	Defines exact container spec
Kubelet	Controller	Runs containers on node

---

Real Case Scenario: Production Service Crash at Night

What happens if a Pod crashes?

1. Pod disappears

ReplicaSet controller detects missing Pod:

Desired: 3
Actual: 2

2. ReplicaSet Controller creates a new Pod

It generates a new Pod matching template.

3. Kubelet runs container

Kubelet starts the new Pod on some node.

4. Deployment becomes healthy again

Deployment controller sees ReplicaSet is stable.

Important:

No human interaction needed. No scripts. No cron jobs.

Controllers recovered the service automatically.

---

Real Case 2: Auto-healing during Node Failure

Node shuts down unexpectedly.

What happens?

• Kubelet on that node becomes unreachable

• node controller marks node as NotReady

• pod eviction controller evicts Pods from that node

• ReplicaSet controller creates replacement Pods

• scheduler places them on healthy nodes

• kubelet runs them

Again, objects declare desired state Controllers fix reality to match desired state.

---

Real Case 3: Custom Resource + Operator (Controller)**

You declare:

apiVersion: cache.example.com/v1
kind: RedisCluster
spec:
  nodes: 5

This object does nothing by itself.

A custom controller (operator) watches this CRD and:

• creates StatefulSets

• configures Redis master–replica

• configures failover

• configures backups

• enforces 5 nodes always running

This is how operators work (MongoDB operator, Kafka operator, Vault operator).

---

Key Takeaway

Objects = The State

“Make the world look like this.”

Controllers = The Logic

“I will take continuous action until the world matches your declaration.”

---

Great question — this is the key to understanding how Kubernetes works internally.

Where is the Deployment Controller?

The Deployment Controller is a built-in controller that runs inside the Kubernetes kube-controller-manager.

---

Location of the Deployment Controller

✔️ It is not in the API server

The API server only stores objects.

✔️ It is not in the Deployment object

The Deployment object carries only the desired state.

✔️ It is inside the kube-controller-manager binary

Specifically in the controller named:

deployment-controller

📌 kube-controller-manager runs as a Pod in most clusters:

• kubeadm

• K3s

• AKS / EKS / GKE

• Rancher

• RKE2

• OpenShift (different)

Check it in kubeadm clusters:

kubectl -n kube-system get pods | grep controller-manager

Example:

kube-controller-manager-ip-172-31-1-20   Running   1/1

Inside that pod are multiple controllers.

---

What lives inside kube-controller-manager?

The controller-manager contains many controllers, not just Deployment:

Controller	Purpose
deployment-controller	Handles Deployments → manages ReplicaSets
replicaset-controller	Ensures Pod replicas
statefulset-controller	Manages StatefulSets
job-controller	Manages Jobs
cronjob-controller	Manages CronJobs
node-controller	Handles node health
service-controller	Syncs load balancers
namespace-controller	Cleans up namespaces
pv-controller	Manages PersistentVolumes
endpoint-controller	Builds Endpoints

And many more.

---

Where is it in Kubernetes source code?

If you browse the Kubernetes source:

kubernetes/pkg/controller/deployment/

On GitHub:

https://github.com/kubernetes/kubernetes/tree/master/pkg/controller/deployment

Inside you will find:

• deployment_controller.go

• rollout.go

• sync.go

• progress.go

These files implement:

• Rolling updates

• Rollbacks

• ReplicaSet management

• Scale behaviors

• Status updates

---

How It Actually Works

1. Deployment object is stored in etcd via API server

2. Deployment controller watches /apis/apps/v1/deployments

3. It detects new or changed Deployment

4. It creates or updates a ReplicaSet

5. ReplicaSet controller notices ReplicaSet changes

6. ReplicaSet controller creates or deletes Pods

7. Scheduler assigns Pods to nodes

8. Kubelet runs containers

Everything is loosely coupled via the API server. Controllers do not talk directly to each other — only through API objects.

---

Where does Deployment Controller run in managed Kubernetes?

On EKS

Runs inside control plane (you cannot see Pod) ✔️ But still a kube-controller-manager process

On GKE

Runs as part of Google’s internal master image

On AKS

Runs in Azure-managed controller-manager VM

On K3s

It is inside:

/usr/local/bin/k3s server

Because K3s compiles all controllers into a single binary.

On kubeadm

Visible as a Pod:

kube-controller-manager-master

---

Fast Recap

Item	Where it exists
Deployment controller logic	Inside kube-controller-manager
Deployment object	Stored in etcd via API server
Runs as	Process or Pod depending on Kubernetes distribution
Communicates via	Shared API use, not direct calls

---