Hands-on lesson on Pods with YAML examples, lifecycle, and management methods

ARTIFICIAL INTELLIGENCE

Article

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.

Se vuoi farmi qualche richiesta o contattarmi per un aiuto riempi il seguente form

    Comments