Como os health checks do Docker funcionam e por que são importantes?

Question

Accepted Answer

Um **health check** diz ao Docker (ou a um orquestrador) como determinar se a aplicação de um container está realmente **funcionando**, não apenas em execução. O processo de um container pode estar ativo enquanto a aplicação está quebrada (travada, não consegue alcançar seu banco de dados) — health checks detectam isso para que a plataforma possa reagir.

## Definindo um health check

```dockerfile
# in a Dockerfile
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
# → Docker runs this command periodically; exit 0 = healthy, non-zero = unhealthy
```

```yaml
# in docker-compose.yml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 3s
  retries: 3
  start_period: 10s    # grace period on startup before failures count
```

Docker executa periodicamente o comando do health check; o status do container se torna `healthy` ou `unhealthy` com base no resultado (visível em `docker ps`).

## Executando vs saudável (a distinção chave)

```text
RUNNING → the container's process is alive (but the APP might be hung/broken)
HEALTHY → the health check confirms the app actually WORKS (responds correctly)
→ A container can be RUNNING but NOT HEALTHY (e.g. the app deadlocked, lost its DB).
  Without a health check, the platform only knows "running" — and keeps sending traffic
  to a broken container.
```

## Por que health checks importam operacionalmente

```text
✓ ORCHESTRATORS use them: restart unhealthy containers; route traffic only to healthy ones
✓ Compose depends_on: condition: service_healthy → wait for real readiness
✓ LIVENESS (is it alive? restart if not) vs READINESS (ready for traffic? hold traffic if not)
  → Kubernetes uses liveness + readiness probes (the same concept, more granular)
✓ Prevents serving requests from broken-but-running containers
```

## Por que isso importa

Compreender os health checks do Docker é importante para **executar aplicações containerizadas confiáveis**, portanto é um conhecimento operacional valioso.

A insight crucial é a distinção entre **executando e saudável**: o processo de um container pode estar **vivo enquanto a aplicação está realmente quebrada** (travada, deadlock, incapaz de alcançar seu banco de dados) — e sem um health check, a plataforma apenas sabe que o container está "executando" e continuará **roteando tráfego para um container quebrado**, causando falhas.

Os health checks resolvem isso definindo como verificar se a aplicação **realmente funciona** (ex: acessando um endpoint `/health`), então o status do container reflete saúde real, não apenas vitalidade do processo.

Isso importa **operacionalmente** porque orquestradores e ferramentas atuam sobre isso: eles **reiniciam containers não saudáveis** (recuperação automática de travamentos/deadlocks) e **rotear tráfego apenas para os saudáveis** (evitando enviar requisições para instâncias quebradas), e a opção `depends_on: condition: service_healthy` do Compose usa health checks para aguardar disponibilidade genuína (resolvendo race conditions de inicialização).

Compreender a distinção relacionada **liveness vs readiness** (está vivo e deve ser reiniciado, vs está pronto para receber tráfego) é importante, pois o **Kubernetes usa liveness e readiness probes** construídos sobre esse mesmo conceito — portanto, compreender os health checks do Docker se transfere diretamente para ambientes orquestrados.

Como a operação confiável requer distinguir "executando" de "realmente funcionando" e reagir a containers quebrados mas em execução (reiniciá-los, reter tráfego), e como os health checks são o mecanismo que possibilita isso — usado por orquestradores para auto-recuperação e roteamento de tráfego — compreender os health checks do Docker é um conhecimento valioso e praticamente importante para executar containers confiávelmente, uma prática chave para resiliência em produção que previne o problema comum de containers quebrados continuarem a receber tráfego silenciosamente, e um conceito fundamental para como orquestradores mantêm a saúde das aplicações.