Static pods are managed directly by the kubelet daemon on a specific node, without being observed by the API server. Unlike pods managed by the control plane (for example, a deployment); instead, the kubelet observes each static Pod (and restarts it if it fails).
Static pods are always linked to a Kubelet on a specific node.
The kubelet attempts to automatically create a mirror pod in the Kubernetes API server for each static pod. This means that Pods running on a node are visible on the API server, but cannot be controlled from there. Pod names will be suffixed with the node’s hostname with an initial hyphen.
Before you begin
You must have a Kubernetes cluster and the kubectl command-line tool must be configured to communicate with your cluster. We recommend that you run this tutorial on a cluster with at least two nodes that are not acting as control plane hosts. If you don’t already have a cluster, you can create one using minikube, or you can use one of these
Kubernetes playgrounds:
- Killercoda
- Playing with Kubernetes
To check the version, enter kubectl version.
This page assumes that you are using CRI-O to run Pods, and that your nodes are running the Fedora operating system. Instructions for other Kubernetes distributions or installations may vary.
Create a static pod You can configure a
static
pod with a configuration file hosted on the file system or a configuration file hosted on the web.
Static pod manifest hosted
on the file system
Manifests are standard pod definitions in JSON or YAML format in a specific directory. Use the staticPodPath: <the directory> field in the kubelet configuration file, which periodically scans the directory and creates/deletes static Pods as YAML/JSON files appear/disappear there. Note that the kubelet will ignore files that begin with dots when scanning the specified directory.
For example, here’s how to start a simple web server like
a static pod:
-
Choose a node where you want to run the static pod. In this example, it is my-node1.
-
static-web.yaml:
-
Configure your kubelet on the node to use this directory by running it with the argument -pod-manifest-path=/etc/kubernetes/manifests/. In Fedora edit
/etc/kubernetes/kubelet to include this line:KUBELET_ARGS=”-cluster-dns=10.254.0.10 -cluster-domain=kube.local -pod-manifest-path=/etc/kubernetes/manifests/”
or add the staticPodPath: field <the directory> in the kubelet configuration file.
-
Restart the kubelet. In Fedora, you would run:
Choose a directory, say /etc/kubernetes/manifests and place a web server pod definition there, for example /etc/kubernetes/manifests/
Web-hosted static pod
manifest
Kubelet periodically downloads a file specified by the -manifest-url=<URL> argument and interprets it as a JSON/YAML file containing Pod definitions. Similar to how manifests hosted on the file system work, the kubelet retrieves the manifest on a schedule. If there are changes in the list of static Pods, the kubelet applies them.
To use this approach:
Create a
-
YAML file and store it on a web server so that you can pass the URL of that file
-
Configure the kubelet on the selected node to use this web manifest by running it with -manifest-url=<manifest-url>. In Fedora, edit /etc/kubernetes/kubelet to include this line:
KUBELET_ARGS=”-cluster-dns=10.254.0.10 -cluster-domain=kube.local -manifest-url=<manifest-url>”
-
Restart the kubelet. In Fedora, you would run:
to the kubelet.
Observe the behavior of the static pod
When the kubelet starts, it automatically starts all defined static pods. Since you have defined a static Pod and restarted the kubelet, the new static Pod should already be running.
You can see running
containers (including static pods) running (on the node)
:The
output could be something like
:
You can see the mirror pod on the server API:
NAME READY STATUS RESTARTS AGE static-web 1/1 Running 0 2m
The static pod tags propagate to the pod mirror. You can use those tags as usual through selectors, etc.
If you try to use kubectl to remove the mirror Pod from the API server
, the kubelet does not delete the deleted static Pod:pod “static-web”
You can see that the Pod is still running:
NAME READY STATE REBOOT AGE static-web 1/1 Running 0 4s
Back at your node where the kubelet is running, you can try to stop the container manually. You’ll see that, after a while, the kubelet will notice and restart the Pod automatically
:
Once you identify the correct container, you can get the logs for that container
with
crictl:For more information on how to debug using crictl, visit Debugging Kubernetes nodes with crictl
Adding and removing static
pods The running kubelet periodically scans the configured directory (/etc/kubernetes/manifests in our example) for changes and adds/removes Pods as files appear/disappear in this directory.
What’s next
Generate static
- pod manifests for control plane components Generate
- Pod manifest for local
- Debugging Kubernetes nodes with
- Map docker CLI commands to crictl.
- Configure etcd instances as static pods managed by a kubelet
static
etcd
crictl Learn more about crictl.
