Lesson 2 of 8 in Kubernetes

Pods: the smallest thing Kubernetes runs

Core12 min

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

What lives inside a Pod
What lives inside a PodA node hosts a Pod, the Pod starts an app container and a sidecar container, and both can use one shared volume.1 hosts2 starts3 starts4 writes5 readsNodea machine in the clusterPodone IP, shared networkApp containernginxSidecaroptional helperShared volumeemptyDir
  • 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.

  1. Node to Pod: 1 hosts
  2. Pod to App container: 2 starts
  3. Pod to Sidecar: 3 starts
  4. App container to Shared volume: 4 writes
  5. 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.

  1. 1
    Create 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 wide

    Run kubectl get pod hello again until STATUS is Running. The first run pulls the image.

  2. 2
    Read 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.

  3. 3
    Reach 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.

  4. 4
    Read the logs
    kubectl logs hello

    You should see nginx's access log line for your curl request.

  5. 5
    Make 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 crashy a few times. STATUS moves through Error to CrashLoopBackOff and RESTARTS climbs. --previous shows the output of the container run that just died.

  6. 6
    Clean 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> --previous for the output of the last failed run, then kubectl 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. Compare resources.requests in your manifest with kubectl describe node under 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, then kubectl 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.

Lesson 71 of 92 in the DevOps path

Search

Search cheat sheets and projects