ابدأ الآن

This guide covers deploying Ilum on Kubernetes and submitting your first Spark job.

Installation Architecture​

Ilum follows a modular architecture where core platform services are separated from optional engines, catalogs, and integrations. The base installation provides:

• إيلوم كور : Main backend (REST API, jobs, multi-engine SQL, lineage, security)
• ILUM-UI : Web frontend (SQL Editor, Table Explorer, Lineage, Workloads)
• ilum-api: Module-management microservice that installs, upgrades, and disables optional modules at runtime via Helm
• Apache Spark 4.x job orchestration on Kubernetes
• بطة دي بي for local-first SQL analytics, with the DuckLake catalog enabled by default
• Hive Metastore for centralized table metadata
• PostgreSQL as the primary metadata store (MongoDB remains supported for legacy deployments)
• RustFS (default) or ميني آيو (opt-in) S3-compatible object storage. See Object Storage in Ilum.
• Apache Kyuubi SQL gateway for multi-engine query routing
• ماركيز for OpenLineage-based data lineage (default-on)
• جوبيتر notebook integration
• REST API for programmatic access

Optional modules enable additional engines, catalogs, and integrations:

• Engines: Trino, Apache Flink
• كتالوجات : Project Nessie, Unity Catalog
• دفاتر الملاحظات : JupyterHub (Enterprise), Apache Zeppelin
• تزامن : Apache Airflow, Kestra, Mage, n8n, Apache NiFi
• BI and visualization: Apache Superset, Streamlit
• AI and ML: MLflow, LangFuse
• قابلية الملاحظة : Kube Prometheus stack, Loki, Promtail
• Identity: Ory Hydra (Ilum as IdP), OpenLDAP

Resource Planning:

• Base deployment: 8-12 GB RAM, 6 CPU cores
• With Hive Metastore, Marquez lineage, Kyuubi, and PostgreSQL: 18 GB RAM, 12 CPU cores
• Production workloads: Size based on concurrent executor requirements across all enabled engines

Module selection impacts pod count, storage IOPS, and network traffic. Each module runs in dedicated pods with configurable resource limits.

المتطلبات المسبقه ​

لتشغيل Ilum على جهازك ، ستحتاج إلى ما يلي:

مجموعة Kubernetes ​

Ilum deploys exclusively on Kubernetes using Helm charts. Any CNCF-compliant Kubernetes distribution works:

Supported Platforms:

• Local development: Minikube, Microk8s, K3s, Docker Desktop
• Cloud-managed: GKE, EKS, AKS, DigitalOcean Kubernetes
• Self-hosted: K8s on bare metal, OpenShift, Rancher

Architecture Support:

• Multi-arch container images (amd64, arm64)
• Tested on Linux, macOS (M1/M2), Windows WSL2

Quick Local Setup: For development/testing without an existing cluster, use Minikube (دليل التثبيت ) or Microk8s (دليل التثبيت ).

This guide uses Minikube for examples. Verify installation with:

minikube version

مشكلات مع Minikube على نظام التشغيل Windows ​

إذا كنت تستخدم Windows ، فقد تواجه مشكلات مع Minikube تتعلق ببرنامج التشغيل.

على Windows ، يمكن ل Minikube الاختيار من بين مجموعة متنوعة من برامج التشغيل (مضيفات مجموعة Kubernetes) ، ومع ذلك ، بشكل عام ، تريد استخدام أي منهما هايبر في أو عامل الإرساء . إذا كان لديك Docker مثبتا ، يجب عليك إما استخدام Minikube مع برنامج تشغيل Docker أو تمكين دعم Kubernetes المدمج في Docker Desktop.

إذا لم يكن لديك Docker متاحا ، فيجب عليك استخدام برنامج تشغيل Hyper-V. للقيام بذلك ، يمكنك الرجوع إلى هذا دليل . ضع في اعتبارك أنك ستحتاج إلى منح امتيازات مسؤول Minikube للتفاعل مع Hyper-V.

kubectl (Logs & Troubleshooting)​

Install كوبيكتل to inspect Ilum resources and stream logs.

Install

Guide

• macOS: brew install kubectl

• Windows: winget install -e --id Kubernetes.kubectl (or) choco install kubernetes-cli

• Linux:

  curl -LO "https://dl.k8s.io/release/$(curl -Ls https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
  sudo install -m 0755 kubectl /usr/local/bin/kubectl
  

Quick use

kubectl get pods -n <ns>
kubectl logs -n <ns> <pod> --all-containers -f
kubectl describe pod -n <ns> <pod>
kubectl get events -n <ns> --sort-by=.lastTimestamp

دومان ​

Helm هو مدير حزم ل Kubernetes يسمح لك بتحديد تطبيقات Kubernetes وتثبيتها وترقيتها. إذا لم تكن قد قمت بتثبيت Helm حتى الآن ، فيمكنك العثور على التعليمات هنا .

Cluster Resource Allocation​

Minikube resource allocation determines available capacity for Spark executors and Ilum services.

Configuration Options:

For full module testing (metadata, lineage, SQL):

بدء تشغيل minikube - وحدة المعالجة المركزية 12 - الذاكرة 18192 - الإضافات المقاييس الخادم 

For minimal Spark workloads:

بدء minikube - وحدة المعالجة المركزية 6 - الذاكرة 12288 - الإضافات المقاييس الخادم 

ال metrics-server addon exposes pod-level CPU/memory metrics to the Ilum UI dashboard.

Minikube Limitations:

• Single-node cluster (no distributed executor scheduling)
• Suitable for functional testing, not performance benchmarks

For production deployments, see Production Setup.

نشر الدفة ​

Add the Ilum chart repository:

خوذة الريبو إضافة ILUM https://charts.ilum.cloud 
تحديث Helm Repo 

Option 1: Data Platform (Recommended)​

Includes Hive Metastore for table metadata, the multi-engine SQL gateway (Kyuubi), and OpenLineage data tracking.

Helm تثبيت ilum ilum / ilum \ 
--set ilum-hive-metastore.enabled=true \ 
  --set ilum-core.metastore.enabled=true \
  --set ilum-core.metastore.type=hive \
--set ilum-sql.enabled=true \ 
--set ilum-core.sql.enabled=true \ 
--set global.lineage.enabled=true 

Capabilities enabled:

• Centralized Hive Metastore (compatible with Spark, Trino, DuckDB, Flink)
• Multi-engine SQL execution via Kyuubi (Spark and Trino out of the box; DuckDB available locally)
• Automatic lineage capture via OpenLineage, visualized in Marquez
• Table and column-level lineage in the Ilum UI

Resource overhead: ~8 GB RAM, 6 CPU cores for metadata, lineage, and SQL gateway services.

Option 2: Minimal Deployment​

Minimal deployment for development and testing. Includes إيلوم كور , ILUM-UI , ilum-api, Spark 4.x execution, DuckDB, and the DuckLake catalog. No external Hive Metastore or lineage tracking.

Helm تثبيت ilum ilum / ilum 

Use case: Development, testing, ephemeral workloads where table schemas are managed externally.

Option 3: Custom Module Selection​

Use the module selector to generate Helm commands with specific integrations (Trino, Nessie, Unity Catalog, Airflow, Superset, MLflow, LangFuse, etc.). Optional modules can also be enabled and disabled at runtime through the in-product Modules registry, which is backed by the ilum-api microservice.

Deployment time: Services typically reach ready state within 2-6 minutes. Monitor with:

kubectl get pods -w

For advanced configuration options, see Helm chart documentation.

مشاكل التثبيت ​

في حال كان لديك أي مشاكل تتعلق بتثبيت Ilum ، قسم استكشاف أخطاء الرؤية وإصلاحها هنا or write us an email ([البريد الإلكتروني محمي] ).

UI Access​

The Ilum web interface provides job management, resource monitoring, and SQL query capabilities. Default credentials: المشرف / المشرف

Minikube Service Exposure​

خدمة Minikube ILUM-UI 

Returns cluster-accessible URL (e.g., http://192.168.49.2:31777).

NodePort (Default)​

The UI service is exposed via NodePort on 31777 by default. Find your node IP:

kubectl الحصول على العقد -o واسعة 

Access at http://<NODE_IP>:31777.

Port Forwarding (Development)​

المنفذ إلى الأمام SVC / ILUM-UI 9777: 9777 

Access at http://localhost:9777 .

Ingress Controller (Production)​

For production deployments, configure an Ingress resource with TLS termination. See Ingress configuration guide for details.

المصادقه:

• Default admin account: المشرف / المشرف
• Change credentials via Helm values or UI user management
• LDAP/OAuth2 integration available (see Security docs)

تقديم طلب Spark على واجهة المستخدم ​

الآن بعد أن تم تكوين مجموعة Kubernetes الخاصة بك للتعامل مع مهام Spark عبر Ilum، دعنا نرسل تطبيق Spark. في هذا المثال ، سنستخدم مثال "SparkPi" من Spark توثيق . You can download the required JAR file from one of these links:

Ilum will create a Spark driver pod using the Spark 4.x docker image. The number of Spark executor pods can be scaled to multiple nodes as per your requirements.

وهذا كل شيء! لقد نجحت في إعداد Ilum وتشغيل أول وظيفة لك في Spark. لا تتردد في استكشاف واجهة مستخدم Ilum وواجهة برمجة التطبيقات لإرسال تطبيقات Spark وإدارتها. بالنسبة للأساليب التقليدية ، يمكنك أيضا استخدام المألوف شرارة تقديم أمر.

وظيفة شرارة تفاعلية مع Scala / Java ​

الوظائف التفاعلية في Ilum هي جلسات طويلة الأمد يمكنها تنفيذ بيانات مثيل الوظيفة على الفور. هذا مفيد بشكل خاص حيث لا داعي لانتظار تهيئة سياق Spark في كل مرة. إذا أشار عدة مستخدمين إلى نفس معرف الوظيفة، فسيتفاعلون مع سياق Spark نفسه.

لتمكين الإمكانات التفاعلية في وظائف Spark الحالية، ستحتاج إلى تنفيذ واجهة بسيطة لجزء التعليمات البرمجية الخاص بك الذي يجب أن يكون تفاعليا. إليك كيفية القيام بذلك:

أولا، أضف تبعية واجهة برمجة تطبيقات وظيفة Ilum إلى مشروعك:

جرادل ​

التنفيذ 'cloud.ilum:ilum-job-api:6.3.0' 

مخضرم ​

< تبعية > 
    < معرف المجموعة > كلاود.إيلوم </ معرف المجموعة > 
    < معرف القطعة الأثرية > ilum-job-api </ معرف القطعة الأثرية > 
    < الإصدار > 6.3.0 </ الإصدار > 
</ تبعية > 

SBT ​

libraryDependencies += "cloud.ilum" ٪ "ilum-job-api" ٪ "6.3.0" 

ثم قم بتنفيذ مهمة سمة / واجهة في وظيفة Spark الخاصة بك. فيما يلي مثال:

سكالا ​

حزمة  تبادلي . job. example

استورد  سحابة . إيلوم . job. مهمة 
استورد  org. apache. شراره . SQL . جلسة سبارك 

فصل  InteractiveJobExample extendsمهمة { 

  override مواطنه ركض ( sparkSession: جلسة سبارك , التكوين :  Map[ String,  أي ] ) :  Option[ String]  =  { 
    val userParam = التكوين . getOrElse( "userParam" ,  "لا شيء" ) . toString
    Some( s "Hello ${userParam} " ) 
  } 
} 

جاوة ​

حزمة  تبادلي . job. example; 

استورد  سحابة . إيلوم . job. مهمة ; 
استورد  org. apache. شراره . SQL . جلسة سبارك ; 
استورد  سكالا . Option; 
استورد  سكالا . Some; 
استورد  سكالا . collection. immutable. Map; 
علني  فصل  InteractiveJobExample implements مهمة  { 
    @Override 
    علني  Option< String>  ركض ( جلسة سبارك  sparkSession,  Map< String,  Object> التكوين )  { 
        String userParam = التكوين . getOrElse( "userParam" ,  ( )  -> "لا شيء" ) ; 
        أعاد  Some. apply( "Hello " +  userParam) ; 
    } 
} 

في هذا المثال، الرقم ركض تم تجاوز الطريقة لقبول جلسة سبارك وخريطة التكوين. يسترد معلمة مستخدم من خريطة التكوين ويرجع رسالة ترحيب.

يمكنك العثور على مثال مماثل على جيت هب .

باتباع هذا النمط، يمكنك تحويل مهام Spark إلى وظائف تفاعلية يمكنها تنفيذ العمليات الحسابية على الفور، وتحسين تفاعل المستخدم وتقليل أوقات الانتظار.

وظيفة Spark التفاعلية مع Python ​

فيما يلي مثال على كيفية تكوين وظيفة Spark تفاعلية في Python باستخدام إيلوم مكتبة:

1. إعداد صورة Spark

   a) استخدام صورة Docker من DockerHub
   كل صورة Spark نقدمها على دوكر هب يحتوي بالفعل على المكونات الضرورية المدمجة.

   b) قم بتثبيت إيلوم حزمة
   إذا كانت صورة Docker الخاصة بك، لأي سبب من الأسباب، لا تتضمن إيلوم أو إذا قمت بإنشاء صورة مخصصة خاصة بك ، فيمكنك تثبيتها (إما داخل الحاوية أو محليا) عن طريق تشغيل:

   pip install ilum-job-api
   

2. الهيكل الوظيفي في إيلوم \

   يتم تغليف منطق وظيفة Spark في فئة توسع IlumJob، لا سيما ضمن طريقة التشغيل الخاصة بها

من إيلوم . واجهة برمجة التطبيقات استورد Ilum Job 

فصل  PythonSparkExample ( Ilum Job ) : 
    مواطنه  ركض ( ذات , شراره , التكوين ) : 
        # منطق الوظيفة هنا 

مثال بسيط على spark pi التفاعلي:

من عشوائي استورد عشوائي 
من المشغل استورد جمع 

من إيلوم . واجهة برمجة التطبيقات استورد Ilum Job 


فصل  SparkPiInteractiveExample ( Ilum Job ) : 

    مواطنه  ركض ( ذات , شراره , التكوين ) : 
اقسام =  الباحث ( التكوين . حصل ( "أقسام" ,  '5' ) ) 
n =  100000  * اقسام 

        مواطنه  is_inside_unit_circle ( _ :  الباحث )  - >  طفا : 
x = عشوائي ( )  *  2  -  1 
y = عشوائي ( )  *  2  -  1 
            أعاد  1.0  لو x **  2  + y **  2  <=  1  اخر  0.0 

عد =  ( 
شراره . sparkContext . موازاة ( نطاق ( 1 , n +  1 ) , اقسام ) 
            . خريطة ( is_inside_unit_circle ) 
            . قلل ( جمع ) 
        ) 

pi_approx =  4.0  * عد / n 
        أعاد  f "Pi تقريبا { pi_approx } " 

يمكنك العثور على مثال مماثل على جيت هب .

إرسال وظيفة Spark تفاعلية على واجهة المستخدم ​

بعد إنشاء ملف يحتوي على رمز Spark الخاص بك ، ستحتاج إلى إرساله إلى Ilum. إليك كيفية القيام بذلك:

افتح واجهة مستخدم Ilum في متصفحك وقم بإنشاء خدمة جديدة:

في المربع عام علامة التبويب ضع اسم خدمة

في المربع ذاكرة اختيار مجموعة وإعداد إعدادات الذاكرة

في المربع مورد علامة التبويب تحميل Spark الخاص بك ملف

كبس إرسال لتطبيق التغييرات الخاصة بك ، وسيقوم Ilum تلقائيا بإنشاء جراب برنامج تشغيل Spark. يمكنك ضبط عدد جراب منفذ Spark عن طريق تحجيمها حسب الحاجة.

بعد ذلك، انتقل إلى الرمز عبء العمل لتحديد موقع وظيفتك. من خلال النقر على اسمه ، يمكنك الوصول إلى طريقة العرض التفصيلية الخاصة به. بمجرد أن تصبح حاوية Spark جاهزة، يمكنك تشغيل المهمة عن طريق تحديد اسم الملف.اسم الفئة وتحديد أي معلمات اختيارية بتنسيق JSON.

الآن علينا أن نضع اسم الملف.اسم الفئة في الفئة المقدمة:

Ilum_interactive_spark_pi. SparkPiInteractiveExample

وحدد معلمة الشرائح بتنسيق JSON:

{ 
  "أقسام" :  5 
} 

قد تستغرق الطلبات الأولى بضع ثوان بسبب مرحلة التهيئة ، وسيكون كل منها فوريا.

باتباع هذه الخطوات، يمكنك إرسال مهام Spark التفاعلية وتشغيلها باستخدام Ilum. توفر هذه الوظيفة معالجة البيانات في الوقت الفعلي ، وتعزز تفاعل المستخدم ، وتقلل من الوقت الذي يقضيه في انتظار النتائج.