Argo CD ignora hooks de migração em self-heal e causa inconsistência de schema
Aprofundamento CEVIU
Aprofundamento
Um incidente recente com o Argo CD, ferramenta popular de GitOps, expôs uma falha crítica em seu mecanismo de self-heal para aplicações que utilizam hooks de migração de banco de dados. O problema ocorre quando um novo release é implantado enquanto uma janela de sincronização (sync window) está configurada para impedir atualizações. Ao reabrir a janela, o self-heal do Argo CD pode interpretar a nova versão no repositório Git como um mero 'drift' (desvio de estado) a ser corrigido, em vez de um deploy completo. Nesse cenário, o self-heal aplica as mudanças, mas ignora a execução dos hooks de migração de banco de dados, deixando a aplicação com um esquema desatualizado. A interface do usuário do Argo CD, enganosamente, reporta o estado da aplicação como 'Synced' e 'Healthy', mascarando a falha.
A causa raiz é uma condição de corrida entre dois tipos de refresh: nível 1 (acionado por mudanças em objetos gerenciados) e nível 2 (acionado por temporizador, comparando com o Git). Se o refresh de nível 1 for o primeiro a ser acionado após o fechamento da janela de sincronização, ele confunde a revisão desejada com a última sincronizada, levando o Argo CD a acreditar que a revisão já foi aplicada. Com o self-heal ativado, ele opta por uma sincronização parcial que não executa hooks, resultando em bancos de dados sem as migrações necessárias. Para contornar, recomenda-se integrar a migração como parte do estado desejado no Git (usando Jobs com sync waves e nomes únicos por release) ou desativar o self-heal para aplicações que dependem de migrações via hooks, permitindo que o refresh por temporizador (nível 2) execute uma sincronização completa.
Por que isso importa
Para engenheiros DevOps e de plataforma, este incidente no Argo CD sublinha a importância de não confiar cegamente no status 'Synced' e 'Healthy' da UI, especialmente em cenários com janelas de sincronização e hooks. A falha pode levar a inconsistências críticas de schema em produção, resultando em tempo de inatividade ou comportamento inesperado da aplicação. A lição é que a automação, por mais robusta que pareça, pode ter nuances que exigem validação e estratégias de mitigação. A recomendação de tratar migrações como parte do estado desejado no Git, em vez de um efeito colateral de hooks, reforça o princípio de infraestrutura como código e garante que a migração seja aplicada independentemente do caminho de sincronização. Desativar o self-heal é uma alternativa, mas implica em abrir mão da correção automática de desvios, o que pode ser um trade-off dependendo da criticidade da aplicação.
Linha do tempo
Argo CD ignora hooks de migração em self-heal e causa inconsistência de schema
Perguntas frequentes
O que causou a falha do Argo CD em executar os hooks de migração?
A falha foi causada por uma condição de corrida. Quando uma janela de sincronização é reaberta, se um refresh de nível 1 (acionado por mudança de objeto) ocorrer antes de um refresh de nível 2 (acionado por temporizador), o Argo CD interpreta a nova versão como 'drift' e executa uma sincronização parcial, que ignora os hooks de migração.
Como posso verificar se minha aplicação foi afetada por este problema?
Mesmo que a UI do Argo CD mostre 'Synced' e 'Healthy', verifique os logs do controlador. Operações afetadas listarão um número específico de recursos e uma contagem de tentativa de self-heal. Mais importante, valide diretamente se as migrações de banco de dados foram realmente aplicadas na sua base de dados.
Qual a solução recomendada para garantir que as migrações de banco de dados sejam executadas?
A principal recomendação é remover as anotações de hook e integrar a migração como um Job comum no seu manifesto, usando sync waves e um nome único por release. Assim, a migração se torna um recurso gerenciado pelo Argo CD e é aplicada em qualquer tipo de sincronização. Como alternativa temporária, pode-se desativar o self-heal para aplicações que dependem de hooks.
Fontes
- cncf.iofonte original
- Categoria
- CEVIU DevOps
- Publicado
- 20 de novembro de 2026
- Editoria
- CEVIU DevOps
