Artigos

Build único, promoção por digest: um pipeline de entrega com rollback

Um caminho de entrega de referência em que o artefato testado em staging é exatamente o que vai para produção, e um rollback é o redeploy do digest anterior.

Os exemplos são genéricos e ilustrativos. Não vêm do ambiente de nenhum cliente: ajuste limites e configurações ao seu próprio sistema.

O problema de refazer o build por ambiente

Pipelines que refazem o build da aplicação para cada ambiente testam um artefato e publicam outro. Dependências se resolvem de outro jeito, uma imagem base muda, uma flag de build difere — e a versão em produção nunca foi testada em lugar nenhum. Faça o build uma vez, dê ao artefato uma identidade imutável e promova essa identidade.

Caminho de referência

Um caminho genérico do commit à produção. Cada etapa repassa o mesmo artefato ou o barra.

01CommitPull request com revisão e verificações obrigatórias.
02BuildUm build por commit; a imagem é publicada e o seu digest registrado.
03VerificaçãoTestes, varredura de dependências e de imagem, assinatura.
04StagingO digest é implantado; rodam testes de fumaça e de integração.
05ProduçãoO mesmo digest, em rollout progressivo.
06ObservaçãoError budget e alertas decidem: seguir ou fazer rollback.

Digests, não tags

Tags como latest ou v2 são rótulos mutáveis; um digest (sha256:…) é o hash do conteúdo da imagem. Os manifestos de deploy devem referenciar o digest, e o pipeline promove um ambiente alterando esse único valor — de preferência como um commit no repositório de deploy, para que cada release seja uma mudança revisada e reversível.

# build once and record the digest
docker buildx build --push --metadata-file meta.json \
  -t registry.example.com/api:"$GIT_SHA" .
DIGEST=$(jq -r '."containerimage.digest"' meta.json)

# promote: every environment receives the same digest
kustomize edit set image api=registry.example.com/api@"$DIGEST"

Mudanças no banco: expandir, depois contrair

Fazer rollback de código só é fácil se o schema ainda servir à versão anterior. Divida migrações incompatíveis em passos, cada um compatível com o código em execução: adicione a nova coluna ou tabela, publique código que escreve nas duas, faça o backfill, troque as leituras e só em um release posterior remova a estrutura antiga.

Entrega progressiva e rollback

Libere primeiro para uma fração do tráfego ou das réplicas e compare taxa de erro e latência com a versão atual.
Amarre a decisão ao SLO: um burn rate alto durante o rollout interrompe a promoção automaticamente.
Um rollback é o redeploy do digest anterior — o mesmo caminho, já testado — e não um hotfix escrito sob pressão.
Mantenha configuração e segredos fora da imagem, para que o mesmo artefato rode em todos os ambientes.