Kubernetes explicado
pela lente da F1.

Etapa 01 motivação + setup

Por que o Kubernetes existe

O problema

O conceito

A peça comum às duas soluções é o container.

Uma máquina virtual (VM) carrega hardware virtualizado e um sistema operacional completo: ocupa gigabytes e leva minutos para subir. Um container compartilha o kernel do sistema operacional da máquina hospedeira e leva apenas os arquivos, binários e bibliotecas de que o app precisa: ocupa megabytes e sobe em segundos. Uma imagem de container empacota esse ambiente inteiro e pode ser executada igual em qualquer lugar, o que resolve o "na minha máquina funciona".

Containers resolvem o problema do ambiente e criam outro. Com dezenas ou centenas deles, alguém precisa criá-los, destruí-los, vigiar a saúde de cada um e recriar o que falhar. Fazer isso manualmente não escala. O Kubernetes (K8s) é o orquestrador que assume essas tarefas.

A ideia central do Kubernetes é o estado desejado. Você não executa uma sequência de ordens ("suba este container, depois aquele"). Você declara o resultado que quer ("quero 3 cópias desta aplicação rodando") e o Kubernetes compara continuamente o que existe com o que foi declarado, corrigindo qualquer diferença. Se uma das cópias some às 3h da manhã (o Pod é apagado ou o nó onde ele rodava cai), o cluster percebe que existem 2 cópias em vez de 3 e cria a que falta, sem ninguém acordar. Quando o que falha é só o processo dentro do container, quem reage é outro mecanismo, que você vai separar com clareza na Etapa 07.

Os conceitos-chave

Montando o laboratório

# 1. Instale o Docker Desktop (docker.com). No Linux, use o Docker
#    Engine (docs.docker.com/engine/install). Confirme:
$ docker -v
Docker version 27.x
 
# 2. Instale o kubectl (kubernetes.io/docs/tasks/tools) e confirme.
#    Use --client: ainda não existe cluster, então só a versão do
#    cliente pode ser consultada (sem --client, o kubectl tentaria falar
#    com um servidor inexistente e imprimiria um erro de conexão)
$ kubectl version --client
Client Version: v1.30.x
Kustomize Version: v5.x
 
# 3. Instale o Minikube (minikube.sigs.k8s.io/docs/start) e suba o cluster:
$ minikube start
😄  minikube v1.33 on Windows 11
✨  Using the docker driver
🏄  Done! kubectl is now configured to use "minikube"
 
# 4. Confirme que o cluster está de pé:
$ kubectl get nodes
NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   1m    v1.30.x
 
# 5. Cluster vazio = sucesso:
$ kubectl get pods
No resources found in default namespace.
 
# 6. Agora que o cluster existe, a versão completa mostra cliente e servidor:
$ kubectl version --output=yaml
clientVersion:
  (...)
serverVersion:
  (...)

Comandos essenciais desta etapa

Mão na massa

O menor exercício possível: provar que o laboratório está vivo.

1. Rode minikube start e aguarde o "Done!".
2. Rode kubectl get nodes. Observe o nó minikube com STATUS Ready. Se aparecer NotReady, aguarde 1 minuto e repita.
3. Rode kubectl get pods. Observe No resources found in default namespace. Um cluster vazio e pronto é o ponto de partida da próxima etapa.
4. Bônus: rode minikube stop e depois kubectl get nodes. Observe a mensagem de erro de conexão (o cluster não responde). Suba de novo com minikube start. Agora você sabe como "cluster fora do ar" aparece no terminal.

Etapa 02 linha de comando + API

kubectl e a API, como você comanda o cluster

O problema

O conceito

Tudo no Kubernetes passa pela API REST do nó master (o *control plane*). O kubectl é o cliente dessa API: cada comando que você digita vira uma requisição HTTP (GET, POST, PUT ou DELETE) contra o cluster.

O caminho de um comando é este:

1. Você digita kubectl get pods.
2. O kubectl lê o arquivo kubeconfig, que guarda o endereço do API Server, as credenciais e o contexto do cluster atual. O Minikube preenche esse arquivo sozinho no minikube start.
3. O kubectl envia um GET ao API Server (para o namespace default, o caminho é /api/v1/namespaces/default/pods).
4. A resposta volta e o kubectl a formata no terminal.

A API é dividida em grupos. O grupo "core" tem os recursos fundamentais (pods, services, replicasets); outros grupos cuidam de segurança, armazenamento e autoscaling. Como é REST puro, qualquer linguagem (Python, Go, Java, C#) consegue chamá-la, o que abre espaço para automação.

Existem dois jeitos de trabalhar com o kubectl:

• Imperativo: você dá a ordem direta, como em kubectl run nginx --image=nginx. É rápido e serve para testes.
• Declarativo: você escreve um arquivo YAML que descreve o estado desejado e roda kubectl apply -f arquivo.yaml. É o modo dominante em projetos reais, porque o arquivo pode ser versionado no Git, revisado e reaplicado.

Neste guia começamos pelo imperativo, que é mais rápido para aprender, e passamos ao declarativo na Etapa 03.

Os conceitos-chave

Ciclo de vida de um Pod

# Cria um pod chamado "nginx" a partir da imagem nginx:1.14.2 do Docker Hub
$ kubectl run nginx --image=nginx:1.14.2 --port=80
pod/nginx created
 
# Acompanhe até o status ficar Running (o primeiro estado é ContainerCreating)
$ kubectl get pods
NAME    READY   STATUS    RESTARTS   AGE
nginx   1/1     Running   0          30s
 
# Detalhes + eventos (veja a linha "Pulling image" na seção Events)
$ 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
 
# O que o container está imprimindo (o nginx escreve o log de acesso na saída
# padrão, então ele só mostra linhas depois que chegam requisições)
$ kubectl logs nginx
 
# Abre um shell dentro do container (digite "exit" para sair).
# Atenção: depois deste comando você está DENTRO do container e o prompt
# passa a ser "# ". As linhas abaixo que começam com "# " (ls e exit) não
# são comentários: são comandos digitados no shell do container.
$ kubectl exec -it nginx -- /bin/sh
# ls /usr/share/nginx/html
50x.html  index.html
# exit
 
# De volta ao seu terminal (prompt "$"). Limpeza:
$ kubectl delete pod nginx
pod "nginx" deleted

Comandos essenciais desta etapa

Mão na massa

Execute o ciclo completo e provoque o primeiro erro de propósito.

1. Rode a sequência do exemplo (run, get, describe, logs, delete). Observe a seção Events do describe: as linhas Pulling image, Created container e Started container contam a história do pod em ordem.
2. Crie um pod quebrado de propósito: kubectl run quebrado --image=nginx:versao-que-nao-existe.
3. Rode kubectl get pods. Observe o status ErrImagePull, que logo vira ImagePullBackOff.
4. Rode kubectl describe pod quebrado. Observe nos Events a mensagem dizendo que a imagem não foi encontrada. Você acabou de praticar o fluxo de debug real.
5. Rode kubectl get pods -v=6 e observe a linha com GET .../api/v1/namespaces/default/pods. Esse é o comando traduzido em HTTP.
6. Limpe: kubectl delete pod quebrado.

Etapa 03 arquitetura + labels

A anatomia do cluster e a menor unidade dele, o Pod

O problema

O conceito

Um cluster é um grupo de máquinas (nodes) trabalhando juntas, com papéis bem definidos:

• O master node (control plane) gerencia o cluster e decide onde executar os Pods.
• Os worker nodes executam os Pods e os demais recursos.
• O etcd é o banco de dados distribuído que guarda a configuração e o estado de tudo no cluster.
• O kubelet é o agente que roda em cada node e gerencia os Pods daquele node.
• O kube-proxy encaminha o tráfego de rede até o Pod certo.
• O API Server é a porta de entrada, por onde passa tudo que o kubectl faz (Etapa 02).

O Pod é a menor unidade que o Kubernetes gerencia: um envelope com um ou mais containers que dividem rede e armazenamento. Quatro fatos sobre Pods:

1. Um Pod representa um processo em execução e pode ter mais de um container, todos dividindo o mesmo IP e os mesmos volumes.
2. Pods são efêmeros. Nascem e morrem o tempo todo, e você nunca deve contar com um Pod específico existindo amanhã. Esta frase é a raiz das Etapas 04, 05 e 06.
3. Cada Pod recebe um IP interno do cluster.
4. Pods são descritos em YAML.

Para organizar muitos objetos existem labels (rótulos) e annotations (anotações). Labels são pares chave-valor usados para identificar e selecionar objetos: é por label que um Service encontra seus Pods (Etapa 04) e que um Deployment sabe quais Pods são seus (Etapa 05). Annotations são metadados livres (autor, link de documentação, dados de auditoria) que não participam de seleção; servem para pessoas e ferramentas lerem. Essa diferença é uma pergunta clássica de prova.

Os conceitos-chave

O primeiro YAML

apiVersion: v1                # versão da API do K8s p/ este objeto
kind: Pod                     # o TIPO de objeto criado
metadata:                     # dados SOBRE o objeto
  name: meu-pod
  labels:                     # rótulos: chave-valor p/ SELECIONAR
    app: myapp
    ambiente: estudo
  annotations:                # anotações: metadados livres (docs)
    autor: "Davi Gomes"
spec:                         # a ESPECIFICAÇÃO: o que roda dentro
  containers:
    - name: meu-container
      image: nginx:1.14.2
      ports:
        - containerPort: 80

Comandos essenciais desta etapa

Mão na massa

1. Salve o YAML acima como etapa03/meu-pod.yaml e aplique com kubectl apply -f meu-pod.yaml.
2. Rode kubectl get pods --show-labels. Observe os dois labels na última coluna.
3. Rode kubectl get pods -l app=myapp e depois kubectl get pods -l app=outra-coisa. Observe: o primeiro encontra o pod, o segundo responde No resources found in default namespace. Esse é o mecanismo de seleção em ação.
4. Adicione um label em tempo real com kubectl label pod meu-pod time=devops e confirme com --show-labels.
5. Não delete o pod agora: ele será o alvo do Service na próxima etapa, e a limpeza dele está no final da Etapa 04. Se você deletou, aplique o YAML de novo. Essa é a vantagem do declarativo: o arquivo recria o objeto idêntico.

Etapa 04 rede + configuração

Services e ConfigMaps, endereço fixo e configuração externa

O problema

O conceito

Problema 1: o Service. O Service é um ponto de entrada estável que encontra os Pods por label e balanceia o tráfego entre eles. O fluxo é:

1. Uma requisição chega ao Service, que tem IP e nome fixos.
2. O Service seleciona os Pods pelo label selector (o mecanismo da Etapa 03).
3. O tráfego é distribuído de forma balanceada entre as réplicas saudáveis.

O nome do Service vira um hostname interno do cluster. Se o Service se chama auth-service, qualquer Pod do cluster consegue acessar http://auth-service, mesmo que os Pods por trás dele troquem de IP repetidamente.

Existem três tipos de Service:

• ClusterIP (o padrão): IP interno, acessível só de dentro do cluster. Serve para a comunicação entre serviços (por exemplo, API para banco).
• NodePort: abre uma porta fixa (de 30000 a 32767) em cada nó. O acesso de fora é feito por IP-do-nó:porta. É o jeito de expor algo no Minikube.
• LoadBalancer: provisiona um balanceador externo com IP público. É o tipo usado em produção na nuvem (AWS, GCP, Azure).

Problema 2: o ConfigMap. O ConfigMap guarda a configuração em um objeto separado do container. Você o injeta no Pod de três formas:

• variáveis de ambiente (a mais comum, via envFrom);
• arquivos montados (ótimo para configurações longas);
• argumentos de linha de comando.

Quando a configuração muda, você atualiza o ConfigMap e a imagem continua a mesma, sem rebuild. Mas atenção a um detalhe: variáveis de ambiente são lidas quando o container inicia. Atualizar o ConfigMap não altera as variáveis de um Pod que já está rodando; o Pod precisa ser recriado para enxergar os valores novos (você vai ver isso acontecer na prática na Etapa 09). Já os ConfigMaps montados como arquivos costumam ser atualizados dentro do Pod depois de algum tempo, sem recriá-lo, mas o app precisa reler o arquivo para usar o valor novo.

Os conceitos-chave

Repare no selector

 # app.yaml: salve o Service neste arquivo
apiVersion: v1
kind: Service
metadata:
  name: meu-service            # vira o hostname interno
spec:
  type: NodePort               # troque p/ ClusterIP (interno) ou LoadBalancer (nuvem)
  selector:                    # ← O ELO: procura Pods com este label
    app: myapp
  ports:
    - protocol: TCP
      port: 80                 # porta em que o Service escuta
      targetPort: 80           # porta do container que recebe
      nodePort: 30080          # porta exposta no nó (só NodePort)

Comandos essenciais desta etapa

Mão na massa

1. Com o meu-pod da Etapa 03 rodando (label app: myapp), salve o YAML do Service como etapa04/app.yaml e aplique.
2. Rode minikube service meu-service --url e abra a URL no navegador. Observe a página de boas-vindas do nginx. Você acessou um Pod efêmero por um endereço estável.
3. Teste o elo: delete o pod (kubectl delete pod meu-pod) e recarregue o navegador. Observe que a página deixa de carregar (o navegador mostra conexão recusada ou tempo esgotado, dependendo do sistema e do driver), já que não existe mais nenhum Pod com o label. Confirme a causa com kubectl get endpoints meu-service: a lista de endpoints está vazia.

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

   Recrie o pod com kubectl apply -f ../etapa03/meu-pod.yaml e recarregue. O acesso voltou sem você tocar no Service, e kubectl get endpoints meu-service volta a mostrar um IP (algo como 10.244.0.7:80).
4. Aplique o ConfigMap e o pod (kubectl apply -f configmap-pod.yaml) e rode kubectl exec pod-config -- env. Observe MENSAGEM e MODO na lista de variáveis.
5. Limpe os objetos desta etapa e da anterior:

   $ 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

   (A ordem das linhas pode variar.) Feche também o terminal do minikube service, com Ctrl+C.

Etapa 05 auto-cura + escala

Auto-cura e escala com ReplicaSets e Deployments

O problema

O conceito

Duas peças resolvem isso, uma embrulhando a outra.

ReplicaSet: garante o número de réplicas. Você declara replicas: 3 e ele monitora os Pods por label selector. Se um Pod some, o ReplicaSet percebe que a contagem caiu e cria outro em segundos, sem ninguém pedir. Essa é a auto-cura, o estado desejado da Etapa 01 mantido na prática. O ReplicaSet cuida de Pods que desaparecem. Se o que falha é só o processo dentro do container (um crash), o Pod continua existindo e quem reinicia o container é o kubelet, dentro do mesmo Pod; essa separação é detalhada na Etapa 07.

Deployment: gerencia versões. Ele cria e gerencia o ReplicaSet por baixo dos panos e adiciona:

• Rolling Update: ao trocar a imagem, o Deployment sobe réplicas novas e desliga as antigas gradualmente, e o serviço nunca fica fora do ar.
• Rollback: se a versão nova quebrar, kubectl rollout undo volta para a anterior em segundos.
• Escala manual: kubectl scale --replicas=5 muda o número de réplicas com um comando.

Cada versão do template tem o seu próprio ReplicaSet. Na troca de versão, o Deployment cria um ReplicaSet novo e vai reduzindo o antigo até zero. O nome de um Pod revela a quem ele pertence: em nginx-fiap-7d4b9c-aaa, o trecho 7d4b9c identifica o ReplicaSet (a versão), e o sufixo final identifica o Pod. Quando o sufixo do meio muda no meio de um rolling update, você está vendo Pods de um ReplicaSet novo.

Os YAMLs de ReplicaSet e Deployment são quase idênticos, mas no dia a dia usamos quase sempre o Deployment, justamente pelo controle de versão.

1. Antes da atualização: todos os Pods rodam a versão antiga atrás do Service.

2. Um Pod novo sobe com outro IP; um antigo começa a sair.

3. A troca continua um Pod por vez, e o Service segue atendendo com os Pods prontos.

4. Fim: todos os Pods estão na versão nova, e o endereço do Service não mudou.

Os conceitos-chave

O Deployment completo e o ciclo de vida

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-fiap
spec:
  replicas: 3                  # quero 3 cópias, sempre
  selector:
    matchLabels:
      app: nginx-app           # gerencio os Pods com este label...
  template:                    # ...e este é o "molde" de cada Pod
    metadata:
      labels:
        app: nginx-app         # tem que casar com o selector ↑
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2  # trocar esta versão dispara o rolling update
          ports:
            - containerPort: 80

Comandos essenciais desta etapa

Mão na massa

Este é o exercício central do guia. Vá com calma e observe cada estado.

1. Aplique o deployment.yaml e confirme os 3 pods Running. Rode também kubectl get rs e observe o ReplicaSet nginx-fiap-<hash> com 3 réplicas: o prefixo dos nomes dos Pods é o nome dele.
2. Delete um pod na mão (copie um nome real do kubectl get pods) e rode kubectl get pods de novo, rápido. Observe o substituto em ContainerCreating. Você tentou violar o estado desejado e o cluster corrigiu.
3. Rode o rolling update para nginx:1.16.1 e acompanhe com kubectl rollout status. Observe a mensagem de sucesso. Rode kubectl get rs e observe que há agora dois ReplicaSets: o novo com 3 réplicas e o antigo com 0. É por isso que o sufixo do nome dos Pods mudou.
4. Quebre de propósito com a imagem nginx:nao-existe. Observe no kubectl get pods os pods antigos Running segurando o serviço e os novos em ImagePullBackOff, e no kubectl get rs um terceiro ReplicaSet com READY 0.
5. Execute kubectl rollout undo deployment/nginx-fiap e confirme com kubectl rollout history deployment/nginx-fiap. Observe que a lista vai 1, 3, 4: a revisão 2 virou a 4. Confirme a imagem atual com kubectl describe deployment nginx-fiap | grep Image, que deve mostrar nginx:1.16.1. Você fez um rollback em um comando.
6. Limpe: kubectl delete -f deployment.yaml (saída: deployment.apps "nginx-fiap" deleted). Os ReplicaSets e Pods do Deployment são removidos junto.

Etapa 06 persistência de dados

Volumes, dados que sobrevivem ao Pod

O problema

O conceito

O Kubernetes resolve isso com uma cadeia de quatro conceitos: Volume, PersistentVolume (PV), PersistentVolumeClaim (PVC) e StorageClass (SC).

• O PVC é o *pedido* de armazenamento: "quero 1Gi, leitura e escrita por um nó".
• O PV é o *disco real* que atende o pedido (NFS, EBS da AWS, hostPath e outros).
• A StorageClass descreve *tipos* de disco (padrão, SSD rápido) e permite que o cluster crie PVs automaticamente quando um PVC os solicita.

O Pod referencia apenas o PVC e não precisa saber onde o disco fica fisicamente. Essa separação permite que o mesmo YAML de Pod rode no Minikube e na AWS, mudando só o que atende o pedido. No Minikube, a StorageClass standard já provisiona PVs automaticamente: você cria o PVC e o PV aparece.

Os tipos de volume mais comuns:

• emptyDir: nasce vazio junto com o Pod e morre com o Pod. Serve para arquivos temporários e para compartilhar dados entre containers do mesmo Pod.
• hostPath: monta um diretório do nó dentro do container. É útil em desenvolvimento e perigoso em produção, porque amarra o Pod àquele nó.
• persistentVolumeClaim: o jeito correto para dados de verdade, que sobrevivem a reinício e recriação do Pod.

Os modos de acesso do PVC definem quem pode montar o volume:

• ReadWriteOnce (RWO): leitura e escrita por um único nó. É o caso típico de banco de dados.
• ReadOnlyMany (ROX): somente leitura, por vários nós. Serve para assets estáticos.
• ReadWriteMany (RWX): leitura e escrita por vários nós. Exige NFS ou um backend equivalente.

Os conceitos-chave

Escreva, destrua, leia de volta

 # pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: meu-pvc
spec:
  accessModes:
    - ReadWriteOnce            # um nó lê e escreve (típico de banco)
  resources:
    requests:
      storage: 1Gi             # quanto disco eu quero
 # no Minikube, a StorageClass "standard" provisiona o PV sozinha

Comandos essenciais desta etapa

Mão na massa

1. Aplique o PVC e rode kubectl get pvc. Observe o STATUS Bound: o pedido foi atendido por um PV criado automaticamente. Confirme com kubectl get pv.
2. Execute a sequência completa do exemplo: escrever o arquivo, deletar o pod, recriar o pod, ler o arquivo. Observe o sobrevivi! voltar. Esse é o contrato do PVC.
3. Experimento de contraste: salve o pod-emptydir.yaml e repita a sequência (escrever, deletar, recriar, ler). Observe o No such file or directory no final: o arquivo sumiu. Essa é a diferença entre efêmero e persistente, vista na prática.
4. Limpe, nesta ordem: kubectl delete pod pod-persistente pod-efemero e depois kubectl delete pvc meu-pvc. Com o PVC apagado, kubectl get pv deve ficar vazio (o PV foi removido junto, como descrito acima).

Etapa 07 saúde do app

Probes, como o cluster sabe que seu app está vivo

O problema

O conceito

Antes das probes, convém separar três situações que no dia a dia todo mundo chama de "o app caiu", porque cada uma é tratada por um mecanismo diferente:

1. O processo dentro do container termina (um crash, falta de memória, uma exceção não tratada). O Pod continua existindo e quem reage é o kubelet do nó: ele reinicia o container dentro do mesmo Pod, conforme a restartPolicy do Pod (o padrão é Always). O nome e o IP do Pod não mudam, e a coluna RESTARTS sobe. Isso acontece sem nenhuma probe configurada.
2. O Pod some (alguém o apagou, o nó caiu). O Pod inteiro deixa de existir e quem reage é o ReplicaSet (Etapa 05), que cria um Pod novo, com nome e IP novos. Um Pod avulso, sem ReplicaSet ou Deployment, não volta.
3. O processo continua vivo, mas travado (deadlock, loop infinito, dependência esgotada). Nada terminou e nenhum Pod sumiu, então os dois mecanismos anteriores não percebem. Só uma probe de liveness detecta, e quando ela falha o kubelet reinicia o container, como no caso 1.

As probes são verificações de saúde declaradas no manifesto do Pod. O kubelet as executa periodicamente e age conforme o resultado.

São três probes, e o ponto mais importante é o que acontece quando cada uma falha:

• Liveness pergunta "está vivo?". Se falha, o kubelet reinicia o container (dentro do mesmo Pod). É para apps que travam e só voltam com restart.
• Readiness pergunta "está pronto para receber requisições?". Se falha, o Pod sai do balanceador (o Service para de mandar tráfego) sem ser reiniciado. É para apps que carregam dados antes de atender ou que ficam temporariamente indisponíveis.
• Startup pergunta "terminou de inicializar?". Enquanto roda, segura as outras probes, evitando que a liveness mate um app lento antes da hora.

Cada probe pode verificar de três formas:

• httpGet: o kubelet faz um GET em um endpoint (por exemplo /health) e espera um status de sucesso (200 OK). É o mais comum. Um status de erro, como 404 ou 500, conta como falha.
• tcpSocket: testa se a porta aceita conexão. Serve para serviços que não falam HTTP.
• exec: executa um comando dentro do container; código de saída 0 significa saudável.

Boas práticas da aula: use as três probes juntas em produção; use endpoints diferentes para cada probe; comece pelas configurações padrão e ajuste intervalos só quando o app pedir; monitore as falhas de probe (por exemplo, com Prometheus), porque elas são o primeiro sinal de problema.

Os conceitos-chave

Exemplos comentados

apiVersion: v1
kind: Pod
metadata:
  name: exemplo-probes
spec:
  containers:
    - name: app
      image: exemplo:latest
      ports:
        - containerPort: 80
      livenessProbe:           # falhou → REINICIA o container
        httpGet:
          path: /health
          port: 80
        periodSeconds: 10      # verifica a cada 10s
        timeoutSeconds: 5
        failureThreshold: 3    # 3 falhas seguidas → reinicia (3 é o padrão)
      readinessProbe:          # falhou → SAI do balanceador
        httpGet:
          path: /ready         # boa prática: endpoint separado
          port: 80
        periodSeconds: 5
      startupProbe:            # segura as outras até o app subir
        httpGet:
          path: /startup
          port: 80
        initialDelaySeconds: 120   # app lento: espera 2min
        periodSeconds: 30

Comandos essenciais desta etapa

Mão na massa

1. Aplique o liveness-exec.yaml e rode kubectl get pods -w. Observe a coluna RESTARTS subir sozinha: a primeira reinicialização aparece cerca de 45 segundos após o início (30s saudável mais 3 falhas espaçadas de 5s). Cada incremento é o kubelet reiniciando um container que parou de passar na verificação.
2. Em outro terminal, rode kubectl describe pod liveness-exec. Observe nos Events o par Warning Unhealthy seguido de Normal Killing. Aprenda a reconhecer essa dupla: em produção, ela é o diagnóstico de probe falhando.
3. Rode o experimento do crash (kubectl run crash ...) e compare. Observe que o RESTARTS também sobe, mas o describe mostra Last State: Terminated com Exit Code: 1 e nenhum evento Liveness probe failed. Este é o caso 1, tratado pelo kubelet sem probe; o do passo 2 é o caso 3, que só a liveness resolve.
4. Limpe: kubectl delete pod liveness-exec crash.

Etapa 08 escala automática

HPA, escala automática baseada em métricas

O problema

O conceito

O Horizontal Pod Autoscaler (HPA) monitora métricas dos Pods (CPU, memória e outras) e ajusta o número de réplicas entre um mínimo e um máximo definidos por você.

O funcionamento: o HPA compara a utilização atual dos Pods com o alvo configurado (por exemplo, manter a média de CPU em 70%). Se a utilização passa do alvo, ele cria réplicas, até o máximo. Se cai, ele remove réplicas, até o mínimo, economizando recursos. O scale down é propositalmente lento (cerca de 5 minutos de estabilidade) para evitar oscilações constantes diante de variações rápidas de carga.

Quando um HPA passa a controlar um Deployment, é ele quem decide o número de réplicas dentro da faixa minReplicas a maxReplicas. O valor replicas escrito no manifesto do Deployment vale só até o HPA agir: se ele for maior que o piso e não houver carga, o HPA o reduz depois de alguns minutos (você vai ver isso na Etapa 09).

Quais métricas o HPA consegue usar. CPU e memória são lidas nativamente, por meio do metrics-server. As demais exigem componentes adicionais instalados no cluster: métricas personalizadas do seu app (requisições por segundo, tamanho de fila), métricas externas (por exemplo, vindas do Prometheus) e E/S de disco precisam de um adaptador de métricas customizadas ou externas. Sem esse adaptador, só CPU e memória estão disponíveis. A métrica certa depende do perfil do app: um app pesado em CPU escala por CPU; um que consome muita RAM escala por memória.

Dois pré-requisitos costumam ser esquecidos:

1. O cluster precisa do metrics-server para ler CPU e memória. No Minikube: minikube addons enable metrics-server.
2. O container precisa declarar `resources.requests.cpu`, porque "70% de CPU" significa 70% do que o Pod pediu. Sem requests, o HPA mostra <unknown> e não escala.

Os conceitos-chave

Deployment, HPA, Service e teste de carga

 # deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-hpa
spec:
  replicas: 1                  # começa com 1; o HPA assume daqui
  selector:
    matchLabels:
      app: nginx-hpa
  template:
    metadata:
      labels:
        app: nginx-hpa
    spec:
      containers:
        - name: nginx
          image: nginx:1.14.2
          resources:           # SEM requests o HPA não calcula %
            requests:
              cpu: "100m"      # 100 milicores = 0,1 CPU
            limits:
              cpu: "200m"

Comandos essenciais desta etapa

Mão na massa

O experimento final desta parte, que junta Deployment, Service e HPA.

1. Ative o metrics-server e aplique os três YAMLs (Deployment, HPA, Service). Rode kubectl get hpa e observe os targets. Se aparecer <unknown>, aguarde cerca de 1 minuto: o metrics-server precisa coletar a primeira leitura.
2. Suba o gerador de carga em um terminal e rode kubectl get hpa -w em outro. Observe o percentual de CPU passar de 70% e, em seguida, a coluna REPLICAS subir. Se o percentual estacionar abaixo do alvo, use o plano B. Confirme com kubectl get pods: pods novos nasceram sem nenhum comando seu.
3. Pare a carga (Ctrl+C) e continue assistindo. Observe que as réplicas levam cerca de 5 minutos para encolher. Essa lentidão é proposital.
4. Rode kubectl top pods durante o teste para ver a métrica crua que alimenta o HPA.
5. Limpe: kubectl delete -f deployment.yaml -f hpa.yaml -f service.yaml. O pod gerador foi criado com --rm e já se apagou quando você interrompeu a carga; confirme com kubectl get pods. Mantenha o metrics-server ativo, porque a Etapa 09 também usa o HPA.

Etapa 09 bônus · imagem real do docker hub

Bônus, aplicação profissional com uma imagem real do Docker Hub

O problema

O conceito

Esta etapa monta um deployment completo com a imagem stefanprodan/podinfo do Docker Hub (docker.io/stefanprodan/podinfo). O podinfo é um projeto open source pensado para ser usado em demonstrações. Ele expõe /healthz e /readyz de verdade, aceita configuração por variáveis de ambiente (PODINFO_UI_MESSAGE, PODINFO_UI_COLOR) e tem um endpoint /panic que encerra o processo de propósito.

Esse último ponto merece cuidado, porque /panic e liveness testam coisas diferentes. Quando o processo do podinfo termina, quem reinicia o container é o kubelet, pela `restartPolicy` do Pod (caso 1 da Etapa 07). Isso aconteceria mesmo que o manifesto não tivesse nenhuma livenessProbe. A liveness só entra em ação no caso 3, processo vivo que não responde de forma saudável. Por isso este exercício usa o /panic para demonstrar o reinício de um container que caiu, e testa a liveness de verdade apontando a probe para um caminho que não existe, de modo que o endpoint passe a devolver 404 e a probe falhe.

Os quatro manifestos se encaixam pelo label app: podinfo, o mesmo mecanismo que costurou o guia inteiro (Etapa 03):

• O ConfigMap injeta as variáveis via envFrom (Etapa 04).
• O Deployment declara 3 réplicas (Etapa 05), resources.requests (obrigatório para o HPA, Etapa 08) e duas probes: liveness em /healthz e readiness em /readyz (Etapa 07).
• O Service é NodePort porque aqui o podinfo é o ponto de entrada do sistema, aplicando a regra de ouro da Etapa 04.
• O HPA lê a CPU declarada no Deployment e escala entre 2 e 8 réplicas (Etapa 08).

Há uma interação entre o Deployment e o HPA que vale conhecer: o Deployment declara replicas: 3, mas o HPA tem minReplicas: 2. Enquanto há alguma carga, ou nos primeiros minutos, você verá 3 réplicas. Sem carga, depois de cerca de 5 minutos (a janela de estabilidade da Etapa 08), o HPA reduz o Deployment para 2. A partir daí, quem manda no número de réplicas é o HPA, e o replicas: 3 do manifesto deixa de valer. Em produção, é comum omitir replicas do Deployment quando existe HPA, justamente para evitar essa disputa.

Também importa o que não entrou. Nem toda peça aprendida cabe em todo app.

• A startupProbe (Etapa 07) ficou de fora porque o podinfo sobe em frações de segundo. Usar uma peça só porque ela existe no manual adiciona configuração sem benefício.
• O PVC (Etapa 06) também ficou fora do Deployment, por um motivo técnico. O problema: o PVC da Etapa 06 usa ReadWriteOnce, e esse modo não pode ser dividido entre réplicas em nós diferentes. No Minikube (um nó só) colar o volumes.persistentVolumeClaim em um Deployment com várias réplicas pode até subir sem reclamar, mas num cluster com vários nós as réplicas extras ficam presas, disputando o mesmo disco (o evento aparece como FailedAttachVolume). As saídas, se o app precisasse de estado: um cache compartilhado de verdade (o podinfo tem a flag --cache-server para falar com um Redis) ou um disco por réplica, com um StatefulSet e volumeClaimTemplates, assunto do módulo avançado. A Etapa 06 continua válida: ela é a resposta certa para o cenário dela, um Pod único com dados, como um banco.

Os conceitos-chave

Os quatro manifestos e o teste completo

 # configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: podinfo-config
data:
  PODINFO_UI_MESSAGE: "olá do pitstop.dev!"   # aparece na tela do app
  PODINFO_UI_COLOR: "#34d399"                 # cor do banner na UI

Comandos essenciais desta etapa

Mão na massa

Neste exercício você monta o deployment completo, provoca falhas controladas e confirma cada comportamento. Os blocos de comandos de cada passo estão no exemplo acima.

1. Salve os quatro YAMLs em etapa09/ (configmap.yaml, deployment.yaml, service.yaml, hpa.yaml) e aplique com um único kubectl apply apontando para os quatro arquivos.
2. Rode kubectl get pods,hpa até ver os pods Running (3 no começo) e o HPA com um valor de CPU real (não <unknown>). Se travar, confirme que o metrics-server da Etapa 08 continua ativo. Lembre que, sem carga, o HPA reduzirá as 3 réplicas para 2 em cerca de 5 minutos; isso é esperado, e os passos seguintes funcionam com qualquer um dos dois números.
3. Rode minikube service podinfo --url, deixe esse terminal aberto e, em outro, execute o laço for i in 1 2 3 4 5; do curl -s <URL> | grep hostname; done. Observe mais de um hostname na saída. Se preferir o navegador, saiba que ele costuma reaproveitar a conexão e pode mostrar sempre o mesmo hostname.
4. Reproduza a pegadinha do ConfigMap: edite a mensagem no configmap.yaml, aplique com kubectl apply -f configmap.yaml, confirme que kubectl exec ... env ainda mostra o valor antigo e só depois rode kubectl rollout restart deployment/podinfo. Confirme a mudança de novo. (Você também pode usar kubectl edit configmap podinfo-config, que abre o editor padrão do sistema, geralmente o vi; editar o arquivo e reaplicar é mais simples e mantém o YAML versionado como fonte da verdade.)
5. Provoque um crash com curl .../panic e acompanhe kubectl get pods -w até ver o RESTARTS subir sozinho, sem você reiniciar nada. Observe com kubectl describe que o container anterior está em Terminated com código de saída diferente de zero e que não há evento de liveness: quem reiniciou foi o kubelet, pela restartPolicy.
6. Teste a liveness de verdade: troque o caminho da probe para /nao-existe com kubectl patch, espere cerca de 30 segundos e observe o RESTARTS subir (o status pode alternar com CrashLoopBackOff entre uma reinicialização e outra, o que é esperado) e, no describe, os eventos Liveness probe failed: HTTP probe failed with statuscode: 404 e Killing. Restaure com kubectl apply -f deployment.yaml e rode kubectl rollout status deployment/podinfo, esperando a mensagem successfully rolled out antes do passo 7, para que o head -n 1 não escolha um Pod antigo que ainda está terminando. Saiba que esse apply devolve replicas para 3; o HPA reduz de novo para 2 se não houver carga.
7. Desligue a readiness de um Pod com curl -X POST .../readyz/disable e, depois de cerca de 15 segundos, confirme com kubectl get pods (READY 0/1, RESTARTS inalterado) e kubectl get endpoints podinfo que aquele Pod saiu da lista, sem ser reiniciado. Com 2 réplicas sobra 1 IP; com 3, sobram 2.
8. Feche gerando carga como na Etapa 08 (o mesmo gerador busybox contra http://podinfo:9898) e observe o HPA escalar este Deployment sozinho.
9. Limpe: kubectl delete -f configmap.yaml -f deployment.yaml -f service.yaml -f hpa.yaml. Feche o terminal do minikube service com Ctrl+C. Se quiser desligar o laboratório, minikube stop.

Etapa 10 labs online

Pratique de graça em clusters reais

Estas plataformas dão um terminal com Kubernetes real direto no navegador, sem instalar nada. Comece pelas 100% gratuitas e passe para as pagas só quando quiser desafios maiores.

Etapa 11 · revisão

Checklist de autoavaliação

Próximos passos: com todos os itens marcados, repita os exercícios em uma das plataformas listadas na seção anterior, desta vez sem consultar o guia. O tema seguinte é o módulo avançado, onde aparece o StatefulSet citado na Etapa 09.