Kubernetes explained
through the F1 lens.

Stage 01 motivation + setup

Why Kubernetes exists

The problem

The concept

The piece common to both solutions is the container.

A virtual machine (VM) carries virtualized hardware and a complete operating system: it takes up gigabytes and takes minutes to start. A container shares the kernel of the host operating system and carries only the files, binaries and libraries the app needs: it takes up megabytes and starts in seconds. A container image packages that whole environment and can be run identically anywhere, which solves the "it works on my machine" problem.

Containers solve the environment problem and create another one. With dozens or hundreds of them, someone has to create them, destroy them, watch the health of each one and recreate whatever fails. Doing that manually does not scale. Kubernetes (K8s) is the orchestrator that takes over these tasks.

The central idea of Kubernetes is the desired state. You do not run a sequence of orders ("start this container, then that one"). You declare the result you want ("I want 3 copies of this application running") and Kubernetes continuously compares what exists with what was declared, correcting any difference. If one of the copies disappears at 3 a.m. (the Pod is deleted or the node it was running on goes down), the cluster notices that there are 2 copies instead of 3 and creates the missing one, without anyone waking up. When what fails is only the process inside the container, another mechanism reacts, one you will clearly tell apart in Stage 07.

Key concepts

Setting up the lab

# 1. Install Docker Desktop (docker.com). On Linux, use Docker
#    Engine (docs.docker.com/engine/install). Confirm:
$ docker -v
Docker version 27.x
 
# 2. Install kubectl (kubernetes.io/docs/tasks/tools) and confirm.
#    Use --client: there is no cluster yet, so only the client
#    version can be queried (without --client, kubectl would try to talk
#    to a nonexistent server and print a connection error)
$ kubectl version --client
Client Version: v1.30.x
Kustomize Version: v5.x
 
# 3. Install Minikube (minikube.sigs.k8s.io/docs/start) and start the cluster:
$ minikube start
😄  minikube v1.33 on Windows 11
✨  Using the docker driver
🏄  Done! kubectl is now configured to use "minikube"
 
# 4. Confirm the cluster is up:
$ kubectl get nodes
NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   1m    v1.30.x
 
# 5. Empty cluster = success:
$ kubectl get pods
No resources found in default namespace.
 
# 6. Now that the cluster exists, the full version shows client and server:
$ kubectl version --output=yaml
clientVersion:
  (...)
serverVersion:
  (...)

Essential commands for this stage

Hands-on

The smallest possible exercise: prove that the lab is alive.

1. Run minikube start and wait for the "Done!".
2. Run kubectl get nodes. Observe the minikube node with STATUS Ready. If NotReady appears, wait 1 minute and repeat.
3. Run kubectl get pods. Observe No resources found in default namespace. An empty, ready cluster is the starting point of the next stage.
4. Bonus: run minikube stop and then kubectl get nodes. Observe the connection error message (the cluster does not respond). Start it again with minikube start. Now you know what "cluster down" looks like in the terminal.

Stage 02 command line + API

kubectl and the API, how you command the cluster

The problem

The concept

Everything in Kubernetes goes through the REST API of the master node (the *control plane*). kubectl is the client of that API: each command you type becomes an HTTP request (GET, POST, PUT or DELETE) against the cluster.

The path of a command is this:

1. You type kubectl get pods.
2. kubectl reads the kubeconfig file, which holds the API Server address, the credentials and the current cluster context. Minikube fills in this file by itself on minikube start.
3. kubectl sends a GET to the API Server (for the default namespace, the path is /api/v1/namespaces/default/pods).
4. The response comes back and kubectl formats it in the terminal.

The API is divided into groups. The "core" group holds the fundamental resources (pods, services, replicasets); other groups handle security, storage and autoscaling. Since it is plain REST, any language (Python, Go, Java, C#) can call it, which opens room for automation.

There are two ways of working with kubectl:

• Imperative: you give the direct order, as in kubectl run nginx --image=nginx. It is fast and good for tests.
• Declarative: you write a YAML file that describes the desired state and run kubectl apply -f file.yaml. It is the dominant mode in real projects, because the file can be versioned in Git, reviewed and reapplied.

In this guide we start with the imperative way, which is faster to learn, and move to the declarative way in Stage 03.

Key concepts

The life cycle of a Pod

# Creates a pod named "nginx" from the nginx:1.14.2 image on Docker Hub
$ kubectl run nginx --image=nginx:1.14.2 --port=80
pod/nginx created
 
# Follow until the status becomes Running (the first state is ContainerCreating)
$ kubectl get pods
NAME    READY   STATUS    RESTARTS   AGE
nginx   1/1     Running   0          30s
 
# Details + events (see the "Pulling image" line in the Events section)
$ kubectl describe pod nginx
Name:         nginx
(...)
Events:
  Type    Reason     Age   From               Message
  Normal  Scheduled  35s   default-scheduler  Successfully assigned default/nginx to minikube
  Normal  Pulling    34s   kubelet            Pulling image "nginx:1.14.2"
  Normal  Pulled     20s   kubelet            Successfully pulled image "nginx:1.14.2"
  Normal  Created    20s   kubelet            Created container nginx
  Normal  Started    20s   kubelet            Started container nginx
 
# What the container is printing (nginx writes the access log to standard
# output, so it only shows lines after requests arrive)
$ kubectl logs nginx
 
# Opens a shell inside the container (type "exit" to leave).
# Note: after this command you are INSIDE the container and the prompt
# becomes "# ". The lines below that start with "# " (ls and exit) are not
# comments: they are commands typed in the container's shell.
$ kubectl exec -it nginx -- /bin/sh
# ls /usr/share/nginx/html
50x.html  index.html
# exit
 
# Back in your terminal (prompt "$"). Cleanup:
$ kubectl delete pod nginx
pod "nginx" deleted

Essential commands for this stage

Hands-on

Run the complete cycle and provoke your first error on purpose.

1. Run the sequence from the example (run, get, describe, logs, delete). Observe the Events section of describe: the lines Pulling image, Created container and Started container tell the pod's story in order.
2. Create a deliberately broken pod: kubectl run quebrado --image=nginx:versao-que-nao-existe.
3. Run kubectl get pods. Observe the status ErrImagePull, which soon becomes ImagePullBackOff.
4. Run kubectl describe pod quebrado. Observe in the Events the message saying the image was not found. You have just practiced the real debugging flow.
5. Run kubectl get pods -v=6 and observe the line with GET .../api/v1/namespaces/default/pods. This is the command translated into HTTP.
6. Clean up: kubectl delete pod quebrado.

Stage 03 architecture + labels

The anatomy of the cluster and its smallest unit, the Pod

The problem

The concept

A cluster is a group of machines (nodes) working together, with well-defined roles:

• The master node (control plane) manages the cluster and decides where to run the Pods.
• The worker nodes run the Pods and the other resources.
• etcd is the distributed database that stores the configuration and state of everything in the cluster.
• The kubelet is the agent that runs on each node and manages the Pods of that node.
• kube-proxy forwards network traffic to the right Pod.
• The API Server is the front door, through which everything kubectl does passes (Stage 02).

The Pod is the smallest unit that Kubernetes manages: an envelope with one or more containers that share network and storage. Four facts about Pods:

1. A Pod represents a running process and can have more than one container, all sharing the same IP and the same volumes.
2. Pods are ephemeral. They are born and die all the time, and you must never count on a specific Pod existing tomorrow. This sentence is the root of Stages 04, 05 and 06.
3. Each Pod receives an internal cluster IP.
4. Pods are described in YAML.

To organize many objects there are labels and annotations. Labels are key-value pairs used to identify and select objects: it is by label that a Service finds its Pods (Stage 04) and that a Deployment knows which Pods are its own (Stage 05). Annotations are free-form metadata (author, documentation link, audit data) that do not take part in selection; they are for people and tools to read. This difference is a classic exam question.

Key concepts

The first YAML

apiVersion: v1                # K8s API version for this object
kind: Pod                     # the TYPE of object created
metadata:                     # data ABOUT the object
  name: meu-pod
  labels:                     # labels: key-value pairs to SELECT
    app: myapp
    ambiente: estudo
  annotations:                # annotations: free-form metadata (docs)
    autor: "Davi Gomes"
spec:                         # the SPECIFICATION: what runs inside
  containers:
    - name: meu-container
      image: nginx:1.14.2
      ports:
        - containerPort: 80

Essential commands for this stage

Hands-on

1. Save the YAML above as etapa03/meu-pod.yaml and apply it with kubectl apply -f meu-pod.yaml.
2. Run kubectl get pods --show-labels. Observe the two labels in the last column.
3. Run kubectl get pods -l app=myapp and then kubectl get pods -l app=outra-coisa. Observe: the first finds the pod, the second answers No resources found in default namespace. This is the selection mechanism in action.
4. Add a label on the fly with kubectl label pod meu-pod time=devops and confirm with --show-labels.
5. Do not delete the pod now: it will be the target of the Service in the next stage, and its cleanup is at the end of Stage 04. If you deleted it, apply the YAML again. This is the advantage of the declarative way: the file recreates the identical object.

Stage 04 networking + config

Services and ConfigMaps, a fixed address and external configuration

The problem

The concept

Problem 1: the Service. The Service is a stable entry point that finds the Pods by label and balances traffic among them. The flow is:

1. A request arrives at the Service, which has a fixed IP and name.
2. The Service selects the Pods by label selector (the mechanism from Stage 03).
3. Traffic is distributed in a balanced way among the healthy replicas.

The Service name becomes an internal hostname of the cluster. If the Service is called auth-service, any Pod in the cluster can reach http://auth-service, even if the Pods behind it change IP repeatedly.

There are three types of Service:

• ClusterIP (the default): internal IP, reachable only from inside the cluster. It serves communication between services (for example, API to database).
• NodePort: opens a fixed port (from 30000 to 32767) on every node. Access from outside is done through node-IP:port. It is the way to expose something on Minikube.
• LoadBalancer: provisions an external load balancer with a public IP. It is the type used in production in the cloud (AWS, GCP, Azure).

Problem 2: the ConfigMap. The ConfigMap stores configuration in an object separate from the container. You inject it into the Pod in three ways:

• environment variables (the most common, via envFrom);
• mounted files (great for long configurations);
• command-line arguments.

When the configuration changes, you update the ConfigMap and the image stays the same, with no rebuild. But pay attention to one detail: environment variables are read when the container starts. Updating the ConfigMap does not change the variables of a Pod that is already running; the Pod needs to be recreated to see the new values (you will see this happen in practice in Stage 09). ConfigMaps mounted as files, on the other hand, are usually updated inside the Pod after some time, without recreating it, but the app needs to reread the file to use the new value.

Key concepts

Look at the selector

 # app.yaml: save the Service in this file
apiVersion: v1
kind: Service
metadata:
  name: meu-service            # becomes the internal hostname
spec:
  type: NodePort               # switch to ClusterIP (internal) or LoadBalancer (cloud)
  selector:                    # ← THE LINK: looks for Pods with this label
    app: myapp
  ports:
    - protocol: TCP
      port: 80                 # port the Service listens on
      targetPort: 80           # container port that receives
      nodePort: 30080          # port exposed on the node (NodePort only)

Essential commands for this stage

Hands-on

1. With the meu-pod from Stage 03 running (label app: myapp), save the Service YAML as etapa04/app.yaml and apply it.
2. Run minikube service meu-service --url and open the URL in the browser. Observe the nginx welcome page. You reached an ephemeral Pod through a stable address.
3. Test the link: delete the pod (kubectl delete pod meu-pod) and reload the browser. Observe that the page stops loading (the browser shows connection refused or timed out, depending on the system and the driver), since there is no Pod left with the label. Confirm the cause with kubectl get endpoints meu-service: the endpoints list is empty.

   $ kubectl get endpoints meu-service
   NAME          ENDPOINTS   AGE
   meu-service   <none>      5m

   Recreate the pod with kubectl apply -f ../etapa03/meu-pod.yaml and reload. Access is back without you touching the Service, and kubectl get endpoints meu-service shows an IP again (something like 10.244.0.7:80).
4. Apply the ConfigMap and the pod (kubectl apply -f configmap-pod.yaml) and run kubectl exec pod-config -- env. Observe MENSAGEM and MODO in the list of variables.
5. Clean up the objects of this stage and the previous one:

   $ kubectl delete -f app.yaml -f configmap-pod.yaml -f ../etapa03/meu-pod.yaml
   service "meu-service" deleted
   configmap "minha-config" deleted
   pod "pod-config" deleted
   pod "meu-pod" deleted

   (The order of the lines may vary.) Also close the minikube service terminal, with Ctrl+C.

Stage 05 self-healing + scale

Self-healing and scaling with ReplicaSets and Deployments

The problem

The concept

Two pieces solve this, one wrapping the other.

ReplicaSet: guarantees the number of replicas. You declare replicas: 3 and it monitors the Pods by label selector. If a Pod disappears, the ReplicaSet notices that the count dropped and creates another in seconds, without anyone asking. This is self-healing, the desired state from Stage 01 maintained in practice. The ReplicaSet takes care of Pods that disappear. If what fails is only the process inside the container (a crash), the Pod still exists and whoever restarts the container is the kubelet, inside the same Pod; this separation is detailed in Stage 07.

Deployment: manages versions. It creates and manages the ReplicaSet under the hood and adds:

• Rolling Update: when you change the image, the Deployment brings up new replicas and shuts down the old ones gradually, and the service never goes down.
• Rollback: if the new version breaks, kubectl rollout undo returns to the previous one in seconds.
• Manual scaling: kubectl scale --replicas=5 changes the number of replicas with one command.

Each version of the template has its own ReplicaSet. When the version changes, the Deployment creates a new ReplicaSet and shrinks the old one to zero. The name of a Pod reveals who it belongs to: in nginx-fiap-7d4b9c-aaa, the 7d4b9c part identifies the ReplicaSet (the version), and the final suffix identifies the Pod. When the middle suffix changes in the middle of a rolling update, you are looking at Pods from a new ReplicaSet.

The ReplicaSet and Deployment YAMLs are almost identical, but day to day we nearly always use the Deployment, precisely because of version control.

1. Before the update: every Pod runs the old version behind the Service.

2. A new Pod comes up with another IP; an old one starts to leave.

3. The swap continues one Pod at a time, and the Service keeps serving with the ready Pods.

4. Done: every Pod is on the new version, and the Service address did not change.

Key concepts

The complete Deployment and its life cycle

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-fiap
spec:
  replicas: 3                  # I want 3 copies, always
  selector:
    matchLabels:
      app: nginx-app           # I manage the Pods with this label...
  template:                    # ...and this is the "mold" of each Pod
    metadata:
      labels:
        app: nginx-app         # must match the selector ↑
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2  # changing this version triggers the rolling update
          ports:
            - containerPort: 80

Essential commands for this stage

Hands-on

This is the central exercise of the guide. Take it calmly and observe each state.

1. Apply deployment.yaml and confirm the 3 pods Running. Also run kubectl get rs and observe the nginx-fiap-<hash> ReplicaSet with 3 replicas: the prefix of the Pod names is its name.
2. Delete a pod by hand (copy a real name from kubectl get pods) and run kubectl get pods again, quickly. Observe the replacement in ContainerCreating. You tried to violate the desired state and the cluster corrected it.
3. Run the rolling update to nginx:1.16.1 and follow it with kubectl rollout status. Observe the success message. Run kubectl get rs and observe that there are now two ReplicaSets: the new one with 3 replicas and the old one with 0. This is why the suffix of the Pod names changed.
4. Break it on purpose with the image nginx:nao-existe. Observe in kubectl get pods the old pods Running holding the service and the new ones in ImagePullBackOff, and in kubectl get rs a third ReplicaSet with READY 0.
5. Run kubectl rollout undo deployment/nginx-fiap and confirm with kubectl rollout history deployment/nginx-fiap. Observe that the list goes 1, 3, 4: revision 2 became 4. Confirm the current image with kubectl describe deployment nginx-fiap | grep Image, which should show nginx:1.16.1. You did a rollback in one command.
6. Clean up: kubectl delete -f deployment.yaml (output: deployment.apps "nginx-fiap" deleted). The Deployment's ReplicaSets and Pods are removed along with it.

Stage 06 data persistence

Volumes, data that outlives the Pod

The problem

The concept

Kubernetes solves this with a chain of four concepts: Volume, PersistentVolume (PV), PersistentVolumeClaim (PVC) and StorageClass (SC).

• The PVC is the storage *request*: "I want 1Gi, read and write by one node".
• The PV is the *real disk* that fulfills the request (NFS, AWS EBS, hostPath and others).
• The StorageClass describes *types* of disk (standard, fast SSD) and lets the cluster create PVs automatically when a PVC asks for them.

The Pod references only the PVC and does not need to know where the disk physically is. This separation lets the same Pod YAML run on Minikube and on AWS, changing only what fulfills the request. On Minikube, the standard StorageClass already provisions PVs automatically: you create the PVC and the PV appears.

The most common volume types:

• emptyDir: born empty together with the Pod and dies with the Pod. It serves for temporary files and for sharing data between containers of the same Pod.
• hostPath: mounts a directory of the node inside the container. It is useful in development and dangerous in production, because it ties the Pod to that node.
• persistentVolumeClaim: the right way for real data, which survives restarts and recreation of the Pod.

The PVC access modes define who can mount the volume:

• ReadWriteOnce (RWO): read and write by a single node. It is the typical case for a database.
• ReadOnlyMany (ROX): read-only, by several nodes. It serves static assets.
• ReadWriteMany (RWX): read and write by several nodes. It requires NFS or an equivalent backend.

Key concepts

Write, destroy, read back

 # pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: meu-pvc
spec:
  accessModes:
    - ReadWriteOnce            # one node reads and writes (typical for a database)
  resources:
    requests:
      storage: 1Gi             # how much disk I want
 # on Minikube, the "standard" StorageClass provisions the PV by itself

Essential commands for this stage

Hands-on

1. Apply the PVC and run kubectl get pvc. Observe the STATUS Bound: the request was fulfilled by an automatically created PV. Confirm with kubectl get pv.
2. Run the complete sequence from the example: write the file, delete the pod, recreate the pod, read the file. Observe the sobrevivi! come back. This is the PVC contract.
3. Contrast experiment: save pod-emptydir.yaml and repeat the sequence (write, delete, recreate, read). Observe the No such file or directory at the end: the file vanished. This is the difference between ephemeral and persistent, seen in practice.
4. Clean up, in this order: kubectl delete pod pod-persistente pod-efemero and then kubectl delete pvc meu-pvc. With the PVC deleted, kubectl get pv should be empty (the PV was removed along with it, as described above).

Stage 07 app health

Probes, how the cluster knows your app is alive

The problem

The concept

Before probes, it is worth separating three situations that in everyday talk everyone calls "the app went down", because each one is handled by a different mechanism:

1. The process inside the container ends (a crash, out of memory, an unhandled exception). The Pod still exists and the one that reacts is the node's kubelet: it restarts the container inside the same Pod, according to the Pod's restartPolicy (the default is Always). The Pod's name and IP do not change, and the RESTARTS column goes up. This happens with no probe configured.
2. The Pod disappears (someone deleted it, the node went down). The whole Pod ceases to exist and the one that reacts is the ReplicaSet (Stage 05), which creates a new Pod, with a new name and IP. A standalone Pod, without a ReplicaSet or Deployment, does not come back.
3. The process is still alive but stuck (deadlock, infinite loop, exhausted dependency). Nothing ended and no Pod disappeared, so the two previous mechanisms do not notice. Only a liveness probe detects it, and when it fails the kubelet restarts the container, as in case 1.

Probes are health checks declared in the Pod manifest. The kubelet runs them periodically and acts according to the result.

There are three probes, and the most important point is what happens when each one fails:

• Liveness asks "is it alive?". If it fails, the kubelet restarts the container (inside the same Pod). It is for apps that hang and only come back with a restart.
• Readiness asks "is it ready to receive requests?". If it fails, the Pod leaves the load balancer (the Service stops sending traffic) without being restarted. It is for apps that load data before serving or that are temporarily unavailable.
• Startup asks "has it finished initializing?". While it runs, it holds back the other probes, preventing liveness from killing a slow app too early.

Each probe can check in three ways:

• httpGet: the kubelet makes a GET to an endpoint (for example /health) and expects a success status (200 OK). It is the most common. An error status, such as 404 or 500, counts as a failure.
• tcpSocket: tests whether the port accepts a connection. It serves services that do not speak HTTP.
• exec: runs a command inside the container; exit code 0 means healthy.

Good practices from the lesson: use all three probes together in production; use different endpoints for each probe; start with the default settings and adjust intervals only when the app asks for it; monitor probe failures (for example, with Prometheus), because they are the first sign of trouble.

Key concepts

Worked examples

apiVersion: v1
kind: Pod
metadata:
  name: exemplo-probes
spec:
  containers:
    - name: app
      image: exemplo:latest
      ports:
        - containerPort: 80
      livenessProbe:           # failed → RESTARTS the container
        httpGet:
          path: /health
          port: 80
        periodSeconds: 10      # checks every 10s
        timeoutSeconds: 5
        failureThreshold: 3    # 3 consecutive failures → restarts (3 is the default)
      readinessProbe:          # failed → LEAVES the load balancer
        httpGet:
          path: /ready         # good practice: separate endpoint
          port: 80
        periodSeconds: 5
      startupProbe:            # holds the others until the app is up
        httpGet:
          path: /startup
          port: 80
        initialDelaySeconds: 120   # slow app: waits 2min
        periodSeconds: 30

Essential commands for this stage

Hands-on

1. Apply liveness-exec.yaml and run kubectl get pods -w. Observe the RESTARTS column go up by itself: the first restart appears about 45 seconds after the start (30s healthy plus 3 failures spaced 5s apart). Each increment is the kubelet restarting a container that stopped passing the check.
2. In another terminal, run kubectl describe pod liveness-exec. Observe in the Events the pair Warning Unhealthy followed by Normal Killing. Learn to recognize this pair: in production, it is the diagnosis of a failing probe.
3. Run the crash experiment (kubectl run crash ...) and compare. Observe that RESTARTS also goes up, but describe shows Last State: Terminated with Exit Code: 1 and no Liveness probe failed event. This is case 1, handled by the kubelet without a probe; the one in step 2 is case 3, which only liveness solves.
4. Clean up: kubectl delete pod liveness-exec crash.

Stage 08 automatic scaling

HPA, automatic scaling based on metrics

The problem

The concept

The Horizontal Pod Autoscaler (HPA) monitors Pod metrics (CPU, memory and others) and adjusts the number of replicas between a minimum and a maximum that you define.

How it works: the HPA compares the current utilization of the Pods with the configured target (for example, keeping average CPU at 70%). If utilization goes above the target, it creates replicas, up to the maximum. If it drops, it removes replicas, down to the minimum, saving resources. The scale down is deliberately slow (about 5 minutes of stability) to avoid constant oscillation in the face of quick load variations.

Once an HPA controls a Deployment, it is the HPA that decides the number of replicas within the range minReplicas to maxReplicas. The replicas value written in the Deployment manifest holds only until the HPA acts: if it is above the floor and there is no load, the HPA reduces it after a few minutes (you will see this in Stage 09).

Which metrics the HPA can use. CPU and memory are read natively, through the metrics-server. The others require additional components installed in the cluster: custom metrics from your app (requests per second, queue size), external metrics (for example, coming from Prometheus) and disk I/O need a custom or external metrics adapter. Without that adapter, only CPU and memory are available. The right metric depends on the app's profile: a CPU-heavy app scales by CPU; one that consumes a lot of RAM scales by memory.

Two prerequisites are often forgotten:

1. The cluster needs the metrics-server to read CPU and memory. On Minikube: minikube addons enable metrics-server.
2. The container must declare `resources.requests.cpu`, because "70% CPU" means 70% of what the Pod requested. Without requests, the HPA shows <unknown> and does not scale.

Key concepts

Deployment, HPA, Service and load test

 # deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-hpa
spec:
  replicas: 1                  # starts with 1; the HPA takes over from here
  selector:
    matchLabels:
      app: nginx-hpa
  template:
    metadata:
      labels:
        app: nginx-hpa
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          resources:           # WITHOUT requests the HPA does not calculate %
            requests:
              cpu: "100m"      # 100 millicores = 0.1 CPU
            limits:
              cpu: "200m"

Essential commands for this stage

Hands-on

The final experiment of this part, which joins Deployment, Service and HPA.

1. Enable the metrics-server and apply the three YAMLs (Deployment, HPA, Service). Run kubectl get hpa and observe the targets. If <unknown> appears, wait about 1 minute: the metrics-server needs to collect the first reading.
2. Start the load generator in one terminal and run kubectl get hpa -w in another. Observe the CPU percentage go above 70% and then the REPLICAS column go up. If the percentage stalls below the target, use plan B. Confirm with kubectl get pods: new pods were born without any command from you.
3. Stop the load (Ctrl+C) and keep watching. Observe that the replicas take about 5 minutes to shrink. This slowness is deliberate.
4. Run kubectl top pods during the test to see the raw metric that feeds the HPA.
5. Clean up: kubectl delete -f deployment.yaml -f hpa.yaml -f service.yaml. The gerador pod was created with --rm and deleted itself when you interrupted the load; confirm with kubectl get pods. Keep the metrics-server enabled, because Stage 09 also uses the HPA.

Stage 09 bonus · real docker hub image

Bonus, a professional application with a real Docker Hub image

The problem

The concept

This stage builds a complete deployment with the stefanprodan/podinfo image from Docker Hub (docker.io/stefanprodan/podinfo). Podinfo is an open source project designed to be used in demonstrations. It exposes real /healthz and /readyz, accepts configuration through environment variables (PODINFO_UI_MESSAGE, PODINFO_UI_COLOR) and has a /panic endpoint that ends the process on purpose.

That last point deserves care, because /panic and liveness test different things. When the podinfo process ends, the one that restarts the container is the kubelet, through the Pod's `restartPolicy` (case 1 of Stage 07). This would happen even if the manifest had no livenessProbe at all. Liveness only comes into play in case 3, a process that is alive but does not respond in a healthy way. That is why this exercise uses /panic to demonstrate the restart of a container that went down, and tests liveness for real by pointing the probe at a path that does not exist, so that the endpoint starts returning 404 and the probe fails.

The four manifests fit together through the label app: podinfo, the same mechanism that stitched the whole guide together (Stage 03):

• The ConfigMap injects the variables via envFrom (Stage 04).
• The Deployment declares 3 replicas (Stage 05), resources.requests (required for the HPA, Stage 08) and two probes: liveness on /healthz and readiness on /readyz (Stage 07).
• The Service is NodePort because here podinfo is the system's entry point, applying the golden rule of Stage 04.
• The HPA reads the CPU declared in the Deployment and scales between 2 and 8 replicas (Stage 08).

There is an interaction between the Deployment and the HPA that is worth knowing: the Deployment declares replicas: 3, but the HPA has minReplicas: 2. While there is some load, or in the first minutes, you will see 3 replicas. Without load, after about 5 minutes (the stability window from Stage 08), the HPA reduces the Deployment to 2. From then on, the one in charge of the number of replicas is the HPA, and the manifest's replicas: 3 stops applying. In production, it is common to omit replicas from the Deployment when an HPA exists, precisely to avoid this dispute.

What was not included also matters. Not every piece you learned fits every app.

• The startupProbe (Stage 07) was left out because podinfo starts in fractions of a second. Using a piece just because it exists in the manual adds configuration with no benefit.
• The PVC (Stage 06) was also left out of the Deployment, for a technical reason. The problem: the PVC from Stage 06 uses ReadWriteOnce, and that mode cannot be shared among replicas on different nodes. On Minikube (a single node), attaching volumes.persistentVolumeClaim to a Deployment with several replicas may even start without complaint, but on a cluster with several nodes the extra replicas get stuck, competing for the same disk (the event shows up as FailedAttachVolume). The ways out, if the app needed state: a truly shared cache (podinfo has the --cache-server flag to talk to a Redis) or one disk per replica, with a StatefulSet and volumeClaimTemplates, a subject for the advanced module. Stage 06 remains valid: it is the right answer for its scenario, a single Pod with data, like a database.

Key concepts

The four manifests and the complete test

 # configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: podinfo-config
data:
  PODINFO_UI_MESSAGE: "olá do pitstop.dev!"   # appears on the app screen
  PODINFO_UI_COLOR: "#34d399"                 # banner color in the UI

Essential commands for this stage

Hands-on

In this exercise you build the complete deployment, provoke controlled failures and confirm each behavior. The command blocks for each step are in the example above.

1. Save the four YAMLs in etapa09/ (configmap.yaml, deployment.yaml, service.yaml, hpa.yaml) and apply them with a single kubectl apply pointing to the four files.
2. Run kubectl get pods,hpa until you see the pods Running (3 at the start) and the HPA with a real CPU value (not <unknown>). If it gets stuck, confirm that the Stage 08 metrics-server is still active. Remember that, without load, the HPA will reduce the 3 replicas to 2 in about 5 minutes; this is expected, and the following steps work with either number.
3. Run minikube service podinfo --url, keep that terminal open and, in another, run the loop for i in 1 2 3 4 5; do curl -s <URL> | grep hostname; done. Observe more than one hostname in the output. If you prefer the browser, know that it usually reuses the connection and may always show the same hostname.
4. Reproduce the ConfigMap gotcha: edit the message in configmap.yaml, apply it with kubectl apply -f configmap.yaml, confirm that kubectl exec ... env still shows the old value and only then run kubectl rollout restart deployment/podinfo. Confirm the change again. (You can also use kubectl edit configmap podinfo-config, which opens the system's default editor, usually vi; editing the file and reapplying is simpler and keeps the YAML versioned as the source of truth.)
5. Provoke a crash with curl .../panic and follow kubectl get pods -w until you see RESTARTS go up by itself, without you restarting anything. Observe with kubectl describe that the previous container is Terminated with a nonzero exit code and that there is no liveness event: the one that restarted it was the kubelet, through the restartPolicy.
6. Test liveness for real: change the probe path to /nao-existe with kubectl patch, wait about 30 seconds and observe RESTARTS go up (the status may alternate with CrashLoopBackOff between one restart and the next, which is expected) and, in describe, the events Liveness probe failed: HTTP probe failed with statuscode: 404 and Killing. Restore with kubectl apply -f deployment.yaml and run kubectl rollout status deployment/podinfo, waiting for the successfully rolled out message before step 7, so that head -n 1 does not pick an old Pod that is still terminating. Know that this apply sets replicas back to 3; the HPA reduces it to 2 again if there is no load.
7. Turn off the readiness of one Pod with curl -X POST .../readyz/disable and, after about 15 seconds, confirm with kubectl get pods (READY 0/1, RESTARTS unchanged) and kubectl get endpoints podinfo that this Pod left the list, without being restarted. With 2 replicas, 1 IP remains; with 3, 2 remain.
8. Finish by generating load as in Stage 08 (the same busybox generator against http://podinfo:9898) and observe the HPA scale this Deployment by itself.
9. Clean up: kubectl delete -f configmap.yaml -f deployment.yaml -f service.yaml -f hpa.yaml. Close the minikube service terminal with Ctrl+C. If you want to shut the lab down, minikube stop.

Stage 10 free labs

Practice for free on real clusters

These platforms give you a terminal with a real Kubernetes cluster right in the browser, with nothing to install. Start with the 100% free ones and move to the paid ones only when you want bigger challenges.

Stage 11 · review

Self-assessment checklist

Next steps: with all items checked, repeat the exercises on one of the platforms listed in the previous section, this time without consulting the guide. The next topic is the advanced module, where the StatefulSet mentioned in Stage 09 appears.