عن المشروع

kestractl هي واجهة سطر أوامر مبنية بلغة Go لإدارة سير عمل Kestra والموارد ذات الصلة. تستهدف Kestra 2.x (مع إصدارات v1 التي تغطي مجموعة ميزات Kestra 1.x الكاملة) ويتم اختبارها ضد Kestra 2.0 و1.3 و1.2 و1.1 و1.0 من خلال مصفوفة اختبارات شاملة؛ المصدر الأساسي للتوافق هو ملف COMPATIBLE_KESTRA_VERSION.properties. يتم التثبيت من خلال سكربت مساعد (curl | bash) يحل أحدث إصدار عبر GitHub REST API، أو تنزيلات مباشرة من GitHub Releases، أو صور حاويات متعددة البنى منشورة على Docker Hub وGHCR (إصدارات Alpine وdistroless)، أو البناء من المصدر مع Go 1.25+. يقبل سكربت التثبيت متغيرات VERSION وINSTALL_DIR، ويمكنه مصادقة استدعاءات GitHub API باستخدام GITHUB_TOKEN لتجنب حدود المعدل المجهولة. يدعم التكوين سياقات متعددة مسماة (dev، staging، prod) مخزنة في ~/.kestractl/config.yaml، مع مصادقة رمزية أو أساسية، ورؤوس HTTP اختيارية مستمرة، ومحدد سياق افتراضي. يتبع أولوية التكوين نموذج العوامل الاثني عشر: أعلام سطر الأوامر، ثم متغيرات البيئة KESTRACTL_*، ثم ملف التكوين، ثم الافتراضيات. تغطي الأعلام العامة --host و--token و--username/--password و--tenant و--header و--output (جدول أو json) و--config و--verbose. تغطي مجموعات الأوامر نطاق Kestra API. التدفقات: list، list-by-namespace، list-deprecated، get، task، deploy (ملف واحد أو دليل، مع --namespace و--override و--fail-fast)، validate (ملف محلي أو دليل أو validate-by-query ضد التدفقات المخزنة)، validate-task، validate-trigger، search-by-source، bulk-update، generate-graph-from-source، graph، expressions، namespace-dependencies، dependencies، enable/disable، delete، delete-by-query، disable-by-query، enable-by-query، export (namespace، by-ids، by-query)، import، namespace-sync، revisions، delete-revisions، concurrency-limits، update-concurrency. يساعد أمر usage-report في التحقق من ترحيل 1.x إلى 2.0، ويخرج validate-by-query برمز غير صفري عند الانتهاكات ليعمل كبوابة CI. عمليات التنفيذ: run (مع --wait)، get، list، watch (يتابع في الوقت الفعلي ويخرج برمز غير صفري عند الفشل)، latest، kill، pause، resume، restart، force-run، replay، replay-with-inputs، unqueue، set-labels، set-labels-bulk، unqueue-bulk، change-status-by-ids، kill-by-query، pause-by-query، resume-by-query، restart-by-query، replay-by-query، force-run-by-query، delete-by-query، unqueue-by-query، set-labels-by-query، update-status-by-query، trigger-webhook (GET/POST/PUT مع لاحقة مسار اختيارية)، flow-graph، flow-info، flow-info-by-id، download-file، file-metadata، eval-expression، change-status، update-taskrun، delete. تستخدم عوامل تصفية الاستعلام صيغة FIELD:OPERATION:VALUE (مثل STATE:EQUALS:RUNNING). المشغلات: list، search-for-flow، enable، disable، unlock، restart، update، delete، بالإضافة إلى متغيرات مجمعة حسب المعرفات (namespace/flowId/triggerId) وحسب الاستعلام، وإدارة backfill (create-backfill مع --start/--end، backfill-pause، backfill-unpause، backfill-delete، ومتغيراتها by-ids وby-query). يمكن تصدير المشغلات كملف CSV. مساحات الأسماء: list، list مع --query، autocomplete، get، create، update، delete، بالإضافة إلى تعيين متغيرات مساحة الاسم عبر --variable أو --variables-file القابلة للتكرار، وعرض inherited-secrets وinherited-variables. مخزن القيم: list، set، update، get، delete، مع الأنواع المدعومة STRING وNUMBER وBOOLEAN وDATETIME وDATE وDURATION وJSON و--ttl اختياري بصيغة ISO 8601. ملفات مساحة الاسم: list (مع --path و--recursive)، get (مع --revision)، upload (ملف واحد أو دليل، مع --override و--fail-fast و--allow-missing-namespace)، delete (مع --recursive و--force). الإضافات: تنزيل جميع ملفات JAR الخاصة بالإضافات لإصدار Kestra معين إلى دليل هدف، مع --concurrency للتنزيلات المتوازية، و--from-config لتهيئة عامل مستقل أو بعيد عن طريق سحب الإضافات الأساسية المطلوبة فقط من تطبيق Kestra application.yaml (التخزين الداخلي، مدير الأسرار، خلفية قائمة الانتظار/المستودع). يوفر أمر list معاينة للإضافات الأساسية المطلوبة دون تنزيل. العمال: registration-tokens generate يعمل دون اتصال لإنتاج رمز تسجيل عامل دون مثيل Kestra. لوحات المعلومات (إصدار المؤسسة): list، get، create من YAML، update، وأوامر إدارة ذات صلة. تغطي مجموعات إضافية التطبيقات والخطط الزرقاء ومجموعات الاختبار وIAM (المستخدمون والمجموعات والأدوار وحسابات الخدمة والروابط والدعوات). تفاصيل تشغيلية: يرسل kestractl بيانات تتبع مجهولة لا تمنع تنفيذ الأوامر أبدًا ويمكن تعطيلها باستخدام KESTRACTL_TELEMETRY_DISABLED=true. يتم تخزين إشعارات التحديث مؤقتًا لمدة 24 ساعة في ~/.kestractl/check_for_new_available_version.json، وتعمل بشكل غير متزامن مع الأمر، ويتم تخطيها في CI وإصدارات التطوير، ويمكن تعطيلها باستخدام KESTRACTL_VERSION_CHECK_DISABLED=true. تعمل صور الحاويات كمستخدم غير جذري، لذا يجب تركيب ملفات التكوين في /home/kestractl/.kestractl (Alpine) أو /home/nonroot/.kestractl (static). تتجاوز وظائف GitLab CI وGitHub Actions الحاوية نقطة الدخول وتشغل السكربتات عبر شل، لذا يُنصح باستخدام علامة Alpine الافتراضية هناك؛ علامة -static لا تحتوي على شل وتعمل فقط مع استدعاءات docker run أو kubectl run.