When you think of Kubernetes, you’re likely picturing Deployments, ReplicaSets, or maybe even DaemonSets orchestrated by the almighty kube-apiserver. But behind the scenes, there’s a lesser-known but powerful construct that operates outside the usual control plane drama: Static Pods.
Static Pods are like the backstage crew of a theatre production—crucial, quiet, and directly managed by the node itself rather than the Kubernetes control plane. In this post, we’ll dive deep into what static pods are, how they work, and why you might want to use them.
What Are Static Pods?
Static Pods are pods that are managed directly by the kubelet on a node, rather than through the Kubernetes API server. They are defined in a manifest file placed on the node’s filesystem.
- No
kubectl apply
- No Deployments, ReplicaSets, or Controllers
- Just pure, raw pod definitions
As soon as the kubelet detects a YAML file in its configured --pod-manifest-path
, it creates and runs the pod. If the pod crashes or the node reboots, kubelet ensures it comes back—no fancy scheduler required.
Real-Life Analogy
Imagine you have a personal chef (kubelet) who always checks a handwritten recipe (manifest file) taped to your fridge door (node file system). Every time they show up, they read the recipe and cook accordingly. If the recipe changes, they update the dish—no instructions from your dietician (control plane) needed.
How Static Pods Work
Step-by-Step
- Kubelet starts and checks the
--pod-manifest-path
directory (like/etc/kubernetes/manifests
). - It reads all
.yaml
or.json
pod definitions in that folder. - For each manifest, kubelet creates and runs the pod locally.
- If the control plane is running, these pods are reflected in the API server as mirror pods (read-only representations).
Example: Creating a Static Pod
Let’s say we want a static pod running NGINX on our node.
1. Define the manifest file
Create /etc/kubernetes/manifests/nginx-static.yaml
:
apiVersion: v1
kind: Pod
metadata:
name: nginx-static
labels:
role: webserver
spec:
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
2. Kubelet picks it up automatically
You don’t have to restart anything. As long as kubelet is running and the manifest is valid, it will launch the pod.
3. Verify
kubectl get pods -A
You’ll see nginx-static
running on that specific node. If the control plane is active, this pod will appear as a mirror pod.
Use Cases: When Static Pods Shine
Use Case | Why Static Pods? |
---|---|
Bootstrapping Kubernetes components | Kube-apiserver, kube-scheduler, etc., are often run as static pods during cluster bootstrap (especially in kubeadm-based setups). |
Running critical node-level agents | If you need a daemon but don’t yet have the cluster control plane up, static pods are perfect. |
Air-gapped or isolated setups | Static pods don’t require any control plane to run—ideal for disconnected or edge devices. |
Disaster recovery scenarios | When the control plane is down, static pods can still run essential workloads. |
Testing and development | Great for experimenting with pod definitions without the complexity of Deployments or ReplicaSets. |
Did You Know?
- Static Pods do not have a controller (like Deployment or DaemonSet) managing them.
- If you delete a static pod via
kubectl
, kubelet will immediately recreate it because the manifest file still exists on disk. - Mirror pods cannot be edited from
kubectl
—you must edit the source manifest file directly.
Limitations of Static Pods
While powerful, static pods come with caveats:
- No autoscaling — you’re on your own
- No rolling updates or restarts
- No centralized control — each node needs to be configured manually
- Can be hard to monitor/debug across many nodes
Use them where they make sense—like at the node level or during control plane bootstrap, not as replacements for managed workloads.
Static Pods in the Wild (Kubeadm Example)
If you’ve used kubeadm
, you’ve already worked with static pods!
Check out:
ls /etc/kubernetes/manifests/
You’ll likely see:
kube-apiserver.yaml
kube-controller-manager.yaml
kube-scheduler.yaml
etcd.yaml
These are all static pods created and managed directly by kubelet.
Pro Tips
- Use
kubectl describe pod <name>
to check why a static pod might be failing. - Keep manifest files under version control.
- Be cautious of syntax errors—kubelet will fail silently or log errors.
- You can simulate updates by replacing the manifest file (no need for
kubectl apply
).
Conclusion
Static Pods may not have the glamour of Deployments or the versatility of StatefulSets, but when the control plane isn’t available or you’re bootstrapping your cluster, they are your MVPs. They are simple, effective, and node-resilient.
So next time you’re knee-deep in YAML, don’t forget about these humble building blocks of Kubernetes—they might just save your cluster one pod at a time.