عن المشروع

# gemaal **gemaal** (كلمة هولندية تعني محطة ضخ) هي أداة تنسيق مصممة للحفاظ على صحة عناقيد اختبار Kubernetes المشتركة. وكما تحافظ محطة الضخ الفعلية على جفاف الأراضي المستصلحة عبر إزالة المياه باستمرار، يحافظ gemaal على قابلية استخدام عنقود الاختبار عبر الكشف التلقائي عن عمليات التثبيت المؤقتة القديمة وتنظيفها. وهو يضمن عدم تراكم المستأجرين المؤقتين للاختبار وتدهور البيئة لمستخدمين آخرين. ## الفلسفة الأساسية * **تنظيف غير معطِّل**: لا يقوم gemaal أبدًا بتثبيت أي شيء. يشغّل العملاء `helm upgrade --install` بأنفسهم. الخدمة تقوم فقط بإلغاء التثبيت وكنس الموارد التي لم تعد قيد الاستخدام. إذا توقفت الخدمة، يتأخر التنظيف، لكنها لا تعطّل أبدًا حلقة التثبيت للعملاء. * **وضع الظل**: افتراضيًا، تعمل الخدمة في وضع الظل (`dryRun: true`). فهي تخطط وتُبلّغ وتُسجّل إجراءات الحذف لكنها لا تنفذها حتى يتم تمكينها صراحةً. يوفر ذلك أمانًا أثناء النشر ويسمح للمشغلين بالتحقق من منطق التنظيف قبل أن يؤثر على الموارد الحية. * **مراقب مُشغَّل بالمستوى**: تعمل الخدمة على حلقة شبيهة بـ cron تعيد اشتقاق حالة العنقود من الصفر في كل دورة. وتستخدم `helm list` لكل مساحة اسم لترى بالضبط ما يراه المشغل، وتجمّع الإصدارات في أزواج حلقات (تطبيق + بنية تحتية) وتطبّق قواعد جمع القمامة بناءً على تسميات مدة الصلاحية (TTL). ## ثلاثة أوجه 1. **`gemaal` (الخدمة)**: مراقب داخل العنقود مسؤول عن: * تدبير TTL على مستأجري الاختبار. * تفكيك واعٍ بأزواج الحلقات (ضمان تفكيك البنية التحتية بعد التطبيقات). * كنس القطع اليتيمة (مثل الأشجار الفرعية لـ S3). * كشف ستة إجراءات ConnectRPC RPC: Plan وListTenants وCheckout وExtend وSweep وResolve. * توفير وحدة تحكم ويب لمراقبة المستأجرين والأعمار والمستويات وسجل الكنس. 2. **`gemaalctl` (واجهة سطر الأوامر)**: واجهة سطر أوامر من أجل: * فحص سلاسل أدلة الهوية والمستأجرين المحلولين (`whoami`). * إدارة عمليات تثبيت/إلغاء تثبيت Helm من جانب العميل مع ختم تسميات السجل. * التفاعل مع الخدمة عبر ConnectRPC للتخطيط أو الحجز أو تمديد أعمار المستأجرين. 3. **مكتبة Go**: تُستورد بواسطة أدوات الاختبار من أجل: * حل المستأجرين الدائمين. * تأطير مراحل مجموعة الاختبار (البناء، النشر، الإعداد، التفكيك). * إدارة حل الهوية وتحميل الإعدادات. ## الميزات الرئيسية * **عزل المستأجر والهوية**: يستخدم تسميات المستوى (مثل `tenancy.truvity.io/tier`) لتحديد مساحات الأسماء القابلة للوصول. يتجاهل مساحات أسماء النظام مثل `gemaal-system`. تُحل الهوية عبر سلسلة تشمل البريد الإلكتروني ومجموعات kubectl وجلسات AWS SSO. * **قواعد جمع القمامة**: * TTL موحّد بناءً على آخر نشاط، قابل للتهيئة لكل مستأجر أو مستوى. * أسبقية `keep-until` لاحتياجات الاحتفاظ المحددة. * تفكيك مرتّب بالحلقات (التطبيق قبل البنية التحتية). * جمع القطع اليتيمة بعد فترة سماح. * **المصادقة والتفويض**: * تُصادق التعديلات عبر TokenReview مقابل Kubernetes API (لأحمال العمل) أو OIDC JWT (للبشر). * يتطلب Checkout/Extend حقوق المالك أو المسؤول. * عمليات Sweep مخصصة للمسؤولين فقط. * **وحدة تحكم الويب**: تطبيق صفحة واحدة بـ Vite/React/MUI مضمّن في الملف التنفيذي، يوفر حزمة وحدة تحكم أسطول لتصور حالة المستأجرين وسجل الكنس. ## تكامل أداة الاختبار يمكن للمشاريع دمج gemaal في اختبارات تكامل Go الخاصة بها باستخدام مكتبة `pkg/harness`. تحل الأداة مستأجرًا دائمًا مرة واحدة في `TestMain`، ما يسمح للاختبارات بالعمل داخل مساحة اسم مخصصة. تتولى الخدمة التنظيف عبر تسميات مختومة على إصدارات Helm، لذا لا تنشئ مجموعة الاختبار نفسها أو تحذف أي شيء مباشرةً (باستثناء خطافات التفكيك المؤقتة). تسمح متغيرات البيئة مثل `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 وهوية الحاوية. ## التطوير * **سلسلة الأدوات**: تستخدم [devbox](https://www.jetify.com/devbox/) و[just](https://just.systems/) لإدارة المهام. * **الأوامر**: * `just check`: يشغّل البناء والاختبار والفحص وفحوصات الثغرات. * `just generate`: يعيد توليد الكود من تعريفات Protobuf. * `just run`: يشغّل هيكل الخدمة مقابل إعدادات مثال. ## الحالة المشروع في مرحلة تطوير مبكرة (مرحلة G4). التصميم وسطح proto ومكتبة العميل وواجهة سطر الأوامر والخدمة كلها جاهزة. لم تشهد الخدمة بعد نشرًا إنتاجيًا؛ ستكون عمليات النشر الأولية في وضع الظل. واجهة برمجة تطبيقات العميل قيد الاستخدام الفعلي لكنها قد تتغير بين الإصدارات الفرعية 0.x. ## الترخيص ترخيص MIT