Pular para o conteúdo principal

Configuração de Orquestração Local

Este guia detalha o ambiente de orquestração dupla utilizado no monorepo. O desenvolvimento local utiliza duas pipelines de containers especializadas:

  • Podman Compose via Podman Desktop: Utilizado para desenvolvimento local de alta velocidade, testes de banco de dados e fluxos gerais de desenvolvedor usando containers sem daemon.
  • Kubernetes via Minikube & Skaffold: Utilizado para validar configurações, roteamento, descoberta de serviços e políticas de ambiente semelhantes à produção com recarregamento automático (hot-reloading).

Pré-requisitos de Ferramentas​

Para executar e gerenciar o ambiente de orquestração local, instale as ferramentas apropriadas em sua máquina.

1. Podman Container Engine & Podman Desktop​

Para desenvolvimento local de microsserviços e testes de banco de dados:

  • Podman Desktop: Interface gráfica e suíte de gerenciamento para máquinas Podman sem daemon rodando sobre o WSL2 no Windows.
  • Podman CLI & Podman Compose: Ferramentas CLI para gerenciamento de containers e pods.
  • Comando de instalação (PowerShell): 
    winget install RedHat.Podman-Desktop RedHat.Podman

Extensões Necessárias no Podman Desktop​

Dentro do Podman Desktop (Settings -> Extensions), certifique-se de que as seguintes extensões estejam instaladas e habilitadas:

  1. Podman Extension: Extensão principal para gerenciar máquinas Podman, imagens, containers e volumes.
  2. Compose Extension: Necessária para interpretar e executar fluxos de trabalho do podman compose para desenvolvimento multi-container.
  3. Kubectl CLI Extension: Integra controles de cluster kubectl e alternância de contexto do Kubernetes diretamente dentro do Podman Desktop.
Política de Não Utilização de Aliases

Os scripts do nosso projeto invocam explicitamente podman compose e podman exec diretamente no package.json. Não crie aliases no shell (como alias docker=podman). O uso de comandos podman explícitos garante execução reprodutível em todas as estações de trabalho de desenvolvedores e pipelines de CI.

2. Ambiente Kubernetes (Minikube via VirtualBox ou Podman)​

Para testes locais de Kubernetes, validação de roteamento e pipelines de implantação. Nosso fluxo de trabalho aproveita duas estratégias complementares:

  • Abordagem A (Desenvolvimento Local Automatizado): Utiliza minikube, kubectl e skaffold instalados no host com o driver virtualbox ou podman para recarregamento automático em tempo real e implantação rápida do cluster.
  • Abordagem B (Simulação de Staging de Produção): Executa 100% dentro de uma VM Ubuntu isolada no VirtualBox simulando hosts de produção em nuvem sem exigir ferramentas de Kubernetes no host Windows.

Instale as seguintes ferramentas no seu host Windows:

  • Oracle VirtualBox: O hipervisor que hospeda nossos nós de Kubernetes.
  • kubectl: O Minikube inclui sua própria versão do kubectl (acessível via minikube kubectl --). No entanto, instalar o cliente nativo é altamente recomendado para integração automática com ferramentas como OpenLens e Skaffold.
  • Skaffold: Obrigatório no host para a Abordagem A. Automatiza pipelines de build e deploy. Se usar a Abordagem B, o Skaffold roda inteiramente dentro da VM.
  • OpenLens: Cliente visual para monitoramento de clusters.
  • Comando de instalação (PowerShell): 
    # Omita Kubernetes.kubectl ou Google.Skaffold se usar exclusivamente a Abordagem B
    winget install Oracle.VirtualBox Kubernetes.kubectl Google.Skaffold Lens.OpenLens

Dependendo dos seus objetivos, escolha uma ou ambas as abordagens de implantação de VM:

  • Abordagem A: Desenvolvimento em VM Local (Minikube ISO) O Minikube cria e inicializa automaticamente sua própria VM otimizada no VirtualBox.

    • Ferramenta Extra no Host: Requer a CLI do Minikube no host Windows.
    • Comando de instalação (PowerShell): 
      winget install Kubernetes.minikube

  • Abordagem B: Simulação de Staging de Produção (VM Ubuntu Server LTS) Uma VM Ubuntu Server LTS criada manualmente no VirtualBox onde o Minikube roda dentro da VM (simulando servidores de produção na nuvem).

Evite Executar o Skaffold via Containers

Embora seja possível executar o Skaffold dentro de um container, isso exige o mapeamento de sockets de container e remapeamento de hosts internos. Além disso, a sincronização de arquivos em tempo real (pnpm k8s:dev) frequentemente falha em propagar eventos do sistema de arquivos através das fronteiras do container. Por este motivo, instalar o binário nativo do Skaffold localmente é altamente recomendado.

1. Configuração do Container Engine Podman Compose​

Para ciclos rápidos de feedback, executamos microsserviços e bancos de dados de suporte usando Podman Compose.

Configuração da Podman Machine​

  1. Inicialize e inicie a Podman machine padrão: 
    podman machine init
    podman machine start
  2. Verifique o status do engine Podman: 
    podman info

Execução de Scripts do Workspace​

Em vez de executar comandos extensos do Podman Compose manualmente, utilize os filtros do Turborepo e scripts predefinidos no package.json raiz:

  • Iniciar Serviços da Plataforma: pnpm platform:up
  • Parar Serviços da Plataforma: pnpm platform:down
  • Resetar Estado da Plataforma: pnpm platform:reset (deleta volumes)
  • Iniciar Stack Cortex: pnpm cortex:core:up ou pnpm cortex:mcp:up
  • Parar Stack Cortex: pnpm cortex:core:down ou pnpm cortex:mcp:down

2. Configuração do Cluster Local Minikube​

Quando você precisar testar políticas de rede, resolução DNS entre namespaces ou configurações do Ingress Traefik, você deve implantar os workspaces no Minikube.

Abordagem A: Desenvolvimento em VM Local (Driver VirtualBox)​

O Minikube cria e inicializa automaticamente uma VM Linux leve (minikube-iso) no VirtualBox.

Criando o Cluster​

Crie um perfil dedicado no Minikube chamado tupynambalucas usando o driver virtualbox:

minikube start -p tupynambalucas --driver=virtualbox --kubernetes-version=v1.30.0

3. Visualizando o Cluster com OpenLens​

Para monitorar o consumo de recursos, inspecionar logs e gerenciar namespaces visualmente, utilizamos o OpenLens no host Windows.

Conectando à Abordagem A (VM Local)​

O OpenLens lê automaticamente as configurações padrão do kubeconfig localizadas em ~/.kube/config.

  1. Defina o contexto ativo para o perfil do Minikube no seu terminal: 
    kubectl config use-context tupynambalucas
  2. Abra o OpenLens ou o Podman Desktop.
  3. Selecione o contexto de cluster chamado tupynambalucas.

4. Orquestração Profissional com Skaffold​

Em vez de compilar cada imagem de container manualmente e aplicar manifestos do Kubernetes um a um, usamos o Skaffold para orquestrar todo o processo de desenvolvimento.

O Skaffold cuida de:

  • Builds Concorrentes: Compilação em paralelo de todas as imagens de serviço necessárias.
  • Tagging Dinâmico: Atualização automática das tags de imagem nos seus manifestos do Kubernetes para coincidir com a assinatura do build atual.
  • Desenvolvimento Contínuo: Monitoramento de arquivos e sincronização de alterações de código para os Pods ativos em tempo real, sem disparar recompilações completas de container.

Inicializando o Cluster e Workspaces​

Fornecemos scripts simplificados no package.json raiz para gerenciar o ciclo de vida:

  1. Implantar e Executar em Segundo Plano: Para compilar todas as imagens e implantar todos os componentes da plataforma e do cortex no Minikube:

    pnpm k8s:up

  2. Modo de Desenvolvimento Contínuo (Live Hot-Reloading): Para executar o Skaffold em modo de desenvolvimento, monitorando alterações no código-fonte e aplicando hot-reloading automaticamente nos pods em execução:

    pnpm k8s:dev

  3. Parar e Limpar: Para remover todos os recursos, namespaces e cargas de trabalho implantadas pelo Skaffold:

    pnpm k8s:down