Hands-on lesson on Pods with YAML examples, lifecycle, and management methods
Pods are the atomic execution unit in Kubernetes: they encapsulate one or more containers that share networking and ephemeral storage. In this hands-on lesson you will learn to define clear YAML manifests, understand the Pod lifecycle, and see the main management approaches in real environments, with commands and tips you can apply right away.
What is a Pod and when to use it
A Pod represents a “logical group” of one or more containers that share the same network namespace (therefore the same IP) and can share volumes. Containers in a Pod cooperate: typically a main container (app) and one or more sidecars (for logging, proxying, metrics). If you need to scale horizontally, you do not scale the Pod itself, but the controller that manages it (for example a Deployment) which creates multiple identical replicas of the Pod.
Anatomy of a YAML manifest
Manifests define the desired state. Understanding the minimal and most commonly used fields helps you create robust and observable resources.
Minimal Pod example
A first example with a web container and exposed port:
apiVersion: v1
kind: Pod
metadata:
name: nginx-pod
labels:
app: web
spec:
restartPolicy: Always
containers:
- name: nginx
image: nginx:1.25
ports:
- containerPort: 80
Probes and resources: production robustness
Probes inform Kubernetes whether the container is live, ready, or starting up. Resources define requests and limits for CPU and memory, influencing QoS and scheduling.
apiVersion: v1
kind: Pod
metadata:
name: api-pod
labels:
app: api
spec:
terminationGracePeriodSeconds: 30
containers:
- name: api
image: ghcr.io/example/api:1.0.0
resources:
requests:
cpu: "250m"
memory: "256Mi"
limits:
cpu: "500m"
memory: "512Mi"
env:
- name: LOG_LEVEL
value: info
ports:
- containerPort: 8080
readinessProbe:
httpGet:
path: /healthz/ready
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
failureThreshold: 3
livenessProbe:
httpGet:
path: /healthz/live
port: 8080
initialDelaySeconds: 10
periodSeconds: 10
failureThreshold: 3
startupProbe:
httpGet:
path: /healthz/startup
port: 8080
failureThreshold: 30
periodSeconds: 2
Initialization and sidecars
Before the main containers start, you can run preparatory tasks with initContainers. For cross-cutting features (log shipping, proxying, metrics), add sidecars that share volumes with the app.
InitContainers for dependencies
This example waits until the database DNS is resolvable before starting the worker.
apiVersion: v1
kind: Pod
metadata:
name: worker-with-init
labels:
app: worker
spec:
initContainers:
- name: wait-for-db
image: busybox:1.36
command: ["sh", "-c", "until nslookup db.default.svc.cluster.local; do echo waiting; sleep 2; done"]
containers:
- name: worker
image: ghcr.io/example/worker:2.0.0
Multi-container with shared volume (logging sidecar)
The two containers share a temporary volume: the app writes logs, the sidecar ships them.
apiVersion: v1
kind: Pod
metadata:
name: app-with-sidecar
labels:
app: app
spec:
volumes:
- name: shared-logs
emptyDir: {}
containers:
- name: app
image: ghcr.io/example/app:1.2.3
volumeMounts:
- name: shared-logs
mountPath: /var/log/app
- name: log-shipper
image: fluent/fluent-bit:2.0
args: ["-i", "tail", "-p", "path=/var/log/app/*.log", "-o", "stdout"]
volumeMounts:
- name: shared-logs
mountPath: /var/log/app
Lifecycle: phases, states, and events
The phases of a Pod are Pending, Running, Succeeded, Failed, Unknown. Each container has more granular states (Waiting, Running, Terminated) visible in kubectl describe. When you create a Pod, the scheduler assigns it to a node; the kubelet pulls the images and starts the containers in order (initContainers first).
Termination follows a precise flow: on delete, SIGTERM is sent to the processes; the terminationGracePeriodSeconds countdown starts; any preStop hooks can perform cleanup; if the processes do not terminate in time, the kubelet sends SIGKILL. For updates and rollouts, eligibility is governed by the readinessProbe: until a Pod is “ready,” it does not receive traffic through Services.
postStart and preStop hooks
Hooks allow you to run commands at container startup and before shutdown.
apiVersion: v1
kind: Pod
metadata:
name: pod-with-hooks
labels:
app: svc
spec:
terminationGracePeriodSeconds: 60
containers:
- name: svc
image: ghcr.io/example/svc:latest
lifecycle:
postStart:
exec:
command: ["/bin/sh", "-c", "echo started > /tmp/status"]
preStop:
exec:
command: ["/bin/sh", "-c", "sleep 10; curl -s -X POST http://localhost:8080/shutdown || true"]
Management modes: imperative, declarative, and controllers
Imperative with kubectl
Useful for quick experiments or debugging. Remember that Pods are ephemeral: if you want resilience, use controllers.
# Create a temporary Pod kubectl run tmp --image=alpine:3.20 --restart=Never --command -- sleep 3600 # Apply from YAML file kubectl apply -f pod.yaml # Inspect and watch scheduling kubectl get pods -o wide kubectl describe pod nginx-pod # Logs, shell, and port-forward kubectl logs -f api-pod kubectl exec -it api-pod -- sh kubectl port-forward pod/api-pod 8080:8080 # Debug with ephemeral container (does not modify the app) kubectl debug -it nginx-pod --image=busybox:1.36 --target=nginx # Delete kubectl delete pod api-pod
Declarative and GitOps
With declarative management you keep manifests versioned in Git and apply changes with kubectl apply, Kustomize, or Helm. The cluster converges toward the desired state; GitOps tools (e.g., Argo CD, Flux) automatically synchronize the repository with the environment, making changes auditable and repeatable.
Higher-level controllers
Single Pods do not replace failed instances by themselves. For high availability use:
- Deployment (manages ReplicaSet) for stateless services, rolling updates and rollbacks.
- DaemonSet to have one Pod per node (logging, agent, CNI).
- Job/CronJob for batch and scheduled workloads.
- StatefulSet for local state, stable identity, and persistent volumes.
To protect availability during planned maintenance, use PodDisruptionBudgets (PDB) on controllers, not on individual Pods:
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
name: api-pdb
spec:
minAvailable: 2
selector:
matchLabels:
app: api
Scheduling and reliability
Influencing scheduling is often essential: use requests/limits to obtain the desired QoS class (Guaranteed, Burstable, BestEffort), affinities and anti-affinities to distribute load, nodeSelector and tolerations for dedicated nodes, topology spread constraints to spread replicas across zones or nodes. Set a PriorityClass to define preemption order when resources are scarce.
Tuning, troubleshooting, and best practices
For quick diagnosis: check events with kubectl describe, logs with kubectl logs (also for specific containers), open a shell with kubectl exec, and use ephemeral containers for debugging without disturbing the app. If a Pod remains Pending, check resources, limits, available nodes, taints/tolerations. If CrashLoopBackOff, inspect the previous container’s logs with the –previous option.
Key best practices:
- Always define readinessProbe and livenessProbe for critical services.
- Set appropriate requests/limits to prevent OOMKill or throttling.
- Use securityContext (runAsNonRoot, readOnlyRootFilesystem) and do not bake secrets into the image.
- Configure ConfigMaps and Secrets as volumes or environment variables to separate configuration and code.
- Keep preStop hooks idempotent and fast; avoid excessive sleeps that prolong updates.
- Use small, versioned images; avoid latest in production.
# Quick diagnosis examples kubectl get events --sort-by=.lastTimestamp kubectl describe pod app-with-sidecar kubectl logs pod-with-hooks -c svc --previous
Conclusions and next steps
You have seen how to structure effective YAML manifests, how lifecycle phases and hooks work, and which management modes are best suited to different scenarios. The next step is to put it into practice: create a test Pod with probes and resources, add a logging sidecar, then migrate to a Deployment with multiple replicas and a PDB to maintain availability during releases.
Do you really want to master Kubernetes? Get hands-on at the terminal right away, try the examples, and build your first declarative environment: the more you practice, the more effective you become. If you need guidance or a review of your manifests, contact me and we can work together on your platform.

Comments