kubectl and the API

Everything in Kubernetes is an object in a REST API, and every action — by you, by a controller, by the kubelet — is a request to one API server. kubectl is just a convenient client for that API. Internalizing this collapses a lot of apparent complexity: there is one interface, and everything else is a way of talking to it.

Once you see the cluster as an API of objects, the daily workflow becomes legible: you read objects, you declare the ones you want, and the system reconciles. The command-line ergonomics matter far less than the model underneath them.

The Object Model

Every Kubernetes object shares a shape. apiVersion and kind identify the type (for example apps/v1 and Deployment). metadata carries the name, namespace, labels, and annotations. spec is the desired state you set. status is the actual state the system reports — you read it, you do not write it. The gap between spec and status is exactly what the reconcile loop works to close.

apiVersion: apps/v1      # the type's group and version
kind: Deployment         # what kind of object this is
metadata:
  name: web              # who it is
  namespace: default
spec:                    # desired state — you write this
  replicas: 3
status:                  # actual state — the system writes this
  readyReplicas: 3

Objects are grouped into API groups and versions. Core objects like Pods live in the original group (v1); others live in named groups like apps, batch, or networking.k8s.io, each versioned independently (v1, v1beta1). The version tells you how stable the contract is, and it is why upgrades sometimes require migrating a manifest from a removed beta version.

Talking to the API

A handful of kubectl verbs cover most work. get lists objects and describe shows a detailed, human-readable view including recent events. apply submits desired state from a file. logs and exec reach into running containers. explain prints the schema of any field. Each is just an HTTP call: get is a GET, apply is a PATCH, and so on.

Which cluster and identity a command uses comes from your kubeconfig — a file of clusters, users, and contexts that pair them. kubectl config current-context tells you where a command will land. This is not a detail: the most expensive kubectl mistakes are commands run against the wrong context.

Imperative vs Declarative

You can change the cluster two ways. Imperative commands act now: kubectl create, scale, edit, delete. They are fine for exploration and emergencies. The declarative way is kubectl apply against manifests you keep in version control. apply performs a three-way merge — comparing your file, the live object, and the last-applied configuration — so it changes only what you changed and leaves fields managed by controllers alone.

For anything that outlives a debugging session, declarative wins. Manifests in Git are reviewable, reproducible, and the foundation of GitOps (covered later), where a controller continuously applies the repository to the cluster. Imperative edits, by contrast, leave no record and quietly drift from what anyone believes is deployed.

Discovering the API

The API is self-describing, which means you rarely need to leave the terminal to learn it. kubectl api-resources lists every kind the cluster knows, including ones added by extensions. kubectl api-versions lists the available group/versions. kubectl explain pod.spec.containers walks the schema field by field. On an unfamiliar cluster these three commands tell you what exists and how it is shaped faster than any documentation.

Extending the Surface

The set of kinds is not fixed. A Custom Resource Definition teaches the API server a new kind, which then behaves like any built-in object — you get, describe, and apply it the same way, and a custom controller reconciles it. This is the foundation of operators and the main way Kubernetes becomes a platform, covered in the extending-Kubernetes chapter. The point for now: the API you have been learning is the same surface that every tool, controller, and extension builds on.