Docker e Kubernetes: Um Guia Prático para Desenvolvedores Modernos

Todo desenvolvedor eventualmente bate na mesma parede. Você escreve código na sua máquina, funciona perfeitamente, você envia para o staging, e ele explode com um erro críptico sobre uma dependência de sistema faltando ou uma versão de biblioteca diferente. O clássico problema "funciona na minha máquina" assombra o desenvolvimento de software há décadas, e o Docker não apenas o resolveu — tornou a solução tão simples que agora não há desculpa para não usá-lo.

Mas o Docker resolve apenas o problema de empacotamento. Depois de containerizar sua aplicação, você ainda precisa executá-la em produção — potencialmente em múltiplos servidores, com balanceamento de carga, implantações sem downtime, verificações de saúde e recuperação automática. É aí que o Kubernetes entra. E é também aí que a maioria dos desenvolvedores se perde na complexidade, porque o Kubernetes introduz um vocabulário inteiramente novo de abstrações que leva tempo para internalizar.

Este guia corta o ruído. Ele cobre o que os containers realmente são por baixo dos panos, como escrever Dockerfiles que são eficientes e seguros, os conceitos de Kubernetes que você precisa conhecer para implantar aplicações reais, os tradeoffs entre Docker Compose e Kubernetes para desenvolvimento local, e — mais importante — quando você deve usar cada ferramenta e quando deve deixá-la de lado.

O que os containers realmente são

Um container não é uma máquina virtual leve. Este é o equívoco mais comum, e leva a modelos mentais incorretos. Uma máquina virtual executa um sistema operacional convidado completo sobre um hypervisor, com seu próprio kernel, sua própria alocação de memória e seus próprios drivers de dispositivo. Um container compartilha o kernel do host e executa como um processo de userspace isolado. O isolamento é fornecido por recursos do kernel Linux — namespaces para isolamento de processo, cgroups para limites de recursos e sistemas de arquivos overlay para camadas de imagem eficientes.

Essa distinção importa porque explica o comportamento que você observará. Containers iniciam em milissegundos porque não há kernel para inicializar. Usam menos memória porque não há kernel duplicado e nem processos de sistema redundantes. Mas também significa que um container rodando em Linux não pode rodar uma versão de kernel diferente do host, e um container Windows requer um host Windows (ou uma VM Linux Hyper-V em versões mais antigas). No macOS, o Docker Desktop executa containers Linux dentro de uma VM leve precisamente por esta razão.

Uma imagem é o template somente leitura — um snapshot de um sistema de arquivos mais metadados. Um container é uma instância em execução dessa imagem, com uma camada gravável no topo. Você pode construir uma imagem uma vez e executar dezenas de containers a partir dela. Esta é a unidade fundamental de operação no mundo Docker, e entendê-la claramente torna todo o resto mais fácil.

Boas práticas de Dockerfile

Um Dockerfile é uma receita para construir uma imagem. Cada instrução cria uma nova camada, e as camadas são armazenadas em cache. Isso significa que a ordem das instruções afeta diretamente a velocidade de build, o tamanho da imagem e a segurança. Aqui estão os princípios que mais importam em projetos reais.

Ordene camadas por frequência de mudança

O Docker armazena cada camada em cache após ser construída. Se uma camada não mudou desde o último build, o Docker reusa a versão em cache. Isso significa que você deve colocar instruções que mudam raramente no topo e instruções que mudam frequentemente no final. Dependências de sistema (apt-get, apk add) quase nunca mudam. Dependências da aplicação (npm install, pip install) mudam quando você atualiza seu lockfile. O código fonte da aplicação muda a cada commit.

# Bad: source code before dependencies
FROM node:20-alpine
WORKDIR /app
COPY . .                 # busts the cache for everything below
RUN npm ci                # runs on every build, even if package.json did not change
EXPOSE 3000
CMD ["node", "dist/index.js"]

# Good: stable-first layer ordering
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci                # cached unless package.json changes
COPY . .                  # only the source changes bust this layer
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/index.js"]

A diferença é dramática. O Dockerfile ruim reconstrói todas as dependências a cada commit. O bom reconstrói dependências apenas quando o lockfile muda, o que é tipicamente uma vez por pull request em vez de a cada commit. Em um projeto Node.js com 500 dependências, isso pode economizar dois minutos por build.

Builds multi-estágio

Builds multi-estágio permitem usar um único Dockerfile para construir sua aplicação e produzir uma imagem de runtime mínima. O estágio de build contém compiladores, dependências de desenvolvimento e ferramentas de build. O estágio de runtime copia apenas a saída compilada. Isso mantém as imagens de produção pequenas e reduz a superfície de ataque.

# Build stage
FROM node:20-alpine AS builder
WORKDIR /build
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runtime stage — starts from a fresh, minimal base
FROM node:20-alpine AS runner
WORKDIR /app

# Only what is needed to run
COPY --from=builder /build/dist ./dist
COPY --from=builder /build/package.json ./
COPY --from=builder /build/node_modules ./node_modules

EXPOSE 3000
USER node
CMD ["node", "dist/index.js"]

O estágio de runtime não inclui o compilador TypeScript, os arquivos fonte ou quaisquer dependências de desenvolvimento. Para uma aplicação típica, isso reduz a imagem de 800 MB para menos de 200 MB. A sintaxe COPY --from=builder é o insight chave — ela puxa arquivos de um estágio anterior sem carregar as camadas desse estágio.

Execute como um usuário não-root

Containers são executados como root por padrão. Isso é um risco de segurança: se um atacante explorar sua aplicação, ele tem acesso root dentro do container. A correção é uma única linha em seu Dockerfile que muda para um usuário não-root. A maioria das imagens base vem com um usuário node ou nobody para este propósito.

Além da segurança, builds multi-estágio e ordenação adequada de camadas também melhoram a velocidade do pipeline CI/CD. Cada minuto economizado em um build de imagem é um minuto que seus desenvolvedores não estão esperando por uma implantação. Em uma equipe de dez desenvolvedores implantando cinco vezes ao dia, economizar dois minutos por build recupera mais de sessenta horas de tempo de desenvolvedor por ano.

Fundamentos de Kubernetes

Kubernetes é um orquestrador de containers. Ele pega um cluster de máquinas (nós), agenda containers nelas, os mantém em execução, lida com rede e fornece uma API declarativa para descrever o estado desejado do seu sistema. Você diz ao Kubernetes o que quer — três réplicas do seu servidor de API, porta 8080 exposta, estratégia de atualização contínua — e ele faz acontecer.

A curva de aprendizado é real porque o Kubernetes introduz um conjunto estratificado de abstrações. As três com as quais você mais interagirá são Pods, Deployments e Services.

Pods

Um Pod é a menor unidade implantável no Kubernetes. Representa um ou mais containers que compartilham um namespace de rede e volumes de armazenamento. Na prática, a maioria dos Pods executa um único container. Padrões de sidecar (um container principal mais um container de log ou proxy) usam Pods com múltiplos containers, mas para implantação de aplicação do dia a dia, você usará um container por Pod.

Você raramente cria Pods diretamente. Pods são efêmeros — podem ser terminados e reagendados a qualquer momento. Se você criar um Pod manualmente e o nó em que ele está executando falhar, o Pod se foi para sempre. É aqui que os Deployments entram.

Deployments

Um Deployment gerencia um conjunto de Pods idênticos (um ReplicaSet). Ele lida com atualizações contínuas, escalonamento, auto-cura e rollbacks. Este é o recurso que você usará para implantar aplicações stateless.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  labels:
    app: api-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: api-server
  template:
    metadata:
      labels:
        app: api-server
    spec:
      containers:
        - name: api
          image: myregistry/api-server:v1.2.3
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: 250m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: 3000
          readinessProbe:
            httpGet:
              path: /ready
              port: 3000

Este Deployment declara três réplicas do servidor de API. O Kubernetes garantirá que três Pods estejam sempre em execução. Se um Pod falhar, o Kubernetes cria um substituto. Durante uma atualização contínua (alterando a tag da imagem), o Kubernetes substitui Pods um por um, garantindo zero downtime. A sonda de verificação de vida (liveness probe) diz ao Kubernetes quando um Pod está saudável; a sonda de prontidão (readiness probe) diz quando um Pod está pronto para receber tráfego.

Services

Pods têm endereços IP dinâmicos. Toda vez que um Pod é recriado, ele recebe um novo IP. Um Service fornece um endpoint de rede estável que balanceia o tráfego entre os Pods que correspondem ao seu seletor. É assim que outras partes do seu sistema encontram e se comunicam com sua aplicação.

apiVersion: v1
kind: Service
metadata:
  name: api-server
spec:
  selector:
    app: api-server
  ports:
    - port: 80
      targetPort: 3000
  type: ClusterIP

Este Service mapeia a porta 80 em um IP estável interno do cluster para a porta 3000 em Pods com o rótulo app: api-server. Outros serviços dentro do cluster podem alcançá-lo pelo nome DNS api-server. Para tráfego externo, você usaria um recurso LoadBalancer ou Ingress sobre o Service.

Kubernetes não é uma plataforma na qual você implanta. É uma plataforma para a qual você descreve sua implantação. A diferença entre imperativo e declarativo é a mudança mental mais importante que você pode fazer.

Desenvolvimento local: Docker Compose vs Kubernetes

O maior erro que as equipes cometem é assumir que precisam do Kubernetes para desenvolvimento local porque o usam em produção. Docker Compose e Kubernetes servem propósitos diferentes, e escolher o errado para trabalho local cria atrito desnecessário.

Docker Compose é projetado para desenvolvimento local. Ele roda em uma única máquina, inicia containers em segundos e tem um formato YAML simples que mapeia diretamente para o que você precisa: um servidor web, um banco de dados, uma instância Redis e talvez um worker de fila. Você define os serviços, e docker compose up traz tudo online, com logs transmitidos para seu terminal, portas mapeadas para localhost e hot reload funcionando de fábrica.

version: "3.8"
services:
  api:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/app
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Este arquivo Compose fornece um ambiente de desenvolvimento funcional com hot reload, um banco de dados local com armazenamento persistente e rede adequada entre os serviços. Leva cerca de trinta linhas de YAML e inicia em menos de dez segundos.

Minikube, Kind e k3s podem executar Kubernetes localmente, mas adicionam sobrecarga significativa. Eles exigem mais memória, demoram mais para iniciar e introduzem complexidade (controladores de ingress, malhas de serviço, classes de armazenamento) que você simplesmente não precisa quando está iterando em uma única funcionalidade. Executar Kubernetes localmente é útil para testar comportamentos específicos do Kubernetes — como políticas de expulsão de pods, auto-escalonamento horizontal de pods ou definições de recursos personalizados — mas não é um substituto para o Compose no desenvolvimento do dia a dia.

• Use Docker Compose para desenvolvimento local. É rápido, simples e mapeia diretamente para os containers que você executa.
• Use Kubernetes (via Minikube ou Kind) para testes de integração quando sua infraestrutura de produção usar recursos do Kubernetes como ConfigMaps, Secrets ou controladores personalizados.
• Use um cluster de desenvolvimento remoto apenas quando precisar de acesso a GPU, hardware especializado ou um ambiente de staging compartilhado que espelhe a produção exatamente.
• Não execute dois clusters Kubernetes localmente só porque você tem dois ambientes. O Compose lida com isso com uma única flag --profile.
• Se sua equipe passa mais tempo depurando configurações do Kubernetes do que escrevendo código de aplicação, você ultrapassou seus faróis. Recue para o Compose e adicione complexidade apenas quando a dor de não tê-la exceder a dor de mantê-la.

Armadilhas comuns e como evitá-las

Mesmo depois de entender os conceitos, certos erros se repetem entre as equipes. Aqui estão os que valem a pena memorizar para que você possa pular as sessões de depuração de dois dias.

O caos de tags de imagem é o problema de produção mais comum. Usar latest como sua tag de imagem em um Deployment do Kubernetes significa que você não pode dizer qual versão está rodando em qualquer nó. O Kubernetes só puxa uma imagem se ela não estiver presente no nó, então latest em um nó pode ser uma versão diferente de latest em outro. Sempre use tags de versão semântica ou SHAs de commit. Melhor ainda, use um digest de imagem totalmente qualificado — é a única coisa garantida de ser imutável.

Requests e limits de recursos são frequentemente omitidos ou definidos arbitrariamente. Se você não definir requests, o Kubernetes não pode agendar seus Pods inteligentemente, e os nós ficam sobrecarregados. Se você não definir limits, um vazamento de memória em um Pod pode derrubar outros Pods no mesmo nó. Defina ambos, e use ferramentas como o Vertical Pod Autoscaler em modo de recomendação para ajustá-los com base no uso real.

ConfigMaps e Secrets são montados como variáveis de ambiente ou arquivos. Variáveis de ambiente são convenientes, mas qualquer alteração requer reinicialização do Pod para fazer efeito. Montagens baseadas em arquivo podem ser atualizadas sem reinicialização (o Pod lê o novo conteúdo quando o arquivo é acessado), mas muitas aplicações armazenam configuração em cache na inicialização. Saiba qual padrão sua aplicação usa e projete sua abordagem de configuração de acordo.

Volumes persistentes no Kubernetes não são mágicos. Um PersistentVolumeClaim solicita armazenamento, mas a classe de armazenamento subjacente deve ser configurada para seu provedor de nuvem. Classes de armazenamento padrão podem usar armazenamento conectado à rede que tem características de desempenho diferentes de SSDs locais. Se o desempenho do seu banco de dados for importante, compare sua classe de armazenamento antes de ir para produção.

Registro e depuração no Kubernetes é mais difícil do que em um único servidor. Pods são efêmeros, então logs desaparecem quando um Pod é deletado. Use kubectl logs --tail=50 -f nome-do-pod para acompanhamento ao vivo, mas para depuração em produção, você precisa de uma solução de log centralizada (Loki, Elasticsearch ou um serviço de log em nuvem). Similarmente, execute dentro de um Pod com kubectl exec -it nome-do-pod -- sh para inspecionar um container em execução, mas lembre-se que qualquer alteração feita dentro de um container em execução é perdida na reinicialização.

Você realmente precisa do Kubernetes?

Esta é a pergunta que ninguém quer fazer porque o Kubernetes fica bem no currículo de engenharia e sinaliza maturidade operacional. Mas o Kubernetes é uma solução para um problema específico: executar múltiplos serviços containerizados em múltiplas máquinas com recuperação automática, escalonamento e implantações contínuas. Se você tem um ou dois serviços rodando em um único servidor, o Kubernetes é exagero.

Aqui está um framework de decisão direto. Se você está implantando uma única aplicação que serve menos de dez mil requisições por segundo, um único servidor com Docker Compose em produção (sim, Compose funciona bem em produção para muitas cargas de trabalho) lhe atenderá bem. Adicione um proxy reverso como Caddy ou Nginx, configure backups automatizados, e você tem um sistema de produção que um único desenvolvedor pode entender e manter em sua totalidade.

Migre para o Kubernetes quando você tiver múltiplos serviços que precisam ser implantados independentemente, quando precisar de escalonamento por serviço (sua API precisa de dez réplicas mas seu worker precisa de apenas duas), quando precisar de implantações sem downtime como operação rotineira, ou quando sua equipe tiver pelo menos uma pessoa cuja responsabilidade principal seja infraestrutura. Antes dessas condições serem atendidas, o custo operacional do Kubernetes — tanto no gerenciamento do cluster quanto na carga cognitiva do desenvolvedor — é um negativo líquido.

Muitas equipes se beneficiam de um meio-termo. Use Docker Compose para desenvolvimento local e uma plataforma de containers gerenciada como AWS App Runner, Google Cloud Run ou Fly.io para produção. Essas plataformas oferecem implantação de containers, HTTPS automático e escalonamento sem exigir que você gerencie um plano de controle Kubernetes. Você obtém a maioria dos benefícios da containerização com nenhuma da curva de aprendizado do Kubernetes.

A melhor estratégia de infraestrutura é aquela que permite que sua equipe entregue funcionalidades. Docker e Kubernetes são ferramentas, não identidades. Use-os quando ajudarem, e pule-os quando não ajudarem.