gemaal

# gemaal **gemaal** (neerlandês para estação de bombagem) é uma ferramenta de orquestração concebida para manter a saúde de clusters de teste Kubernetes partilhados. Tal como uma estação de bombagem física mantém um polder seco removendo água continuamente, o gemaal mantém um cluster de teste utilizável detetando e limpando automaticamente instalações efémeras obsoletas. Garante que inquilinos de teste temporários não se acumulam e degradam o ambiente para outros utilizadores. ## Filosofia Central * **Limpeza Não Bloqueante**: O gemaal nunca instala nada. Os clientes executam `helm upgrade --install` por si próprios. O serviço apenas desinstala e varre recursos que já não estão em uso. Se o serviço ficar indisponível, a limpeza é atrasada, mas nunca bloqueia o ciclo de instalação dos clientes. * **Modo Sombra**: Por predefinição, o serviço é executado em modo sombra (`dryRun: true`). Planeia, reporta e registra ações de eliminação, mas não as executa até ser explicitamente ativado. Isto proporciona segurança durante a implantação e permite aos operadores verificar a lógica de limpeza antes de esta afetar recursos em produção. * **Watcher Acionado por Nível**: O serviço opera num ciclo tipo cron que re-deriva o estado do cluster de raiz a cada tick. Utiliza `helm list` por namespace para ver exatamente o que um operador vê, agrupando releases em pares de anéis (app + infra) e aplicando regras de recolha de lixo com base em etiquetas de time-to-live (TTL). ## Três Faces 1. **`gemaal` (Serviço)**: Um watcher dentro do cluster responsável por: * Manutenção de TTL sobre inquilinos de teste. * Desmantelamento ciente de pares de anéis (garantindo que a infraestrutura é desmantelada após as aplicações). * Varrimento de artefactos órfãos (por exemplo, subárvores S3). * Exposição de seis RPCs ConnectRPC: Plan, ListTenants, Checkout, Extend, Sweep, Resolve. * Fornecimento de uma consola web para monitorização de inquilinos, idades, níveis e histórico de varrimentos. 2. **`gemaalctl` (CLI)**: Uma interface de linha de comandos para: * Verificação de cadeias de evidência de identidade e inquilinos resolvidos (`whoami`). * Gestão de instalações/desinstalações Helm do lado do cliente com etiquetas de registo estampadas. * Interação com o serviço via ConnectRPC para planeamento, checkout ou extensão de tempos de vida de inquilinos. 3. **Biblioteca Go**: Importada por harnesses de teste para: * Resolver inquilinos permanentes. * Delimitar fases de suites de teste (build, deploy, setup, teardown). * Gerir resolução de identidade e carregamento de configuração. ## Funcionalidades Principais * **Isolamento e Identidade de Inquilinos**: Utiliza etiquetas de nível (por exemplo, `tenancy.truvity.io/tier`) para identificar namespaces alcançáveis. Ignora namespaces de sistema como `gemaal-system`. A identidade é resolvida através de uma cadeia envolvendo email, grupos kubectl e sessões AWS SSO. * **Regras de Recolha de Lixo**: * TTL uniforme baseado na última atividade, configurável por inquilino ou nível. * Precedência `keep-until` para necessidades específicas de retenção. * Desmantelamento ordenado por anéis (aplicação antes da infraestrutura). * Recolha de artefactos órfãos após um período de carência. * **Autenticação e Autorização**: * As mutações autenticam via TokenReview contra a API Kubernetes (para workloads) ou OIDC JWT (para humanos). * Checkout/Extend requerem direitos de proprietário ou administrador. * As operações de Sweep são exclusivas de administradores. * **Consola Web**: Uma aplicação de página única Vite/React/MUI incorporada no binário, fornecendo uma pilha de consola de frota para visualizar o estado dos inquilinos e o histórico de varrimentos. ## Integração com Harness de Teste Os projetos podem integrar o gemaal nos seus testes de integração Go usando a biblioteca `pkg/harness`. O harness resolve um inquilino permanente uma vez em `TestMain`, permitindo que os testes corram dentro de um namespace dedicado. O serviço trata da limpeza através de etiquetas estampadas nas releases Helm, pelo que a própria suite de teste não cria nem elimina nada diretamente (exceto em hooks de teardown intercalares). Variáveis de ambiente como `GEMAAL_TEST_SKIP_BUILD`, `GEMAAL_TEST_SKIP_DEPLOY` e `GEMAAL_TEST_KEEP` permitem controlo granular sobre o ciclo de vida dos testes em pipelines CI/CD. ## Acesso AWS O serviço suporta cadeias de credenciais AWS padrão, incluindo EKS Pod Identity e IRSA (IAM Roles for Service Accounts). Interage com o AWS Systems Manager (SSM) para armazenamento de artefactos e requer permissões apropriadas para STS e endpoints de identidade de pod. ## Desenvolvimento * **Toolchain**: Utiliza [devbox](https://www.jetify.com/devbox/) e [just](https://just.systems/) para gestão de tarefas. * **Comandos**: * `just check`: Executa build, teste, lint e verificações de vulnerabilidade. * `just generate`: Regenera código a partir de definições Protobuf. * `just run`: Executa o esqueleto do serviço contra configuração de exemplo. ## Estado O projeto está em desenvolvimento inicial (fase G4). O design, a superfície proto, a biblioteca cliente, a CLI e o serviço estão implementados. O serviço ainda não teve uma implantação em produção; as implantações iniciais serão em modo sombra. A API cliente está em uso real, mas pode mudar entre versões menores 0.x. ## Licença Licença MIT