Inside Kubernetes: How a `kubectl run nginx --image=nginx --replicas=3` Command Traverses the System

Overview

The command kubectl run nginx --image=nginx --replicas=3 triggers a chain of actions across many Kubernetes components. The article explains each step in detail, showing how the request is validated, transformed, stored, and eventually turned into running containers.

Client Side

The kubectl binary parses the command line, validates arguments, and builds a Pod object using a generator (e.g., BasicPod).

It then discovers the appropriate API group and version, performs client‑side authentication (using kubeconfig), and sends an HTTP POST request to the API server.

API Server Processing

Authentication : The request passes through x509, bearer‑token, and basic‑auth handlers.

Authorization : The server evaluates RBAC, ABAC, webhook, and node authorizers.

Admission Control : Admission plugins (e.g., ValidatingAdmissionWebhook) may modify or reject the object.

If the request is accepted, the API server stores the Pod and related objects (Deployment, ReplicaSet) in etcd.

Controller Manager

The Deployment controller creates a ReplicaSet, which in turn creates three Pod objects.

The ReplicaSet controller ensures the desired number of pods exist, creating them via the API server.

All controllers use informers to watch resources and reconcile the current state with the desired state.

Scheduler

The scheduler watches unscheduled pods, runs a filter chain (e.g., node name, taints, node affinity) to find feasible nodes.

It then scores the nodes with plugins (e.g., NodeAffinity, PodTopologySpread) and selects the best node.

A Binding object is created, updating spec.nodeName of the pod.

Kubelet on the Target Node

Kubelet receives the pod, creates a sandbox (pause) container via the Container Runtime Interface (CRI).

The sandbox holds shared Linux namespaces (network, IPC, PID).

Network plugins (CNI) are invoked (e.g., bridge, host‑local IPAM) to allocate an IP and configure resolv.conf.

Init containers are started first, followed by the main containers. Images are pulled if needed, and containers are launched through CRI calls ( CreateContainer, StartContainer).

CRI and CNI Details

CRI abstracts the underlying runtime (Docker, containerd, etc.). The RunPodSandbox RPC creates the pause container.

CNI plugins are executable binaries that receive JSON configuration via stdin. The bridge plugin creates a Linux bridge, a veth pair, assigns an IP from the host‑local IPAM, and sets up routing.

The optional noop plugin can be used for nodes that only run host‑network pods.

Pod Lifecycle and Status

Kubelet continuously syncs pod status, updating phases ( Pending, Running, Succeeded, Failed) and conditions (e.g., PodReady). It also handles post‑start hooks, volume mounting, and garbage collection.

Result

After all components finish their work, three nginx pods are running on one or more nodes, each with its own IP, network connectivity, and the pause container providing shared namespaces.