Saúde e Prontidão

Endpoints de saúde informam aos orquestradores se um processo Python está ativo (liveness) e se pode aceitar tráfego (readiness). Separe-os para que falhas de dependência drenem o tráfego sem reiniciar pods.

Receita

from fastapi import FastAPI, Response, status
 
app = FastAPI()
 
@app.get("/health/live")
def live():
    return {"status": "ok"}
 
@app.get("/health/ready")
def ready():
    if not db_ping():
        return Response(content='{"status":"down"}', status_code=503, media_type="application/json")
    return {"status": "ok"}

Quando usar isso:

• Verificações de saúde de balanceadores de carga Kubernetes/ECS
• Implantações Rolling deploys direcionam tráfego apenas para pods prontos
• Falhas de dependência removem a instância da rotação temporariamente
• Monitoramento sintético verificações externas de uptime (geralmente apenas /health/live público)

Exemplo de Trabalho

Prontidão do FastAPI com verificação de banco de dados com limite de tempo e inicialização lenta amigável à sonda de inicialização.

import asyncio
from contextlib import asynccontextmanager
 
from fastapi import FastAPI, Response, status
 
class HealthState:
    def __init__(self) -> None:
        self.db_ready = False
 
    async def check_db(self) -> bool:
        try:
            await asyncio.wait_for(fake_db_ping(), timeout=0.5)
            self.db_ready = True
            return True
        except Exception:
            self.db_ready = False
            return False
 
async def fake_db_ping() -> None:
    await asyncio.sleep(0.01)
 
state = HealthState()
 
@asynccontextmanager
async def lifespan(app: FastAPI):
    await state.check_db()
    yield
 
app = FastAPI(lifespan=lifespan)
 
@app.get("/health/live")
async def live():
    return {"status": "ok"}
 
@app.get("/health/ready")
async def ready():
    ok = await state.check_db()
    body = {"status": "ok" if ok else "degraded", "db": ok}
    if not ok:
        return Response(content=str(body), status_code=status.HTTP_503_SERVICE_UNAVAILABLE)
    return body

O que isso demonstra:

• Liveness sempre 200 se o loop de eventos estiver em execução
• Readiness retorna 503 quando a verificação do banco de dados falha - o LB para de rotear
• Tempo limite curto na verificação de dependência evita sondas travadas

Mergulho Profundo

Mapeamento de Sondas

Escopo da Verificação

• Readiness: pool de banco de dados, cache, flags de recursos necessários carregados
• Liveness: evite chamadas externas - o reinício do kubelet é caro

Notas Python

startupProbe:
  httpGet:
    path: /health/ready
    port: 8000
  failureThreshold: 30
  periodSeconds: 10

Armadilhas

• Verificação de DB na liveness - a interrupção do DB mata todos os pods. Correção: readiness apenas para dependências.
• Readiness lenta sempre - a implantação nunca termina. Correção: startupProbe para inicialização lenta, readiness rápida depois.
• Flutuação da Readiness - efeito "thundering herd" na recuperação do DB. Correção: histerese ou resultado de verificação em cache curto (TTL de 1-2s).
• Readiness pública expõe internos - vazamento de informações {"db": false}. Correção: corpo genérico externamente, detalhes em logs/métricas.
• Saúde na porta errada - a sonda atinge a porta de métricas. Correção: documente a porta 8000 do aplicativo no Deployment.

Alternativas

FAQs

Relacionado

• Noções Básicas de Implantação - introdução à saúde
• Kubernetes para Aplicativos Python - YAML de sonda
• Implantações Zero-Downtime - comportamento de drenagem
• Métricas - contadores de falha de sonda
• Melhores Práticas de Observabilidade - lista de verificação de sonda

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.