Skip to main content

Comece aqui

Um módulo é um produto que roda dentro da NNumbers Console: um serviço de backend (o NNS), escrito em Java 26 + Spring Boot 4.1 sobre o SDK da plataforma, mais os descritores que declaram o que ele precisa (rotas, permissões, trilhas de auditoria, placement, banco, configuração, documentação e ajuda contextual), um chart que a plataforma renderiza no Kubernetes e um Status Probe que responde "este produto está funcionando?". Tudo isso vira um pacote único — o NNP — que o Module Manager valida e implanta.

A Console é o lugar em que o módulo aparece para quem usa: cada rota vira uma chamada pelo gateway (com autenticação e permissão conferidas de novo pelo próprio NNS), cada mutação vira um evento de auditoria e cada operação demorada vira uma Action visível no Action Center. Você não cria namespace, banco, conta nem Secret: você declara o que o módulo precisa no próprio repositório e a plataforma provisiona no primeiro deploy, dentro do que foi autorizado.

O que você precisa na máquina​

o quêpor quê
Gito módulo é um repositório; nnumbers-console-<id>
JDK 26o serviço compila e roda em Java 26 (java --version tem de mostrar a 26)
Um runtime de contêiner./mvnw spring-boot:build-image constrói a imagem OCI do serviço (Paketo)
MySQL 8.0.35 ou 8.4 (opcional, mas recomendado)os testes de banco rodam contra MySQL real; sem ele, esses testes são pulados

Nada além disso: o Maven Wrapper (./mvnw) e a ferramenta do desenvolvedor (./nnconsolew) vêm dentro do projeto — você não instala Maven nem a ferramenta. Os comandos usam git, java e ./mvnw/./nnconsolew, e só.

Para criar o PRIMEIRO módulo (quando ainda não existe um repositório com o ./nnconsolew), baixe o jar all do CLI — br.com.nnumbers.console:console-sdk-cli (0.8.0-SNAPSHOT), no grupo https://cicd.nnumbers.com.br/nexus/repository/maven-public/ (leitura sem credencial; o grupo também espelha o Maven Central):

MAVEN=https://cicd.nnumbers.com.br/nexus/repository/maven-public
SDK=0.8.0-SNAPSHOT                       # a versão do SDK desta linha
value=$(curl -sS "$MAVEN/br/com/nnumbers/console/console-sdk-cli/$SDK/maven-metadata.xml" \
  | awk '/<classifier>all<\/classifier>/{f=1} f && /<value>/{gsub(/.*<value>|<\/value>.*/,""); print; exit}')
curl -sS -o nnconsole-all.jar \
  "$MAVEN/br/com/nnumbers/console/console-sdk-cli/$SDK/console-sdk-cli-$value-all.jar"
java -jar nnconsole-all.jar version
# sdk 0.8.0-SNAPSHOT (nnconsole/0.8.0-SNAPSHOT), contrato console.nnumbers.io/v1alpha3

(O caminho -SNAPSHOT do arquivo 404; por isso o value do <snapshotVersions>.)

Como as peças se encaixam​

         seu módulo (nnumbers-console-notes/)
  ┌──────────────────────────────────────────────────────────┐
  │  src/…          o NNS (Java 26 + Spring Boot)            │
  │  nnp/           os descritores (release, api, iam,       │
  │                 audit, placement)                        │
  │  nns/service.yaml, status/, docs/, help/, embed/         │
  │  nns/helm/chart/  o chart do serviço                     │
  │  tests/         as expectativas da conformance           │
  └───────────────┬──────────────────────────────────────────┘
                  │  ./mvnw verify          (testes)
                  │  ./mvnw spring-boot:build-image  (imagem)
                  │  ./nnconsolew nnp build  (pacote .nnp)
                  ▼
            notes-0.1.0.nnp ──► Module Manager (upload + deploy)
                                      │  valida, planeja, provisiona
                                      ├─ Kubernetes: namespace, Deployment,
                                      │  Service, chart, Migration Job
                                      └─ Console: rotas, permissões,
                                         auditoria, Status, docs e help
  • SDK da plataforma (console-sdk-core, console-sdk-jdbc, console-sdk-spring, o starter console-sdk-spring-boot-starter): é o que o seu serviço usa para virar um NNS. As anotações e classes do SDK cuidam do protocolo (rotas por @NnsRoute, tokens e permissões, idempotência, ações assíncronas, auditoria, migrations, /live e /ready); você escreve o domínio.
  • Ferramenta do desenvolvedor (nnconsole, usada no repositório pelo ./nnconsolew): confere os descritores e as rotas, os scans de segredos e portabilidade, a conformance, e constrói o pacote (nnp build), assina (nnp sign), verifica (nnp verify) e conversa com o Module Manager (modules upload|plan|deploy|rollback|disable|enable|retire|wait).
  • Module Manager: recebe o NNP, valida (assinatura, checksums, SBOM, descritores, rede), planeja o que será criado e provisiona no deploy — namespace, banco, segredos, rotas no gateway, status, docs.
  • Console: onde o produto aparece para quem usa; o shell carrega o módulo, o gateway autentica as chamadas e o serviço confere a permissão de novo.

O ciclo de vida em uma olhada​

java -jar nnconsole-all.jar module create --dir nnumbers-console-notes --name "Notes" notes  # 1. cria o módulo
cd nnumbers-console-notes             # a partir daqui, tudo roda DENTRO do módulo
./mvnw -q verify                      # 2. testa
./mvnw spring-boot:build-image        # 3. constrói a imagem do serviço
./nnconsolew nnp build --root . --out dist \
  --java-image "$(cat nns/build/image.ref)" \
  --probe-java-image "$(cat status/build/image.ref)"   # 4. empacota o .nnp
./nnconsolew nnp verify dist/notes-0.1.0.nnp           # 5. valida o pacote
./nnconsolew modules upload dist/notes-0.1.0.signed.nnp --api "$NN_API_URL"  # 6. upload (operador)
./nnconsolew modules deploy notes notes@0.1.0 --api "$NN_API_URL"            # 7. deploy (operador)

O passo 1 usa o jar baixado (a module create recusa as flags DEPOIS do id); do passo 2 em diante tudo roda no repositório do módulo. O passo 4 lê as imagens PUBLICADAS por digest (nns/build/image.ref): construí-las exige um runtime de contêiner na sua máquina, publicá-las exige a credencial de registry (a equipe da plataforma fornece num DOCKER_CONFIG) e a assinatura do pacote (passo 6) é do operador, com a chave dele.

Os passos 6 e 7 são do operador, com a sua identidade de plataforma; o resto é seu, no repositório do módulo. Nada é aplicado com kubectl ou helm à mão: produção é só pelo Module Manager.

Para onde ir agora​

  • Crie seu primeiro módulo NNumbers em Java — do zero ao módulo instalado e visível na Console, passo a passo, com o comando exato e a saída esperada.
  • O ciclo de vida de um módulo — o guia completo (repositório, domínio, descritores, provas locais, publicação, upgrade e rollback) para quem terminou o tutorial.
  • As páginas de Referência (descritores, API do SDK, checklist e a referência da ferramenta) ficam ao lado deste produto no portal.