منصوبے کے بارے میں

# gemaal **gemaal** (ڈچ زبان میں پمپنگ اسٹیشن) ایک آرکسٹریشن ٹول ہے جو مشترکہ Kubernetes ٹیسٹ کلسٹرز کی صحت برقرار رکھنے کے لیے ڈیزائن کیا گیا ہے۔ جس طرح ایک طبعی پمپنگ اسٹیشن مسلسل پانی نکال کر پولڈر کو خشک رکھتا ہے، اسی طرح gemaal خودکار طور پر پرانی، عارضی انسٹالیشنز کا پتہ لگا کر اور انہیں صاف کر کے ٹیسٹ کلسٹر کو قابل استعمال رکھتا ہے۔ یہ یقینی بناتا ہے کہ عارضی ٹیسٹ ٹیننٹس جمع نہ ہوں اور دوسرے صارفین کے لیے ماحول کو خراب نہ کریں۔ ## بنیادی فلسفہ * **نان-بلاکنگ کلین اپ**: gemaal کبھی کچھ انسٹال نہیں کرتا۔ کلائنٹس خود `helm upgrade --install` چلاتے ہیں۔ سروس صرف ان وسائل کو اَن انسٹال اور صاف کرتی ہے جو مزید استعمال میں نہیں ہیں۔ اگر سروس بند ہو جائے تو کلین اپ میں تاخیر ہوتی ہے، لیکن یہ کلائنٹس کے انسٹالیشن لوپ کو کبھی بلاک نہیں کرتی۔ * **شیڈو موڈ**: بطور ڈیفالٹ، سروس شیڈو موڈ (`dryRun: true`) میں چلتی ہے۔ یہ ڈیلیشن ایکشنز کی منصوبہ بندی، رپورٹنگ اور لاگنگ کرتی ہے لیکن واضح طور پر فعال کیے جانے تک انہیں نافذ نہیں کرتی۔ یہ ڈیپلائمنٹ کے دوران حفاظت فراہم کرتا ہے اور آپریٹرز کو لائیو وسائل پر اثر ڈالنے سے پہلے کلین اپ لاجک کی تصدیق کی اجازت دیتا ہے۔ * **لیول-ٹرگرڈ واچر**: سروس ایک کرون نما لوپ پر کام کرتی ہے جو ہر ٹک پر کلسٹر کی حالت کو شروع سے دوبارہ اخذ کرتی ہے۔ یہ فی نیم اسپیس `helm list` استعمال کرتی ہے تاکہ بالکل وہی دیکھے جو ایک آپریٹر دیکھتا ہے، ریلیزز کو رِنگ پیئرز (ایپ + انفرا) میں گروپ کرتی ہے اور ٹائم ٹو لائیو (TTL) لیبلز کی بنیاد پر گاربیج کلیکشن قواعد لاگو کرتی ہے۔ ## تین چہرے 1. **`gemaal` (سروس)**: ایک اِن-کلسٹر واچر جو ذمہ دار ہے: * ٹیسٹ ٹیننٹس پر TTL ہاؤس کیپنگ۔ * رِنگ-پیئر سے آگاہ ٹیئر ڈاؤن (یقینی بنانا کہ انفراسٹرکچر ایپلیکیشنز کے بعد ختم ہو)۔ * یتیم آرٹیفیکٹس کی صفائی (مثلاً S3 سب ٹریز)۔ * چھ ConnectRPC RPCs ظاہر کرنا: Plan, ListTenants, Checkout, Extend, Sweep, Resolve۔ * ٹیننٹس، عمروں، ٹیئرز اور سویپ ہسٹری کی نگرانی کے لیے ایک ویب کنسول فراہم کرنا۔ 2. **`gemaalctl` (CLI)**: ایک کمانڈ لائن انٹرفیس برائے: * شناخت کے ثبوت کی زنجیروں اور حل شدہ ٹیننٹس کی جانچ (`whoami`)۔ * لیجر لیبلز اسٹیمپ کے ساتھ کلائنٹ سائیڈ Helm انسٹال/اَن انسٹال کا انتظام۔ * منصوبہ بندی، چیک آؤٹ، یا ٹیننٹ کی زندگی میں توسیع کے لیے ConnectRPC کے ذریعے سروس کے ساتھ تعامل۔ 3. **Go لائبریری**: ٹیسٹ ہارنسز کے ذریعے امپورٹ کی جاتی ہے برائے: * اسٹینڈنگ ٹیننٹس کو حل کرنا۔ * ٹیسٹ سوٹ کے مراحل (بلڈ، ڈیپلائے، سیٹ اپ، ٹیئر ڈاؤن) کو بریکٹ کرنا۔ * شناخت کی حل پذیری اور کنفیگریشن لوڈنگ کا انتظام۔ ## اہم خصوصیات * **ٹیننٹ آئسولیشن اور شناخت**: قابل رسائی نیم اسپیسز کی شناخت کے لیے ٹیئر لیبلز (مثلاً `tenancy.truvity.io/tier`) استعمال کرتی ہے۔ `gemaal-system` جیسے سسٹم نیم اسپیسز کو نظر انداز کرتی ہے۔ شناخت ای میل، kubectl گروپس، اور AWS SSO سیشنز پر مشتمل ایک زنجیر کے ذریعے حل کی جاتی ہے۔ * **گاربیج کلیکشن قواعد**: * آخری سرگرمی کی بنیاد پر یکساں TTL، فی ٹیننٹ یا ٹیئر قابل ترتیب۔ * مخصوص برقراری کی ضروریات کے لیے `keep-until` کی ترجیح۔ * رِنگ کے مطابق ترتیب وار ٹیئر ڈاؤن (انفراسٹرکچر سے پہلے ایپلیکیشن)۔ * گریس پیریڈ کے بعد یتیم آرٹیفیکٹس کا جمع کرنا۔ * **تصدیق اور اجازت**: * میوٹیشنز Kubernetes API (ورک لوڈز کے لیے) یا OIDC JWT (انسانوں کے لیے) کے خلاف TokenReview کے ذریعے تصدیق کرتی ہیں۔ * Checkout/Extend کے لیے مالک یا ایڈمن حقوق درکار ہیں۔ * Sweep آپریشنز صرف ایڈمن کے لیے ہیں۔ * **ویب کنسول**: بائنری میں ایمبیڈڈ ایک Vite/React/MUI سنگل پیج ایپلیکیشن، جو ٹیننٹ کی حالت اور سویپ ہسٹری کو دیکھنے کے لیے فلیٹ کنسول اسٹیک فراہم کرتی ہے۔ ## ٹیسٹ ہارنس انٹیگریشن پروجیکٹس `pkg/harness` لائبریری استعمال کرتے ہوئے gemaal کو اپنے Go انٹیگریشن ٹیسٹس میں ضم کر سکتے ہیں۔ ہارنس `TestMain` میں ایک بار اسٹینڈنگ ٹیننٹ حل کرتا ہے، جس سے ٹیسٹس ایک مخصوص نیم اسپیس کے اندر چل سکتے ہیں۔ سروس Helm ریلیزز پر لگے لیبلز کے ذریعے کلین اپ سنبھالتی ہے، لہذا ٹیسٹ سوٹ خود براہ راست کچھ بھی بناتا یا حذف نہیں کرتا (سوائے عبوری ٹیئر ڈاؤن ہکس کے)۔ `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 اور پوڈ آئیڈینٹٹی اینڈ پوائنٹس کے لیے مناسب اجازتوں کی ضرورت ہوتی ہے۔ ## ڈیولپمنٹ * **ٹول چین**: ٹاسک مینجمنٹ کے لیے [devbox](https://www.jetify.com/devbox/) اور [just](https://just.systems/) استعمال کرتی ہے۔ * **کمانڈز**: * `just check`: بلڈ، ٹیسٹ، لنٹ، اور کمزوری کی جانچ چلاتی ہے۔ * `just generate`: Protobuf تعریفات سے کوڈ دوبارہ جنریٹ کرتی ہے۔ * `just run`: مثال کنفیگریشن کے خلاف سروس اسکیلیٹن چلاتی ہے۔ ## حیثیت پروجیکٹ ابتدائی ڈیولپمنٹ (G4 مرحلہ) میں ہے۔ ڈیزائن، پروٹو سطح، کلائنٹ لائبریری، CLI، اور سروس موجود ہیں۔ سروس نے ابھی تک پروڈکشن ڈیپلائمنٹ نہیں دیکھی؛ ابتدائی ڈیپلائمنٹس شیڈو موڈ میں ہوں گی۔ کلائنٹ API حقیقی استعمال میں ہے لیکن 0.x مائنر ورژنز کے درمیان تبدیل ہو سکتی ہے۔ ## لائسنس MIT لائسنس