Upgrade e rollback

Publicar uma versão nova não é aplicar um helm upgrade: é instalar uma release nova. Isso muda o que você precisa saber sobre upgrade — e simplifica muito o rollback.

Upgrade: uma release nova por versão

O Module Manager instala release nova por versão; ele não faz upgrade no lugar. Consequências:

• Não existe "atualizar o chart do mesmo release": a versão nova é um pacote novo, com chart novo.
• A release que está no ar continua servindo até a nova estar ativa. Qualquer falha até a ativação deixa a release ativa intocada.
• O caminho normal é: upload → plan → deploy. Cada passo é uma operação do Module Manager, com estado e idempotência próprios.

./nnconsolew modules upload dist/<módulo>-<versão>.nnp
./nnconsolew modules plan <id> <release>
./nnconsolew modules deploy <id> <release>
./nnconsolew modules wait <id> <release>

O plan é leitura pura e mostra cada recurso (will_create, exists_ok, conflict, denied, unknown) e cada blocker com owner e remediation. READY é pré-requisito do deploy; na Console, o botão só habilita com "Pronto para implantar". Um blocker do estado da plataforma deixa a release validada e o plano bloqueado — quando ele é resolvido, não é preciso reenviar o pacote.

Recursos de MÓDULO × de RELEASE

Esta é a distinção que explica o resto:

são do MÓDULO (nascem no 1º deploy, não se tocam depois)	são da RELEASE (trocam a cada versão)
namespace, banco, principais, segredos de bootstrap, labels de grant	Helm, política de rede da release, identidade, rotas, IAM ativo, Audit, probe, docs/help, NNC

Rollback, disable e enable não tocam nos recursos de módulo. O banco de um módulo nunca é recriado por causa de uma troca de versão — é por isso que as migrations são expand-only.

A versão nova convive com a anterior

Durante o deploy, a plataforma precisa de capacidade para N + N-1 + a nova. Se faltar, o resultado é BLOCKED_CAPACITY — a plataforma resolve, você não cria nó.

Quando algo dá errado no meio

O deploy registra fases (PENDING, PREFLIGHT, PROVISIONING, MIGRATING, DEPLOYING, REGISTERING, ACTIVATING, ACTIVE). FAILED_RECONCILABLE significa repetir o deploy retoma do checkpoint — a operação é idempotente. Repita o deploy antes de procurar outra causa.

rollback ou disable durante um deploy longo preempta o deploy: ele é gravado como preempto, responde 202, e o deploy aborta em até 2 segundos com conflict/preempted_by_recovery, desfazendo o que tinha sido preparado. A recuperação tem prioridade.

Rollback: N → N-1

O rollback aponta sempre para a release anterior inteira, e é acoplado: voltam juntos todas as surfaces, o NNS, os contratos, o Status Probe, docs e help. Não existe rollback só do frontend nem só do serviço.

./nnconsolew modules rollback <id> --to <release-anterior>

Antes de mexer em qualquer coisa, o Module Manager reconfere a compatibilidade da release alvo com a Console atual. Incompatível = recusa, e nenhuma geração é alterada.

Depois disso é só a ativação, e ela é rápida por desenho: nunca espera o Status nem o build de docs. O probe da N-1 recebe réplica depois, quando a prova dele está atual; se a variante de docs não está pronta, fica PENDING e a reconciliação resolve.

As duas guardas

recusa	quando
rollback_crosses_sdk_line	a N-1 é de outra linha do SDK
rollback_audience_changed	um item presente nas duas releases (rota, página de docs, tópico de help, componente de status, trilha) muda de audience

A N-1 só é servida (arquivos e help) se for da mesma linha do SDK e tiver a mesma surface. Por isso a primeira release de um módulo numa linha não tem N-1: o tests/conformance.yaml declara

release: {previous: none, previous_reason: no_same_line_previous}

e os itens rollback.* da conformance saem not_applicable. A partir da segunda release, o rollback acoplado volta a valer.

Rollback para uma release aposentada

A N-2 é aposentada (desinstalada) quando a N fica ativa. Voltar para ela não é um rollback: é um deploy completo do pacote guardado, com todas as fases.

disable e enable

./nnconsolew modules disable <id>
./nnconsolew modules enable <id>

disable deixa as rotas em 503 not_ready/service_disabled, tira as surfaces das duas Consoles e faz scale 0 do NNS e de todos os probes; o módulo sai da avaliação do Status e da página pública. Nada é apagado — os recursos de módulo continuam no lugar.

enable reverte com o gate e a prova de rede atuais antes do scale, e reconfere a compatibilidade com a Console. Não há caminho que pule essa conferência.

O deploy de uma release nova é permitido com o módulo DISABLED: ela fica pronta e só serve no enable.

O que não volta no rollback

• O banco: as migrations da versão que entrou não são revertidas. É exatamente por isso que elas são expand-only e precisam ser compatíveis com a N-1 — a N-1 vai ler o schema da N.
• Os recursos de módulo: namespace, contas, segredos e labels de grant ficam.
• A release aposentada: voltar para ela é deploy completo.

Nunca

• Tag latest ou imagem sem digest.
• helm install, kubectl apply ou cópia de JS à mão.
• Assinar com a chave de produção fora do operador.
• Apagar release: use disable. A N-2 quem aposenta é o Module Manager.

Onde conferir

./nnconsolew modules show <id> <release>     # estado, fases e último resultado
./nnconsolew conformance validate --dir .    # as expectativas, incluindo release.previous