Skip to main content

Publicação

Quando usar: quando o pacote está assinado e as imagens estão no registry. Daqui para frente, tudo é operação pela ferramenta do módulo contra a Public API — e depende de um principal de plataforma com as permissões de release.

Permissões necessárias: modules.release.upload, modules.release.deploy, modules.release.rollback, modules.module.disable, modules.module.read (papel nnc:modules:release-manager).

export NN_API_URL=https://api.nnumbers.com.br

1. Upload​

./nnconsolew modules upload dist/sample-0.1.0.signed.nnp --api "$NN_API_URL"

O upload valida o pacote de novo (agora contra o ambiente: imagem existe no registry? rede declarada casa com o catálogo do destino? slots de segredo declarados?), provisiona o que a release precisa e deixa a release em VALIDATED. A Idempotency-Key é gerada e impressa no stderr: repetir com a mesma chave é seguro.

Imagem ausente no registry: image_not_found. Pacote sem assinatura válida para o ambiente: release_invalid — a política de assinatura é do ambiente, não do módulo.

2. Ler o Report​

./nnconsolew modules show sample sample@0.1.0
./nnconsolew modules show sample sample@0.1.0 --json > dist/sample-0.1.0-report.json

O Report do MM usa passed|failed|warning|skipped (o nnp verify local usa pass|warn|fail). Além dos checks do pacote, o ambiente acrescenta os dele: network_contract, sbom, docs_build, help_topics.

3. Plano de deploy​

./nnconsolew modules plan sample sample@0.1.0          # sai ≠ 0 se não estiver READY
./nnconsolew modules plan sample sample@0.1.0 --json > dist/sample-0.1.0-plan.json

Cada recurso aparece com will_create ou exists_ok (namespace, banco, principais, segredos, Secrets, label de grant). BLOCKED traz code, recurso, dono (owner) e o que fazer (remediation) — quase sempre é do dono indicado, não do autor do módulo. Não faça Deploy com o plano BLOCKED.

4. Deploy​

./nnconsolew modules deploy sample sample@0.1.0 --api "$NN_API_URL"

O comando acompanha a operação até o fim (timeout padrão 30 min; --no-wait devolve o aceite e o id da operação). O Deploy faz, numa operação só: first install (namespace, banco, principais, segredos, grants quando é a primeira vez), migrations, stage completo e ativação.

As fases aparecem no last_operation e no progresso:

PREFLIGHT → PROVISIONING → MIGRATING → DEPLOYING → REGISTERING → ACTIVATING → ACTIVE

Falha com checkpoint vira FAILED_RECONCILABLE: repetir o mesmo Deploy retoma de onde parou, sem criar nada duas vezes. Se preferir acompanhar por fora:

./nnconsolew modules wait <action-id> --api "$NN_API_URL"

Prova de sucesso: a operação termina succeeded e o modules show mostra os checks de ambiente passed (network_conformance, status_registration, status_probe_ready, status_first_observation, docs_build, help_topics — os que o módulo declara).

5. Atualizar (N+1)​

Upgrade é o mesmo caminho, com a versão nova:

# 1. versão nova nos descritores, no POM e no chart (juntos)
# 2. gate local verde
./mvnw -q verify

# 3. imagem e pacote da versão nova
./mvnw spring-boot:build-image && ./nnconsolew nnp build

# 4. assinatura (operador) e o mesmo Upload → Deploy
./nnconsolew modules upload dist/sample-0.1.1.signed.nnp --api "$NN_API_URL"
./nnconsolew modules deploy sample sample@0.1.1 --api "$NN_API_URL"

Durante o Deploy convivem a release N (ativa) e a N+1 (standby): as duas servem tráfego, e só a ativa faz o trabalho de manutenção (veja Papel). O schema é expand-only, então a N continua funcionando com o banco novo (veja Migration).

6. Voltar atrás​

./nnconsolew modules rollback sample --to sample@0.1.0 --api "$NN_API_URL"

O rollback ativa uma release anterior já validada (N-1). Ele não desfaz migration: o schema continua o novo, e a release antiga roda sobre ele — é exatamente o que o expand-only garante. Rollback que importa é Java N → Java N-1, dentro da mesma linha do SDK; o piso de upload é declarado em compatibility.sdk.

7. Tirar do ar e aposentar​

./nnconsolew modules disable sample --api "$NN_API_URL"   # para de servir; o dado fica
./nnconsolew modules enable  sample --api "$NN_API_URL"   # volta
./nnconsolew modules retire  sample --api "$NN_API_URL"   # aposenta a release/ módulo

disable é a parada controlada: as rotas do módulo respondem 503 service_disabled, o namespace e o banco continuam existindo, e o enable recupera o serviço sem novo deploy. retire é o fim: não há uninstall de módulo — a remoção de dado e de credencial é procedimento do operador, com o segredo do cofre marcado como retired.

Erros comuns​

  • Subir pacote sem a imagem publicada — image_not_found; publique a imagem do MESMO commit do pacote (o digest do pacote tem de ser o que está no registry).
  • Deploy com plano BLOCKED — nada é provisionado e o bloqueio volta; siga a remediation e o owner do plano.
  • Repetir um Deploy que falhou sem checkpoint — falha sem checkpoint significa que o estado não é retomável: leia o erro antes de repetir.
  • Fazer rollback "para desfazer migration" — rollback não desfaz schema. Correção de schema é release nova, expand-only (veja Migration).
  • Usar um principal de tenant — as permissões de release são scope: platform: principal de realm de cliente não sobe release.
  • Deixar o --no-wait e não guardar o id — sem o id você não acompanha nem repete com rastreio; use modules wait <action-id>.
  • Mudar a versão só no pacote — o serviço embute a versão do release.yaml; versão divergente aparece no /whoami e no log e denuncia release mal montada.
  • Aposentar (retire) para "limpar" — aposentadoria é irreversível pela ferramenta.