Rollout de NODE_OPTIONS com ipv4first em frota Node: validação e rollback com Semaphore

Uma variável de ambiente parece uma mudança pequena até precisar ser aplicada em uma frota inteira.

Neste caso, uma execução real via Semaphore/Ansible propagou:

1
NODE_OPTIONS=--dns-result-order=ipv4first

O ponto mais interessante não é a flag. É o que aconteceu depois de aplicá-la: a automação verificou os serviços, executou testes repetidos e fez rollback nos hosts que não passaram na validação.

E a evidência também impõe um limite importante: ela não prova que IPv6 era a causa raiz do incidente original e não menciona Redis. Uma correção funcionar não autoriza reescrever o passado.

O que a execução real comprova #

O log do Task Runner mostra um play explicitamente voltado a aplicar NODE_OPTIONS com validação e rollback em uma frota ampla.

Nos hosts que concluíram a mudança, a validação registrou processos Node com ipv4first ativo. Em exemplos da própria execução, os serviços de API e webhooks responderam com HTTP 200 e uma série de dez testes terminou sem falha.

O estado observado incluía, entre outros parâmetros:

1
NODE_OPTIONS=--dns-result-order=ipv4first

Em parte da aplicação também havia configuração relacionada à seleção automática de família de rede.

Isso sustenta:

1
2
3
4
FACT
→ a configuração foi aplicada em processos Node
→ houve validação funcional depois da mudança
→ houve testes repetidos, não apenas um único request

Não sustenta:

1
2
HYPOTHESIS
→ IPv6 foi a causa raiz do problema anterior

Essa distinção é importante porque o log recuperado documenta muito bem o rollout, mas não reconstrói sozinho a falha que motivou a mudança.

A automação não tratou “container subiu” como sucesso #

Um rollout frágil poderia terminar assim:

1
2
3
4
editar variável
→ recriar container
→ processo está running
→ sucesso

O play fez mais.

A validação observou a aplicação depois da alteração e verificou endpoints de API e webhooks. Também executou uma pequena série de requisições para confirmar comportamento consistente.

A diferença é operacionalmente grande:

1
RUNNING != VALIDADO

Um container pode estar em execução e a aplicação continuar incapaz de atender o caminho que motivou a mudança.

O rollback aconteceu de verdade #

Dois hosts não passaram na validação.

Em vez de considerar o lote inteiro verde ou deixar os hosts em estado intermediário, o play entrou no caminho de rollback. O log registra:

1
2
3
4
5
falha na validação
→ restaurar .env
→ restaurar .providers.env
→ recriar containers
→ validar novamente API e webhooks

Depois disso, a automação ainda manteve a falha visível quando o host não voltou aos critérios esperados.

Esse comportamento é um guardrail importante: rollback não serve para esconder falha; serve para tentar retornar ao estado anterior e deixar o resultado explícito.

A frota real também tinha hosts inacessíveis #

A etapa inicial de coleta encontrou alvos que não estavam alcançáveis por SSH.

Isso também é evidência útil. Em operação de frota, “aplicar em todos” raramente significa que todos os alvos estão disponíveis ao mesmo tempo.

Uma execução segura precisa separar pelo menos:

1
2
3
4
aplicado e validado
aplicado e rollback executado
unreachable antes da mudança
falha após rollback

Misturar tudo em uma única mensagem de “sucesso” cria uma visão falsa da mudança.

Por que `ipv4first` não significa “IPv6 estava quebrado” #

O ajuste influencia a ordem de resultados de DNS usada pelo runtime Node.

Ele pode ser útil quando existe diferença de comportamento entre caminhos IPv4 e IPv6, mas isso não transforma automaticamente a hipótese abaixo em fato:

1
IPv6 causou o timeout

Para afirmar causalidade seria necessário recuperar evidência anterior à mudança, por exemplo:

1
2
3
4
resolução DNS antes do ajuste
endereço/família efetivamente escolhido
falha de conexão naquele caminho
comparação reproduzível com o caminho alternativo

Essa fonte não contém essa cadeia completa.

Por isso o case público fica no que é comprovável: como uma mudança de runtime foi propagada, validada e revertida de forma controlada.

Um modelo melhor para rollout em frota #

O fluxo observado pode ser generalizado assim:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
inventário
→ verificar pré-requisitos
→ preservar estado anterior
→ aplicar configuração
→ recriar/reiniciar somente o necessário
→ validar processo
→ validar aplicação
→ repetir testes
→ rollback se falhar
→ repetir validação após rollback
→ PLAY RECAP por host

Esse desenho é mais importante que a flag usada neste caso.

O mesmo padrão vale para mudanças como:

variáveis de runtime;
parâmetros de proxy;
configurações de conexão;
feature flags operacionais;
ajustes de JVM/Node/PHP;
troca de endpoint ou resolver.

Configurado, validado e resolvido são estados diferentes #

Eu separo três estados:

1
2
3
4
5
6
7
8
CONFIGURADO
A variável desejada chegou ao processo.

VALIDADO
A aplicação passou nos testes definidos depois da mudança.

RESOLVIDO
O sintoma original deixou de ocorrer por uma janela suficiente, sem regressão relevante.

A execução recuperada comprova muito bem os dois primeiros para diversos alvos.

Ela não é suficiente, isoladamente, para provar toda a história causal do incidente original nem estabilidade indefinida depois do rollout.

O que eu exigiria antes de repetir uma mudança desse tipo #

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
[ ] target explícito
[ ] estado anterior preservado
[ ] variável/configuração desejada declarada
[ ] restart/recreate controlado
[ ] health da aplicação
[ ] teste do caminho funcional relevante
[ ] repetição suficiente para detectar intermitência
[ ] rollback definido antes da expansão
[ ] validação depois do rollback
[ ] resultado por host
[ ] unreachable separado de failed
[ ] PLAY RECAP preservado como evidência

O principal aprendizado #

A parte forte desse case não é:

“adicione ipv4first que resolve”.

É outra:

uma correção de configuração só vira operação segura quando a automação consegue provar onde ela funcionou, onde não funcionou e como voltar.

O log real mostra exatamente isso: aplicação em escala, validação funcional, falhas reais e rollback real — sem precisar inventar uma causa raiz que a fonte não demonstra.

Leitura relacionada #

Este rollout é um exemplo concreto do modelo operacional descrito no case Ansible Semaphore em frota ampla: guard-rails para não rodar no alvo errado.