Kubernetes pods explained: What they are and how to use them

A pod is the smallest deployable unit in Kubernetes. It is a group of one or more containers, along with shared storage and network resources, and a specification defining how those containers run. Every workload in Kubernetes ultimately runs inside a pod.

All containers in a pod share the same IP address, port space, and storage. They can communicate with each other via localhost and share volumes mounted into the pod.

Pod YAML structure

1apiVersion: v1
2kind: Pod
3metadata:
4  name: sample-pod
5  labels:
6    app: sample
7spec:
8  containers:
9  - name: sample-pod-container
10    image: nginx
11    ports:
12    - containerPort: 80

The four essential fields:

• apiVersion: v1 — the API version for pods
• kind: Pod — the type of object to create
• metadata — the pod's name and labels
• spec — the containers to run inside the pod, including image, name, and ports

Create a pod from a YAML file

1kubectl create -f sample-pod.yaml

Verify the pod is running:

1kubectl get pods

Expected output:

1NAME         READY   STATUS    RESTARTS   AGE
2sample-pod   1/1     Running   0          10s

Get additional details including the pod IP and the node it is running on:

1kubectl get pods -o wide

Expected output:

1NAME         READY   STATUS    RESTARTS   AGE   IP           NODE
2sample-pod   1/1     Running   0          30s   10.244.1.5   node1

Create a pod imperatively

For quick testing and debugging, you can create a pod without a YAML file:

1kubectl run demo --image=nginx --port=80

Now you have two pods running:

1kubectl get pods

Expected output:

1NAME         READY   STATUS    RESTARTS   AGE
2demo         1/1     Running   0          5s
3sample-pod   1/1     Running   0          2m

Pods created without a namespace specification go into the default namespace.

View pod logs

1kubectl logs -f demo

The -f flag follows the log stream in real time. Remove it to see a snapshot of current logs and return to the terminal.

Describe a pod

When something goes wrong, kubectl describe is usually the first command to run. It shows the pod's configuration, status, and the event log:

1kubectl describe pod demo

The Events section at the bottom shows what Kubernetes did: assigning a node, pulling the image, creating the container, and starting it. If any step failed, the reason appears here.

Exec into a pod

To open a shell inside a running container:

1kubectl exec -it demo -- sh

This works like docker exec. You are now inside the running container and can run commands directly. Type exit to return to your terminal.

Delete a pod

1kubectl delete pod demo

1kubectl get pods

Only sample-pod remains. The demo pod is gone and will not be recreated because it was not managed by a Deployment or other controller.

Common pod issues

Pod stuck in Pending

The pod has been accepted by Kubernetes but has not been scheduled to a node yet. Common causes are insufficient CPU or memory on available nodes, or node selector / affinity rules that no node satisfies.

1kubectl describe pod <pod-name>

Look at the Events section for a FailedScheduling message with a specific reason.

Pod in CrashLoopBackOff

The container is starting and then crashing repeatedly. Kubernetes backs off the restart attempts with increasing delays. Check the logs to find the crash reason:

1kubectl logs <pod-name>

If the container has already crashed and restarted, check the previous container's logs:

1kubectl logs <pod-name> --previous

ImagePullBackOff

Kubernetes cannot pull the container image. Common causes are a typo in the image name, a missing tag, or missing registry credentials for a private registry.

1kubectl describe pod <pod-name>

Look for a Failed to pull image message in the Events section. Verify the image name and tag are correct and that any required pull secrets are configured.