Primeiro deploy local

Esta jornada usa o JSON Handler para obter o código, compilar, testar, construir uma imagem JVM e instalar/atualizar o serviço no Kind. Ele gera JSON Schema a partir de JSON e não precisa de MongoDB, Redis nem de autenticação externa para a operação escolhida. O exemplo exercita uma chamada funcional, além do health check.

Os comandos usam PowerShell, Java 21, Docker com containers Linux, Kind, kubectl e Helm. No Linux, use ./mvnw e adapte a sintaxe de variáveis ao shell. Os comandos deste tutorial não são uma receita universal para os demais serviços.

1. Obter os repositórios

Configure o acesso Git corporativo conforme Preparar o ambiente. Escolha o diretório de trabalho; o exemplo usa:

$gatewayWorkspace = 'C:\TOTVS\workspace\gateway'
New-Item -ItemType Directory -Force "$gatewayWorkspace/services", "$gatewayWorkspace/infra" | Out-Null
git clone --branch develop git@ssh.dev.azure.com:v3/totvstfs/TOTVS-Gateway/totvs-gateway-jsonhandler "$gatewayWorkspace/services/totvs-gateway-jsonhandler"
git clone --branch main git@ssh.dev.azure.com:v3/totvstfs/TOTVS-Gateway/totvs-gateway-infra-local "$gatewayWorkspace/infra/totvs-gateway-infra-local"
$servicePath = "$gatewayWorkspace/services/totvs-gateway-jsonhandler"
$infraPath = "$gatewayWorkspace/infra/totvs-gateway-infra-local"

Se já possui os repositórios, não clone sobre eles: defina as mesmas variáveis, confira git status e execute git pull --ff-only dentro de cada repositório. Resolva falhas de acesso ou divergências antes de continuar; preserve suas alterações locais.

2. Conferir a configuração

Set-Location $servicePath
java -version
./mvnw.cmd --version
docker info

O Maven deve usar Java 21. O serviço declara porta 8080 e raiz HTTP /jsonhandler em src/main/resources/application.properties. Esta jornada usa esses defaults; não requer copiar segredos ou criar .env. Consulte Execução local para executar fora do cluster.

3. Compilar e testar

./mvnw.cmd verify
if ($LASTEXITCODE -ne 0) { throw 'Build ou testes falharam; interrompa a jornada.' }

O pacote JVM fica em target/quarkus-app/. Não copie somente o JAR: o Dockerfile consome também lib/, app/ e quarkus/. verify respeita o POM: os testes Surefire são executados, mas Failsafe é desabilitado pelo skipITs padrão. Veja Build e testes.

4. Construir e conferir a imagem

Use uma tag inédita para cada iteração; estas tags identificam a validação desta jornada.

$image = 'gateway-jsonhandler:docs-20261016-01'
docker build -f docker/Dockerfile.jvm -t $image .
if ($LASTEXITCODE -ne 0) { throw 'A imagem não foi construída.' }
docker run --detach --rm --name gateway-docs-jsonhandler -p 127.0.0.1:18080:8080 $image

Após a inicialização, confira o serviço. Se ainda estiver subindo, consulte docker logs gateway-docs-jsonhandler e repita a consulta.

Invoke-RestMethod http://127.0.0.1:18080/jsonhandler/q/health/ready
$body = @{ input = '{"name":"John","age":30}' } | ConvertTo-Json -Compress
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:18080/jsonhandler/api/json-schema/generate -ContentType application/json -Body $body
docker stop gateway-docs-jsonhandler

O health deve indicar UP. A chamada funcional deve produzir schema do tipo object, com properties.name.type = string e properties.age.type = integer. O payload deriva de JsonSchemaControllerTest; input é uma string contendo JSON, não um objeto aninhado na requisição.

5. Disponibilizar a imagem no Kind

O cluster desta jornada é totvs-gateway, com contexto kind-totvs-gateway. A configuração local explica os nós e seus labels. Se ainda não existe, crie-o com o arquivo do repositório:

Set-Location $infraPath
kind get clusters
# Execute a criação somente se totvs-gateway ainda não existir.
kind create cluster --config kind/kind-config.yaml

Em um cluster existente, pule a criação. Não é necessário instalar o conjunto completo de dependências para executar este serviço isoladamente.

kubectl --context kind-totvs-gateway get nodes -L apptype
kind load docker-image $image --name totvs-gateway
if ($LASTEXITCODE -ne 0) { throw 'Falha ao carregar a imagem nos nós.' }

O chart seleciona nós com apptype=service. A configuração Kind do repositório fornece esses nós. A imagem deve estar disponível nos nós que podem receber o Pod, inclusive durante uma atualização.

6. Instalar o chart isoladamente

Usaremos o chart existente, um namespace exclusivo e nenhuma alteração dos values versionados. Os nomes da release, do namespace e do deployment são diferentes por definição:

$namespace = 'gateway-docs-first-deploy'
$release = 'gateway-docs-jsonhandler'
$chart = 'helm-releases/totvs-gateway-apps/totvs-gateway-json-handler'
helm template $release $chart --namespace $namespace --set global.namespace=$namespace --set-string deployment.image=$image --set deployment.imagePullPolicy=Never
helm upgrade --install $release $chart --kube-context kind-totvs-gateway --namespace $namespace --create-namespace --set global.namespace=$namespace --set-string deployment.image=$image --set deployment.imagePullPolicy=Never --wait --timeout 180s
if ($LASTEXITCODE -ne 0) { throw 'Deployment não concluído; consulte o diagnóstico.' }
kubectl --context kind-totvs-gateway -n $namespace rollout status deployment/totvs-gateway-json-handler --timeout=60s

O chart usa global.namespace nos manifests, por isso essa opção acompanha --namespace. Seu nome de recurso é fixo: instale apenas uma release desse chart por namespace. Never substitui o default Always somente nesta release, pois a imagem foi carregada diretamente nos nós. Consulte a política de imagens locais.

7. Validar no cluster

Em um segundo terminal, mantenha o encaminhamento ativo:

kubectl --context kind-totvs-gateway -n gateway-docs-first-deploy port-forward svc/totvs-gateway-json-handler 18081:8080 --address 127.0.0.1

No primeiro terminal:

Invoke-RestMethod http://127.0.0.1:18081/jsonhandler/q/health/ready
$body = @{ input = '{"name":"John","age":30}' } | ConvertTo-Json -Compress
$schema = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:18081/jsonhandler/api/json-schema/generate -ContentType application/json -Body $body
if ($schema.properties.name.type -ne 'string' -or $schema.properties.age.type -ne 'integer') { throw 'Resposta funcional inesperada.' }
$schema
kubectl --context kind-totvs-gateway -n $namespace get pods -l app=totvs-gateway-json-handler -o wide

Este acesso usa Service e port-forward, sem Ingress, Istio ou Gateway API. Ele valida o JSON Handler isolado, não o fluxo completo de uma API publicada pelo Gateway.

8. Atualizar a imagem e repetir a validação

Depois de alterar o serviço, execute novamente ./mvnw.cmd verify em $servicePath. Construa uma tag nova; carregar a imagem sozinho não altera o Deployment.

Set-Location $servicePath
$image = 'gateway-jsonhandler:docs-20261016-02'
docker build -f docker/Dockerfile.jvm -t $image .
if ($LASTEXITCODE -ne 0) { throw 'Falha no build da nova imagem.' }
kind load docker-image $image --name totvs-gateway
if ($LASTEXITCODE -ne 0) { throw 'Falha no carregamento da nova imagem.' }
Set-Location $infraPath
helm upgrade --install $release $chart --kube-context kind-totvs-gateway --namespace $namespace --set global.namespace=$namespace --set-string deployment.image=$image --set deployment.imagePullPolicy=Never --wait --timeout 180s
if ($LASTEXITCODE -ne 0) { throw 'Atualização não concluída.' }
kubectl --context kind-totvs-gateway -n $namespace rollout status deployment/totvs-gateway-json-handler --timeout=60s
kubectl --context kind-totvs-gateway -n $namespace get deployment totvs-gateway-json-handler -o jsonpath='{.spec.template.spec.containers[0].image}'

Encerre e reinicie o port-forward se ele perder a conexão durante a troca de Pod. Repita as duas chamadas da etapa 7. Uma tag nova muda o Pod template e inicia o rollout; rollout restart não substitui a atualização da imagem e não é necessário nesta sequência.

9. Encerrar o exercício

Interrompa o port-forward com Ctrl+C. Se este namespace foi criado exclusivamente para o tutorial, remova os recursos do exercício:

helm uninstall gateway-docs-jsonhandler --kube-context kind-totvs-gateway --namespace gateway-docs-first-deploy
kubectl --context kind-totvs-gateway delete namespace gateway-docs-first-deploy

Não exclua o cluster nem namespaces compartilhados. As tags carregadas no Docker/Kind podem ser reutilizadas; não é necessário removê-las para encerrar o serviço.

Validação desta jornada

Resultados de execução e limites estão no registro de validação do onboarding. Os demais guias diferenciam caminhos Java/Go e não estendem automaticamente esses resultados a todos os serviços.

Referências no código

• totvs-gateway-jsonhandler — pom.xml

• totvs-gateway-jsonhandler — docker/Dockerfile.jvm

• totvs-gateway-jsonhandler — src/main/resources/application.properties

• totvs-gateway-jsonhandler — src/test/java/app/totvs/gateway/jsonhandler/controller/JsonSchemaControllerTest.java

• totvs-gateway-infra-local — kind/kind-config.yaml

• totvs-gateway-infra-local — helm-releases/totvs-gateway-apps/totvs-gateway-json-handler/templates/deploy.yaml

Próximo passo: debug remoto

O tutorial de debug Java no Kind usa o BFF, cujo chart suporta global.devMode. O chart do JSON Handler desta jornada não possui esse mecanismo; não transfira a configuração automaticamente entre os serviços.