gemaal

# gemaal **gemaal**（荷兰语，意为泵站）是一个编排工具，旨在维护共享 Kubernetes 测试集群的健康。正如实体泵站通过持续排水保持圩田干燥，gemaal 通过自动检测并清理陈旧、临时的安装，使测试集群保持可用。它确保临时测试租户不会累积并降低其他用户的环境质量。 ## 核心理念 * **非阻塞清理**：gemaal 从不安装任何东西。客户端自行运行 `helm upgrade --install`。该服务仅卸载并清扫不再使用的资源。如果服务宕机，清理会被延迟，但绝不会阻塞客户端的安装循环。 * **影子模式**：默认情况下，服务以影子模式（`dryRun: true`）运行。它会规划、报告并记录删除操作，但在明确启用之前不会执行。这在部署期间提供了安全性，并允许运维人员在清理逻辑影响实时资源之前进行验证。 * **电平触发监视器**：服务以类似 cron 的循环运行，每个周期都从头重新推导集群状态。它按命名空间使用 `helm list`，以查看与运维人员所见完全一致的内容，将 release 分组为环形配对（应用 + 基础设施），并根据生存时间（TTL）标签应用垃圾回收规则。 ## 三个面向 1. **`gemaal`（服务）**：集群内监视器，负责： * 对测试租户进行 TTL 维护。 * 感知环形配对的拆除（确保基础设施在应用之后拆除）。 * 孤立工件清扫（例如 S3 子树）。 * 暴露六个 ConnectRPC RPC：Plan、ListTenants、Checkout、Extend、Sweep、Resolve。 * 提供用于监控租户、年龄、层级和清扫历史的 Web 控制台。 2. **`gemaalctl`（CLI）**：命令行界面，用于： * 检查身份证据链和已解析租户（`whoami`）。 * 管理客户端侧 Helm 安装/卸载，并打上账本标签。 * 通过 ConnectRPC 与服务交互，以进行规划、签出或延长租户生命周期。 3. **Go 库**：由测试框架导入，用于： * 解析常驻租户。 * 括起测试套件阶段（构建、部署、设置、拆除）。 * 管理身份解析和配置加载。 ## 关键特性 * **租户隔离与身份**：使用层级标签（例如 `tenancy.truvity.io/tier`）识别可到达的命名空间。忽略 `gemaal-system` 等系统命名空间。身份通过涉及电子邮件、kubectl 组和 AWS SSO 会话的链进行解析。 * **垃圾回收规则**： * 基于最后活动的统一 TTL，可按租户或层级配置。 * 针对特定保留需求的 `keep-until` 优先级。 * 按环形顺序拆除（应用先于基础设施）。 * 在宽限期后收集孤立工件。 * **认证与授权**： * 变更操作通过针对 Kubernetes API 的 TokenReview（用于工作负载）或 OIDC JWT（用于人员）进行认证。 * Checkout/Extend 需要所有者或管理员权限。 * Sweep 操作仅限管理员。 * **Web 控制台**：嵌入二进制文件中的 Vite/React/MUI 单页应用，提供用于可视化租户状态和清扫历史的机群控制台栈。 ## 测试框架集成 项目可以使用 `pkg/harness` 库将 gemaal 集成到其 Go 集成测试中。该框架在 `TestMain` 中解析一次常驻租户，允许测试在专用命名空间内运行。服务通过打在 Helm release 上的标签处理清理，因此测试套件本身不直接创建和删除任何内容（临时拆除钩子除外）。 诸如 `GEMAAL_TEST_SKIP_BUILD`、`GEMAAL_TEST_SKIP_DEPLOY` 和 `GEMAAL_TEST_KEEP` 等环境变量允许在 CI/CD 流水线中对测试生命周期进行细粒度控制。 ## AWS 访问 该服务支持标准 AWS 凭证链，包括 EKS Pod Identity 和 IRSA（服务账户的 IAM 角色）。它与 AWS Systems Manager（SSM）交互以进行工件存储，并需要适当的 STS 和 pod identity 端点权限。 ## 开发 * **工具链**：使用 [devbox](https://www.jetify.com/devbox/) 和 [just](https://just.systems/) 进行任务管理。 * **命令**： * `just check`：运行构建、测试、lint 和漏洞检查。 * `just generate`：从 Protobuf 定义重新生成代码。 * `just run`：使用示例配置运行服务骨架。 ## 状态 该项目处于早期开发阶段（G4 阶段）。设计、proto 接口、客户端库、CLI 和服务均已就位。该服务尚未进行生产部署；初始部署将以影子模式进行。客户端 API 已在实际使用中，但可能在 0.x 次版本之间发生变化。 ## 许可证 MIT License