Pular para conteúdo

Implantar e atualizar no Kind

Para instalar o ecossistema com credenciais locais, Keycloak e mocks, siga Instalação completa local.

Este guia contém procedimentos do ambiente local experimental. A composição dos nós, dependências e controllers pertence à referência de infraestrutura. DEV, STAGING e PROD pertencem ao TOTVS Apps.

Escolher o alcance

Para o primeiro exercício, instale somente o JSON Handler conforme Primeiro deploy local. Ele usa o chart existente em namespace dedicado e dispensa o bootstrap da plataforma completa.

Para desenvolvimento integrado, use os Helmfiles existentes, entendendo que eles podem alterar várias releases e instalar dependências. O tutorial histórico permanece como acervo, não como sequência atual para copiar sem revisão.

Conferir cluster e perfil

Na raiz de totvs-gateway-infra-local:

kind get clusters
kubectl --context kind-totvs-gateway get nodes -L apptype
helmfile --file install/NGiNX/helmfile.yaml --environment local-win list

O arquivo NGINX declara local-win e local-ubuntu; use o correspondente ao seu ambiente. Não use os nomes dev/stage/prod do README histórico para esse arquivo. list confirma a composição declarada, não instala nem comprova saúde das releases.

A criação do cluster com kind/kind-config.yaml está no primeiro deploy. Não recrie um cluster existente para seguir o tutorial.

Aplicação integrada com Helmfile

Antes de aplicar, revise os valores do perfil, acessos às imagens/charts, disponibilidade dos componentes e o contexto Kubernetes. O arquivo tem dependências needs entre releases. Sua fase crds não deve ser confundida com adoção corporativa de tecnologias experimentais.

Os comandos abaixo usam caminhos e perfis atuais. A aplicação integrada não foi executada nesta validação; o procedimento comprovado é a release isolada do tutorial.

helmfile --kube-context kind-totvs-gateway --file install/NGiNX/helmfile.yaml --environment local-win --selector phase=crds apply
helmfile --kube-context kind-totvs-gateway --file install/NGiNX/helmfile.yaml --environment local-win apply

apply pode depender de plugins Helm e baixar charts externos. Se helm diff não estiver instalado ou houver erro de repositório/credencial, resolva a dependência antes de continuar. A receita de instalação em ambiente limpo ainda precisa de validação própria. Istio/Gateway API permanecem em Estudos e experimentos.

Política de imagens locais

Os charts usam normalmente imagePullPolicy: Always. Essa política solicita resolução da imagem no registry mesmo quando há uma imagem carregada no nó. Para uma tag criada somente no Docker local, a combinação coerente é:

  1. Construir uma tag nova.
  2. Carregá-la no cluster nomeado com kind load docker-image.
  3. Configurar a mesma tag e imagePullPolicy: Never na release de exercício.
  4. Aguardar rollout e conferir imagem, probes e operação funcional.

Never torna a falta de carregamento explícita como ErrImageNeverPull. IfNotPresent permite fallback ao registry; não é a política escolhida para o exercício local. Não altere os defaults versionados nem aplique esse override em ambiente corporativo.

O tutorial executa o chart filho diretamente, portanto usa deployment.image e deployment.imagePullPolicy. No chart agregador totvs-gateway-server, os mesmos valores ficam sob a chave da dependência, por exemplo:

totvs-gateway-json-handler:
  deployment:
    image: gateway-jsonhandler:docs-20261016-02
    imagePullPolicy: Never

Esse fragmento deve compor o override local já utilizado pelo Helmfile, preservando os demais valores. Não passe uma chave de chart filho como se fosse raiz do agregador. Core possui estrutura própria (deployment.core e sidecar); consulte seu chart antes de adaptar exemplos.

Atualização e diagnóstico

Na release isolada, repita helm upgrade --install com a nova tag e os mesmos overrides. No conjunto integrado, atualize a configuração local mantida pelo Helmfile e aplique a release correspondente; alterações manuais com kubectl set image podem ser revertidas pela próxima aplicação declarativa.

Carregar outra imagem sem mudar o Pod template não inicia rollout. Usar tag nova evita depender de cache e de rollout restart. Durante a troca de Pod, reinicie o port-forward quando necessário. Para Pending, ImagePullBackOff ou falhas de probes, siga Debugging e troubleshooting.

Referências no código

Depuração Java no cluster

Para os charts que oferecem global.devMode, use Debug remoto Java no Kind. O tutorial explica a seleção do Pod, port-forward, conexão da IDE e o alcance do flag na release.