Lesson 2 of 8 in Kubernetes
Pods: the smallest thing Kubernetes runs
A Pod is one or more containers that always run together on the same node, share one IP address and can share volumes. It is the smallest unit you can create in Kubernetes.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Why Kubernetes exists and how it is built
The problem this solves
Kubernetes does not schedule bare containers. Some programs need a helper beside them, for example one that ships logs or refreshes a certificate. Those helpers must share a network address and files with the main program, and they must live and die together.
The Pod is that group. Most Pods hold a single container. Extra containers, called sidecars, are added only when they need to share the Pod's network and storage. Pods are disposable by design, so you rarely create them directly. You will do it here to see the basics.
How it works
- Runs code
- Control
- Data
A node hosts a Pod, the Pod starts an app container and a sidecar container, and both can use one shared volume.
- Node to Pod: 1 hosts
- Pod to App container: 2 starts
- Pod to Sidecar: 3 starts
- App container to Shared volume: 4 writes
- Sidecar to Shared volume: 5 reads
The node hosts the Pod. Inside it, containers share one network namespace, so they reach each other on localhost, and they cannot both listen on the same port. They can mount the same volume to share files.
A Pod has a phase: Pending while it is waiting to be scheduled or pulling images, Running once at least one container is up, then Succeeded or Failed when its containers finish. Pods do not move between nodes and do not heal. If a node dies, the Pod is gone, and a controller must create a new one.
Within a Pod, the kubelet restarts a container that exits, following the Pod's restartPolicy. Repeated quick crashes make it wait longer between restarts. That waiting state is what CrashLoopBackOff means.
Try it yourself
Use the kind cluster from the previous concept. All files go in the current folder, so run these in a throwaway directory.
- 1Create a Pod from a manifest
cat > hello.yaml <<'EOF' apiVersion: v1 kind: Pod metadata: name: hello labels: app: hello spec: containers: - name: web image: nginx:1.27 ports: - containerPort: 80 EOF kubectl apply -f hello.yaml kubectl get pod hello -o wideRun
kubectl get pod helloagain until STATUS isRunning. The first run pulls the image. - 2Read the events
kubectl describe pod hello
Scroll to the Events section at the bottom. It shows scheduling, the image pull and the container start in order. This is the first place to look when anything is wrong.
- 3Reach it from your laptop
kubectl port-forward pod/hello 8080:80
Leave this running. In a second terminal run
curl localhost:8080, then press Ctrl+C in the first one. - 4Read the logs
kubectl logs hello
You should see nginx's access log line for your curl request.
- 5Make a Pod crash on purpose
kubectl run crashy --image=busybox:1.36 --restart=Always -- sh -c 'echo starting; exit 1' kubectl get pod crashy kubectl logs crashy --previous
Repeat
kubectl get pod crashya few times. STATUS moves throughErrortoCrashLoopBackOffand RESTARTS climbs.--previousshows the output of the container run that just died. - 6Clean up
kubectl delete pod hello crashy rm hello.yaml
What breaks, and where to look
STATUS shows CrashLoopBackOff and RESTARTS keeps increasing.
- WHY IT HAPPENS
- The container starts and then exits, for example because of a wrong command, a missing setting or a crash in the app. Kubernetes restarts it with growing delays.
- CHECK FIRST
- Run
kubectl logs <pod-name> --previousfor the output of the last failed run, thenkubectl describe pod <pod-name>and look at Last State for the exit code and reason.
The Pod stays Pending, and the Events show: 0/1 nodes are available: 1 Insufficient cpu.
- WHY IT HAPPENS
- The Pod's resource requests are larger than any node can offer, so the scheduler cannot place it. A request is the amount the scheduler reserves for the container.
- CHECK FIRST
- Run
kubectl describe pod <pod-name>and read the Events. Compareresources.requestsin your manifest withkubectl describe nodeunder Allocatable. Lower the request or add capacity.
kubectl logs <pod-name>prints nothing, or says the container is waiting to start.- WHY IT HAPPENS
- The container has not started yet, or it started and printed nothing before it crashed. Logs only exist once a container has run.
- CHECK FIRST
- Run
kubectl get pod <pod-name>to see the status, thenkubectl describe pod <pod-name>for the reason it is waiting.
When not to use this
- Do not create bare Pods for real workloads. A bare Pod is not replaced if its node fails. Use a Deployment, which you will meet next.
- Do not put unrelated services in one Pod just to save YAML. Containers in a Pod scale and restart together, so only group things that truly belong side by side.
Check yourself
What do containers in the same Pod share?
A network namespace, so one IP and localhost, and any volumes you mount into both.
What does CrashLoopBackOff tell you?
The container keeps exiting soon after it starts, and Kubernetes is waiting longer between restarts. The cause is in the container's logs and exit code.
Which flag shows the logs of the crashed run?
kubectl logs <pod-name> --previous, because the current container may have only just restarted and have no output yet.
Keep going
Lesson 71 of 92 in the DevOps path