इस प्रोजेक्ट के बारे में

# gemaal **gemaal** (Dutch for pumping station) एक ऑर्केस्ट्रेशन टूल है जो साझा Kubernetes टेस्ट क्लस्टर के स्वास्थ्य को बनाए रखने के लिए डिज़ाइन किया गया है। जैसे एक भौतिक पंपिंग स्टेशन लगातार पानी हटाकर पोल्डर को सूखा रखता है, gemaal स्वचालित रूप से स्टेल, एफेमेरल इंस्टॉलेशन का पता लगाकर और साफ़ करके टेस्ट क्लस्टर को उपयोगयोग्य रखती है। यह सुनिश्चित करती है कि अस्थायी टेस्ट टेनेंट जमा न हों और अन्य उपयोगकर्ताओं के लिए पर्यावरण को खराब न करें। ## Core Philosophy * **Non-Blocking Cleanup**: gemaal कभी भी कुछ इंस्टॉल नहीं करती। क्लाइंट स्वयं `helm upgrade --install` चलाते हैं। सेवा केवल उन संसाधनों को अनइंस्टॉल और स्वीप करती है जो अब उपयोग में नहीं हैं। यदि सेवा बंद हो जाती है, तो क्लीनअप देरी से होता है, लेकिन यह क्लाइंट्स के इंस्टॉलेशन लूप को कभी ब्लॉक नहीं करती। * **Shadow Mode**: डिफ़ॉल्ट रूप से, सेवा शैडो मोड (`dryRun: true`) में चलती है। यह हटाने की कार्रवाइयों की योजना बनाती है, रिपोर्ट करती है और लॉग करती है लेकिन स्पष्ट रूप से सक्षम किए जाने तक उन्हें निष्पादित नहीं करती। यह डिप्लॉयमेंट के दौरान सुरक्षा प्रदान करता है और ऑपरेटर्स को लाइव संसाधनों पर प्रभाव डालने से पहले क्लीनअप lógica को सत्यापित करने की अनुमति देता है। * **Level-Triggered Watcher**: सेवा एक क्रॉन‑जैसे लूप पर काम करती है जो हर टिक पर क्लस्टर की स्थिति को खरोंच से फिर से प्राप्त करती है। यह प्रति namespace `helm list` का उपयोग करके ठीक वही देखती है जो एक ऑपरेटर देखता है, रिलीज़ को रिंग जोड़ों (एप्लिकेशन + इन्फ्रास्ट्रक्चर) में समूहित करती है और समय‑से‑जीवन (TTL) लेबल्स पर आधारित गार्बेज कलेक्शन नियम लागू करती है। ## Three Faces 1. **`gemaal` (Service)**: एक इन‑क्लस्टर वॉचर जो निम्नलिखित के लिए जिम्मेदार है: * टेस्ट टेनेंट्स पर TTL हाउसकीपिंग। * रिंग‑पेयर‑अवेयर टीयर‑डाउन (एप्लिकेशन के बाद इन्फ्रास्ट्रक्चर को टियर‑डाउन सुनिश्चित करना)। * अनाथ artefact स्वीप्स (उदाहरण के लिए, S3 सबट्री)। * छह ConnectRPC RPCs को उजागर करना: Plan, ListTenants, Checkout, Extend, Sweep, Resolve। * टेनेंट्स, उम्र, टियर्स और स्वीप इतिहास की निगरानी के लिए एक वेब कंसोल प्रदान करना। 2. **`gemaalctl` (CLI)**: एक कमांड‑लाइन इंटरफ़ेस जो निम्नलिखित के लिए है: * पहचान प्रमाण श्रृंखलाओं और हल किए गए टेनेंट्स की जाँच (`whoami`)। * क्लाइंट‑साइड Helm इंस्टॉल/अनइंस्टॉल को लेज़र लेबल स्टैम्प के साथ प्रबंधित करना। * ConnectRPC के माध्यम से सेवा के साथ बातचीत करके योजना बनाना, टेनेंट की जाँच करना या टेनेंट लाइफ़टाइम बढ़ाना। 3. **Go Library**: टेस्ट हार्नेस द्वारा आयात किया जाता है ताकि: * खड़े टेनेंट्स को हल किया जा सके। * टेस्ट सूट चरणों (बिल्ड, डिप्लॉय, सेटअप, टीयर‑डाउन) को ब्रैकेट किया जा सके। * पहचान समाधान और कॉन्फ़िगरेशन लोडिंग को प्रबंधित किया जा सके। ## Key Features * **Tenant Isolation & Identity**: पहुंचने योग्य नामस्पेस की पहचान करने के लिए टियर लेबल (उदाहरण: `tenancy.truvity.io/tier`) का उपयोग करता है। `gemaal-system` जैसे सिस्टम नामस्पेस को अनदेखा करता है। पहचान ईमेल, kubectl समूहों और AWS SSO सत्रों की एक श्रृंखला के माध्यम से हल की जाती है। * **Garbage Collection Rules**: * अंतिम गतिविधि पर आधारिक एकरूप TTL, प्रति टेनेंट या टियर के लिए कॉन्फ़िगरेबल। * विशिष्ट retenशन आवश्यकताओं के लिए `keep-until` प्राथमिकता। * रिंग‑ऑर्डर्ड टीयर‑डाउन (एप्लिकेशन से पहले इन्फ्रास्ट्रक्चर)। * एक grace period के बाद अनाथ artefacts का संग्रह। * **Authentication & Authorization**: * म्यूटेशंस Kubernetes API (वर्कलोड्स के लिए) या OIDC JWT (मानवों के लिए) के खिलाफ TokenReview के माध्यम से प्रमाणित होती हैं। * Checkout/Extend को मालिक या admin अधिकारों की आवश्यकता होती है। * Sweep ऑपरेशंस केवल admin‑केवल होते हैं। * **Web Console**: एक Vite/React/MUI सिंगल‑पेज एप्लिकेशन जो बाइनरी में एम्बेडेड होता है, जो टेनेंट स्थिति और स्वीप इतिहास को विज़ुअलाइज़ करने के लिए एक फ्लीट कंसोल स्टैक प्रदान करता है। ## Test Harness Integration प्रोजेक्ट `pkg/harness` लाइब्रेरी का उपयोग करके gemaal को अपने Go इंटीग्रेशन टेस्ट में एकीकृत कर सकते हैं। हार्नेस `TestMain` में एक खड़ा टेनेंट एक बार हल करता है, जिससे टेस्ट एक समर्पित नामस्पेस में चल सकते हैं। सेवा Helm रिलीज़ पर स्टैम्प किए गए लेबल के माध्यम से क्लीनअप को हैंडल करती है, इसलिए टेस्ट सूट स्वयं कुछ भी सीधे नहीं बनाता या हटाता है (इंटरिम टीयर‑डाउन हुक्स को छोड़कर)। पर्यावरण चर जैसे `GEMAAL_TEST_SKIP_BUILD`, `GEMAAL_TEST_SKIP_DEPLOY`, और `GEMAAL_TEST_KEEP` CI/CD पाइपलाइंस में टेस्ट जीवनचक्र पर सूक्ष्म नियंत्रण की अनुमति देते हैं। ## AWS Access सेवा मानक AWS क्रेडेंशियल चेन को सपोर्ट करती है, जिसमें EKS Pod Identity और IRSA (IAM Roles for Service Accounts) शामिल हैं। यह AWS Systems Manager (SSM) के साथ artefact स्टोरेज के लिए इंटरैक्ट करती है और STS और pod identidad एंडपॉइंट्स के लिए उपयुक्त अनुमतियों की आवश्यकता होती है। ## Development * **Toolchain**: टास्क मैनेजमेंट के लिए [devbox](https://www.jetify.com/devbox/) और [just](https://just.systems/) का उपयोग करता है। * **Commands**: * `just check`: बिल्ड, टेस्ट, लिंट और वल्नरेबिलिटी चेक चलाता है। * `just generate`: Protobuf परिभाषाओं से कोड को रीजेनरेट करता है। * `just run`: उदाहरण कॉन्फ़िगरेशन के खिलाफ सेवा स्केलेटन चलाता है। ## Status परियोजना प्रारंभिक विकास चरण में है (G4 फेज़)। डिज़ाइन, प्रोटो सर्फ़ेस, क्लाइंट लाइब्रेरी, CLI, और सेवा मौजूद हैं। सेवा अभी तक उत्पादन में तैनात नहीं हुई है; प्रारंभिक तैनाती शैडो मोड में होगी। क्लाइंट API वास्तविक उपयोग में है लेकिन 0.x माइनर वर्ज़न के बीच बदल सकती है। ## License MIT License