Kubernetes API¶

The Kubernetes API is the control surface of the cluster.

Whether changes come from kubectl, CI/CD, operators, or controllers, they flow through the API server.

API Server and etcd¶

A core design rule is that etcd is accessed through the API server, not directly by normal components.

• etcd stores cluster state.
• API server validates and persists state transitions.
• Controllers and kubelets watch API resources and react.

graph TD
    User[User or CI] -->|kubectl / API client| API[API Server]
    Controllers[Controllers] <-->|watch / patch| API
    Kubelet[Kubelet] <-->|status / pod updates| API
    API <-->|read and write| Etcd[(etcd)]

Object Anatomy: spec and status¶

Most Kubernetes resources separate intent from observation.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
status:
  replicas: 2

• spec: desired state declared by users or automation.
• status: current state reported by controllers.
• reconciliation: controllers close the gap.

Request Pipeline¶

A create or update request passes through these stages:

1. Authentication: who is calling.
2. Authorization: what they are allowed to do.
3. Admission: mutation and validation policy.
4. Persistence: accepted object is stored.

API Groups and Versions¶

Kubernetes APIs are grouped and versioned for compatibility.

• Alpha (v1alpha1): experimental and can change or be removed.
• Beta (v1beta1): maturing, but still not guaranteed long-term stable.
• Stable (v1): production-ready API contract.

Version behavior is governed by the Kubernetes deprecation policy. Do not assume beta APIs are always enabled in every environment.

Common paths:

Useful discovery commands:

kubectl api-resources
kubectl api-versions
kubectl explain deployment.spec

Declarative vs Imperative¶

Imperative commands are useful for quick actions:

kubectl scale deployment web --replicas=5

Declarative workflows are preferred for production:

kubectl apply -f deployment.yaml

Declarative config is repeatable, reviewable, and CI-friendly.

Troubleshooting API Interactions¶

To inspect client-level API calls:

kubectl get pods -v=6

For server-side behavior, use audit logs and events:

kubectl get events -A --sort-by=.metadata.creationTimestamp

Summary¶

• The API server is the authoritative control interface.
• Kubernetes objects model desired and observed state.
• Controllers continuously reconcile state.
• API version choice and deprecation awareness are operationally important.
• Declarative API usage should be the default for production systems.