Kubernetes Pods Explained: A Beginner's Complete Guide

If you’re starting your Kubernetes journey, understanding pods is essential. Pods are the foundation of everything you’ll deploy in Kubernetes. In this beginner-friendly guide, we’ll explain what pods are and walk through all the basic operations you need to know.

What is a Kubernetes Pod?

A pod is the smallest deployable unit in Kubernetes. Think of it as a wrapper around one or more containers that need to work together. While Docker runs individual containers, Kubernetes runs pods.

Key Pod Characteristics

• Shared Network: All containers in a pod share the same IP address and port space
• Shared Storage: Containers can share volumes for data persistence
• Co-located: Containers in a pod always run on the same node
• Ephemeral: Pods are temporary by design - they can be created and destroyed frequently

When to Use Multiple Containers in a Pod

Most pods contain a single container. However, you might use multiple containers when:

• A sidecar container handles logging or monitoring
• An init container prepares the environment before the main app starts
• Containers need to share files through a volume

Prerequisites

Before following this tutorial, ensure you have:

• A running Kubernetes cluster (Minikube, kind, or a cloud provider). Need to set one up? Follow our MicroK8s local cluster guide to get started in minutes.
• kubectl installed and configured
• Basic familiarity with the command line

Creating Pods in Kubernetes

There are two main ways to create pods: imperative commands and declarative YAML files.

Method 1: Quick Pod Creation with kubectl run

The fastest way to create a pod is using kubectl run:

kubectl run my-nginx --image=nginx:latest

This creates a pod named my-nginx running the nginx web server. You can add more options:

kubectl run my-nginx --image=nginx:latest --port=80 --labels="app=web,env=dev"

Method 2: Creating Pods with YAML (Recommended)

For reproducible deployments, use YAML manifests. Create a file called pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: my-nginx
  labels:
    app: web
    environment: development
spec:
  containers:
  - name: nginx
    image: nginx:1.25
    ports:
    - containerPort: 80
    resources:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"

Apply the manifest:

kubectl apply -f pod.yaml

Understanding the Pod YAML Structure

Field	Description
apiVersion	Kubernetes API version (v1 for pods)
kind	Resource type (Pod)
metadata	Pod name, labels, and annotations
spec	Container specifications
containers	List of containers to run
resources	CPU and memory requests/limits

Reading Pod Information

Once your pods are running, you’ll need to inspect them frequently.

List All Pods

# Pods in current namespace
kubectl get pods

# Pods in all namespaces
kubectl get pods -A

# Pods with more details
kubectl get pods -o wide

Get Detailed Pod Information

The describe command shows comprehensive pod details:

kubectl describe pod my-nginx

This displays:

• Pod status and conditions
• Container states
• Events (useful for debugging)
• Resource allocation
• Volumes and mounts

View Pod Logs

Access container logs with:

# Current logs
kubectl logs my-nginx

# Follow logs in real-time
kubectl logs -f my-nginx

# Logs from specific container (multi-container pods)
kubectl logs my-nginx -c nginx

Execute Commands Inside a Pod

Open an interactive shell:

kubectl exec -it my-nginx -- /bin/bash

Or run a single command:

kubectl exec my-nginx -- cat /etc/nginx/nginx.conf

Updating Pods

Pods themselves are immutable - you cannot change most fields after creation. However, there are strategies for updates.

Edit Pod Labels and Annotations

You can modify metadata:

kubectl label pod my-nginx tier=frontend
kubectl annotate pod my-nginx description="Web server pod"

Replace a Pod

To change container images or specs, delete and recreate:

kubectl delete pod my-nginx
kubectl apply -f pod.yaml

Using Deployments for Updates (Recommended)

For production workloads, use Deployments instead of bare pods. Deployments manage pod updates automatically:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25

With Deployments, you can update the image and Kubernetes handles the rollout:

kubectl set image deployment/nginx-deployment nginx=nginx:1.26

Deleting Pods

Remove pods when they’re no longer needed.

Delete a Single Pod

kubectl delete pod my-nginx

Delete Multiple Pods

# Delete by label
kubectl delete pods -l app=web

# Delete all pods in namespace
kubectl delete pods --all

Force Delete a Stuck Pod

If a pod won’t terminate:

kubectl delete pod my-nginx --force --grace-period=0

Warning: Force deletion should be used sparingly as it may cause data inconsistency.

Pod Lifecycle and States

Understanding pod states helps with debugging:

State	Description
Pending	Pod accepted but containers not yet created
Running	At least one container is running
Succeeded	All containers completed successfully
Failed	All containers terminated, at least one failed
Unknown	Pod state cannot be determined

Common Pod Issues

• ImagePullBackOff: Cannot pull container image
• CrashLoopBackOff: Container keeps crashing
• Pending (no resources): Cluster lacks CPU/memory

Practical Example: Deploying a Web Application

Let’s deploy a complete web application pod:

apiVersion: v1
kind: Pod
metadata:
  name: web-app
  labels:
    app: myapp
    tier: frontend
spec:
  containers:
  - name: web
    image: nginx:1.25-alpine
    ports:
    - containerPort: 80
    volumeMounts:
    - name: html
      mountPath: /usr/share/nginx/html
    readinessProbe:
      httpGet:
        path: /
        port: 80
      initialDelaySeconds: 5
      periodSeconds: 10
    livenessProbe:
      httpGet:
        path: /
        port: 80
      initialDelaySeconds: 15
      periodSeconds: 20
  volumes:
  - name: html
    emptyDir: {}

This pod includes:

• Health probes for reliability
• Volume mounts for data
• Resource-efficient Alpine image

Kubectl Cheat Sheet for Pods

Command	Description
kubectl run <name> --image=<image>	Create a pod
kubectl get pods	List pods
kubectl describe pod <name>	Show pod details
kubectl logs <name>	View pod logs
kubectl exec -it <name> -- /bin/sh	Shell into pod
kubectl delete pod <name>	Delete a pod
kubectl apply -f <file>	Create/update from YAML
kubectl get pods -w	Watch pod status changes

Next Steps

Now that you understand pods, you’re ready to explore more Kubernetes concepts:

1. Deployments - Manage pod replicas and updates
2. Services - Expose pods to network traffic
3. ConfigMaps & Secrets - Externalize configuration
4. Network Policies - Control pod-to-pod communication (see our Kubernetes Network Policies guide for securing your pods)

Conclusion

Pods are the fundamental building blocks of Kubernetes applications. Mastering pod creation, inspection, and management is essential for any Kubernetes practitioner. Remember that pods are ephemeral - for production workloads, always use higher-level controllers like Deployments.

At Fraway, we provide Kubernetes training and consulting services to help teams adopt container orchestration effectively. Our CKA and CKAD certified engineers can guide you from basic pod management to advanced cluster operations. Contact us to accelerate your Kubernetes journey.