Об этом проекте

# gemaal **gemaal** (нидерландское слово, означающее насосная станция) — это инструмент оркестрации, предназначенный для поддержания здоровья общих тестовых кластеров Kubernetes. Так же как физическая насосная станция поддерживает сухость полдера, постоянно удаляя воду, gemaal поддерживает пригодность тестового кластера, автоматически обнаруживая и очищая устаревшие, эфемерные установки. Это гарантирует, что временные тестовые арендаторы не накапливаются и не ухудшают среду для других пользователей. ## Основная философия * **Неблокирующая очистка**: gemaal никогда ничего не устанавливает. Клиенты сами выполняют `helm upgrade --install`. Сервис только удаляет и собирает ресурсы, которые больше не используются. Если сервис выйдет из строя, очистка задержится, но он никогда не блокирует цикл установки для клиентов. * **Режим тени**: По умолчанию сервис работает в режиме тени (`dryRun: true`). Он планирует, сообщает и логирует действия удаления, но не выполняет их, пока не будет явно включён. Это обеспечивает безопасность при развёртывании и позволяет операторам проверить логику очистки перед её воздействием на живые ресурсы. * **Наблюдатель, срабатывающий по уровню**: Сервис работает в цикле, похожем на cron, который каждую итерацию пересчитывает состояние кластера с нуля. Он использует `helm list` в каждом пространстве имён, чтобы увидеть именно то, что видит оператор, группируя релизы в пары кольца (приложение + инфраструктура) и применяя правила сборки мусора на основе меток времени жизни (TTL). ## Три грани 1. **`gemaal` (Сервис)**: Внутрикластерный наблюдатель, отвечающий за: * Обслуживание TTL тестовых арендаторов. * Снос пар кольца (обеспечение снятия инфраструктуры после приложения). * Сбор сиротских артефактов (например, поддеревьев S3). * Предоставление шести RPC ConnectRPC: Plan, ListTenants, Checkout, Extend, Sweep, Resolve. * Веб‑консоль для мониторинга арендаторов, их возраста, уровней и истории очистки. 2. **`gemaalctl` (CLI)**: Интерфейс командной строки для: * Проверки цепочек доказательств идентичности и решённых арендаторов (`whoami`). * Управления клиентскими установками/удалением Helm с метками журнала. * Взаимодействия с сервисом через ConnectRPC для планирования, проверки или продления срока жизни арендатора. 3. **Библиотека Go**: Импортируется тестовыми harness‑ами для: * Разрешения стоящих арендаторов. * Ограничения фаз набора тестов (сборка, развёртывание, настройка, снятие). * Управления разрешением идентичности и загрузки конфигурации. ## Ключевые возможности * **Изоляция арендаторов и идентичность**: Использует метки уровней (например, `tenancy.truvity.io/tier`) для определения доступных пространств имён. Игнорирует системные пространства имён типа `gemaal-system`. Идентичность определяется цепочкой, включающей email, группы kubectl и сеансы AWS SSO. * **Правила сборки мусора**: * Единый TTL на основе последней активности, настраиваемый на уровне арендатора или уровня. * Приоритет `keep-until` для специфических потребностей в хранении. * Упорядоченная по кольцу очистка (сначала приложение, потом инфраструктура). * Сбор сиротских артефактов после периода grace. * **Аутентификация и авторизация**: * Мутации аутентифицируются через TokenReview в Kubernetes API (для нагрузок) или OIDC JWT (для людей). * Операции Checkout/Extend требуют прав владельца или администратора. * Операции Sweep доступны только администратору. * **Веб‑консоль**: Одностраничное приложение на Vite/React/MUI, встроенное в бинарник, предоставляющее панель мониторинга флота для визуализации статуса арендаторов и истории очистки. ## Интеграция с тестовыми harness‑ами Проекты могут интегрировать gemaal в свои Go‑интеграционные тесты с помощью библиотеки `pkg/harness`. Harness разрешает стоящий арендатор один раз в `TestMain`, позволяя тестам выполняться в выделенном пространстве имён. Сервис занимается очисткой благодаря меткам, поставленным на релизы Helm, поэтому тестовый набор сам ничего не создаёт и не удаляет (кроме промежуточных хуков teardown). Переменные окружения типа `GEMAAL_TEST_SKIP_BUILD`, `GEMAAL_TEST_SKIP_DEPLOY` и `GEMAAL_TEST_KEEP` позволяют тонко управлять жизненным циклом теста в CI/CD‑конвейерах. ## Доступ к AWS Сервис поддерживает стандартные цепочки учётных данных AWS, включая EKS Pod Identity и IRSA (IAM Roles for Service Accounts). Он взаимодействует с AWS Systems Manager (SSM) для хранения артефактов и требует соответствующих прав для STS и конечных точек pod identity. ## Разработка * **Инструментарий**: Использует [devbox](https://www.jetify.com/devbox/) и [just](https://just.systems/) для управления задачами. * **Команды**: * `just check` — запускает сборку, тесты, линтинг и проверку уязвимостей. * `just generate` — regenerates код из определений Protobuf. * `just run` — запускает скелет сервиса с примерной конфигурацией. ## Статус Проект находится на ранней стадии разработки (фаза G4). Дизайн, поверхность proto, клиентская библиотека, CLI и сервис уже на месте. Сервис ещё не был развёрнут в production; первоначальные развёртывания будут выполняться в режиме тени. Клиентский API используется в реальных условиях, но может меняться между минорными версиями 0.x. ## Лицензия MIT License