gemaal

# gemaal **gemaal** (neerlandés para estación de bombeo) es una herramienta de orquestación diseñada para mantener la salud de clústeres de prueba de Kubernetes compartidos. Así como una estación de bombeo física mantiene seco un pólder eliminando agua continuamente, gemaal mantiene utilizable un clúster de prueba detectando y limpiando automáticamente instalaciones efímeras obsoletas. Garantiza que los inquilinos de prueba temporales no se acumulen y degraden el entorno para otros usuarios. ## Filosofía central * **Limpieza no bloqueante**: gemaal nunca instala nada. Los clientes ejecutan `helm upgrade --install` ellos mismos. El servicio solo desinstala y barre recursos que ya no están en uso. Si el servicio se cae, la limpieza se retrasa, pero nunca bloquea el bucle de instalación de los clientes. * **Modo sombra**: Por defecto, el servicio se ejecuta en modo sombra (`dryRun: true`). Planifica, informa y registra acciones de eliminación, pero no las ejecuta hasta que se habilite explícitamente. Esto proporciona seguridad durante el despliegue y permite a los operadores verificar la lógica de limpieza antes de que afecte a recursos en vivo. * **Observador activado por nivel**: El servicio opera en un bucle tipo cron que vuelve a derivar el estado del clúster desde cero en cada ciclo. Utiliza `helm list` por espacio de nombres para ver exactamente lo que ve un operador, agrupando releases en pares de anillos (app + infra) y aplicando reglas de recolección de basura basadas en etiquetas de tiempo de vida (TTL). ## Tres caras 1. **`gemaal` (Servicio)**: Un observador dentro del clúster responsable de: * Mantenimiento de TTL sobre inquilinos de prueba. * Desmontaje consciente de pares de anillos (asegurando que la infraestructura se desmonte después de las aplicaciones). * Barridos de artefactos huérfanos (por ejemplo, subárboles de S3). * Exponer seis RPC de ConnectRPC: Plan, ListTenants, Checkout, Extend, Sweep, Resolve. * Proporcionar una consola web para monitorear inquilinos, antigüedades, niveles e historial de barridos. 2. **`gemaalctl` (CLI)**: Una interfaz de línea de comandos para: * Verificar cadenas de evidencia de identidad e inquilinos resueltos (`whoami`). * Gestionar instalaciones/desinstalaciones de Helm del lado del cliente con etiquetas de libro mayor estampadas. * Interactuar con el servicio a través de ConnectRPC para planificar, hacer checkout o extender tiempos de vida de inquilinos. 3. **Biblioteca Go**: Importada por arneses de prueba para: * Resolver inquilinos permanentes. * Delimitar fases de suites de prueba (build, deploy, setup, teardown). * Gestionar resolución de identidad y carga de configuración. ## Características clave * **Aislamiento de inquilinos e identidad**: Utiliza etiquetas de nivel (por ejemplo, `tenancy.truvity.io/tier`) para identificar espacios de nombres alcanzables. Ignora espacios de nombres del sistema como `gemaal-system`. La identidad se resuelve a través de una cadena que involucra correo electrónico, grupos de kubectl y sesiones de AWS SSO. * **Reglas de recolección de basura**: * TTL uniforme basado en la última actividad, configurable por inquilino o nivel. * Precedencia de `keep-until` para necesidades específicas de retención. * Desmontaje ordenado por anillos (aplicación antes que infraestructura). * Recolección de artefactos huérfanos después de un período de gracia. * **Autenticación y autorización**: * Las mutaciones se autentican mediante TokenReview contra la API de Kubernetes (para cargas de trabajo) o JWT de OIDC (para humanos). * Checkout/Extend requieren derechos de propietario o administrador. * Las operaciones de Sweep son solo para administradores. * **Consola web**: Una aplicación de página única Vite/React/MUI incrustada en el binario, que proporciona una pila de consola de flota para visualizar el estado de los inquilinos y el historial de barridos. ## Integración con arnés de prueba Los proyectos pueden integrar gemaal en sus pruebas de integración de Go usando la biblioteca `pkg/harness`. El arnés resuelve un inquilino permanente una vez en `TestMain`, permitiendo que las pruebas se ejecuten dentro de un espacio de nombres dedicado. El servicio maneja la limpieza mediante etiquetas estampadas en los releases de Helm, por lo que la propia suite de pruebas no crea ni elimina nada directamente (excepto en ganchos de desmontaje intermedios). Variables de entorno como `GEMAAL_TEST_SKIP_BUILD`, `GEMAAL_TEST_SKIP_DEPLOY` y `GEMAAL_TEST_KEEP` permiten un control detallado sobre el ciclo de vida de las pruebas en pipelines de CI/CD. ## Acceso a AWS El servicio admite cadenas de credenciales estándar de AWS, incluida EKS Pod Identity e IRSA (IAM Roles for Service Accounts). Interactúa con AWS Systems Manager (SSM) para el almacenamiento de artefactos y requiere permisos apropiados para STS y endpoints de identidad de pod. ## Desarrollo * **Cadena de herramientas**: Utiliza [devbox](https://www.jetify.com/devbox/) y [just](https://just.systems/) para la gestión de tareas. * **Comandos**: * `just check`: Ejecuta compilación, pruebas, lint y verificaciones de vulnerabilidades. * `just generate`: Regenera código a partir de definiciones de Protobuf. * `just run`: Ejecuta el esqueleto del servicio contra una configuración de ejemplo. ## Estado El proyecto está en desarrollo temprano (fase G4). El diseño, la superficie proto, la biblioteca cliente, la CLI y el servicio están en su lugar. El servicio aún no ha visto un despliegue en producción; los despliegues iniciales serán en modo sombra. La API del cliente está en uso real pero puede cambiar entre versiones menores 0.x. ## Licencia Licencia MIT