Démarrer

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:

• ilum-core : 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
• DuckDB for local-first SQL analytics, with the DuckLake catalog enabled by default
• Ruche Metastore for centralized table metadata
• PostgreSQL as the primary metadata store (MongoDB remains supported for legacy deployments)
• RustFS (default) or MinIO (opt-in) S3-compatible object storage. See Object Storage in Ilum.
• Apache Kyuubi SQL gateway for multi-engine query routing
• Márquez for OpenLineage-based data lineage (default-on)
• Jupyter notebook integration
• REST API for programmatic access

Optional modules enable additional engines, catalogs, and integrations:

• Engines: Trino, Apache Flink
• Catalogues : Project Nessie, Unity Catalog
• Cahiers : JupyterHub (Enterprise), Apache Zeppelin
• Orchestration : Apache Airflow, Kestra, Mage, n8n, Apache NiFi
• BI and visualization: Apache Superset, Streamlit
• AI and ML: MLflow, LangFuse
• Observabilité : 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.

Conditions préalables ​

Pour exécuter Ilum sur votre machine, vous aurez besoin des éléments suivants :

Kubernetes Cluster ​

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 (Guide d’installation ) or Microk8s (Guide d’installation ).

This guide uses Minikube for examples. Verify installation with:

minikube version

Problèmes avec Minikube sur le système d’exploitation Windows ​

Si vous utilisez Windows, vous pouvez rencontrer des problèmes avec Minikube liés au pilote.

Sous Windows, Minikube peut choisir parmi une variété de pilotes (hôtes pour le cluster Kubernetes), cependant, en général, vous souhaitez utiliser soit Hyper-V ou Docker . Si Docker est installé, vous devez soit utiliser Minikube avec le pilote Docker, soit activer la prise en charge intégrée de Kubernetes dans Docker Desktop.

Si vous n’avez pas Docker disponible, vous devez utiliser le pilote Hyper-V. Pour ce faire, vous pouvez consulter ce guide . Gardez à l’esprit que vous devrez accorder à Minikube des privilèges d’administrateur pour interagir avec Hyper-V.

kubectl (Logs & Troubleshooting)​

Install kubectl 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

Barre ​

Helm est un gestionnaire de packages pour Kubernetes qui vous permet de définir, d’installer et de mettre à niveau des applications Kubernetes. Si vous n’avez pas encore installé Helm, vous pouvez trouver des instructions ici .

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 start --cpus 12 --memory 18192 --addons metrics-server 

For minimal Spark workloads:

minikube start --cpus 6 --memory 12288 --addons metrics-server 

Le 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.

Déploiement de Helm ​

Add the Ilum chart repository:

helm repo add ilum https://charts.ilum.cloud 
Mise à jour du référentiel Helm 

Option 1: Data Platform (Recommended)​

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

helm install ilum ilum/ilum \ 
--set ilum-hive-metastore.enabled=vrai \ 
  --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=vrai 

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-core , ilum-ui , ilum-api, Spark 4.x execution, DuckDB, and the DuckLake catalog. No external Hive Metastore or lineage tracking.

helm install 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.

Problèmes d’installation ​

Si vous rencontrez des problèmes liés à l’installation d’Ilum, consultez la section de dépannage de la vision ici or write us an email ([email protected] ).

UI Access​

The Ilum web interface provides job management, resource monitoring, and SQL query capabilities. Default credentials: Admin / Admin

Minikube Service Exposure​

minikube service 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 get nodes -o wide 

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

Port Forwarding (Development)​

kubectl port-forward 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.

Authentication:

• Default admin account: Admin / Admin
• Change credentials via Helm values or UI user management
• LDAP/OAuth2 integration available (see Security docs)

Envoi d’une application Spark sur l’interface utilisateur ​

Maintenant que votre cluster Kubernetes est configuré pour gérer les tâches Spark via Ilum, nous allons soumettre une application Spark. Pour cet exemple, nous allons utiliser l’exemple « SparkPi » de la Spark documentation . 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.

Et c’est tout ! Vous avez réussi à configurer Ilum et à exécuter votre première tâche Spark. N’hésitez pas à explorer l’interface utilisateur et l’API Ilum pour soumettre et gérer des applications Spark. Pour les approches traditionnelles, vous pouvez également utiliser le familier étincelle-soumission commander.

Job Spark interactif avec Scala/Java ​

Les tâches interactives dans Ilum sont des sessions de longue durée qui peuvent exécuter immédiatement les données d’instance de tâche. Ceci est particulièrement utile car il n’est pas nécessaire d’attendre que le contexte Spark soit initialisé à chaque fois. Si plusieurs utilisateurs pointent vers le même ID de tâche, ils interagissent avec le même contexte Spark.

Pour activer les fonctionnalités interactives dans vos travaux Spark existants, vous devez implémenter une interface simple pour la partie de votre code qui doit être interactive. Voici comment vous pouvez procéder :

Tout d’abord, ajoutez la dépendance d’API de tâche Ilum à votre projet :

Gradle ​

Mise en œuvre 'cloud.ilum :ilum-job-api :6.3.0' 

Maven ​

< dépendance > 
    < groupId > cloud.ilum </ groupId > 
    < artefactId > ilum-job-api </ artefactId > 
    < Version > 6.3.0 </ Version > 
</ dépendance > 

SBT ​

libraryDependencies += « cloud.ilum » % « ilum-job-api » % « 6.3.0 » 

Ensuite, mettez en œuvre le Travail trait/interface dans votre job Spark. Voici un exemple :

Scala ​

colis  interactif . job. example

importation  nuage . ilum . job. Travail 
importation  org. apache. étincelle . SQL . SparkSession 

classe  InteractiveJobExample extendsTravail { 

  override Def Courir ( sparkSession: SparkSession , Configuration :  Map[ String,  Quelconque ] ) :  Option[ String]  =  { 
    val userParam = Configuration . getOrElse( « userParam » ,  « Aucun » ) . toString
    Some( s "Hello ${userParam} " ) 
  } 
} 

Java ​

colis  interactif . job. example; 

importation  nuage . ilum . job. Travail ; 
importation  org. apache. étincelle . SQL . SparkSession ; 
importation  scala. Option; 
importation  scala. Some; 
importation  scala. collection. immutable. Map; 
public  classe  InteractiveJobExample implements Travail  { 
    @Override 
    public  Option< String>  Courir ( SparkSession  sparkSession,  Map< String,  Object> Configuration )  { 
        String userParam = Configuration . getOrElse( « userParam » ,  ( )  -> « Aucun » ) ; 
        rendre  Some. apply( "Hello " +  userParam) ; 
    } 
} 

Dans cet exemple, le Courir est remplacée pour accepter une SparkSession et une carte de configuration. Il récupère un paramètre utilisateur à partir de la carte de configuration et renvoie un message d’accueil.

Vous pouvez trouver un exemple similaire sur Lien avec GitHub .

En suivant ce modèle, vous pouvez transformer vos tâches Spark en tâches interactives capables d’exécuter des calculs immédiatement, améliorant ainsi l’interactivité des utilisateurs et réduisant les temps d’attente.

Job Spark interactif avec Python ​

Vous trouverez ci-dessous un exemple de configuration d’un job Spark interactif en Python à l’aide de la commande ilum bibliothèque:

1. Configuration de l’image Spark

   a) Utiliser une image Docker à partir de DockerHub
   Chaque image Spark que nous fournissons sur DockerHub dispose déjà des composants nécessaires intégrés.

   b) Installez le ilum colis
   Si, pour une raison quelconque, votre image Docker n’inclut pas l’icône ilum package ou si vous créez votre propre image personnalisée, vous pouvez l’installer (soit dans le conteneur, soit localement) en exécutant :

   pip install ilum-job-api
   

2. Structure du poste dans ilum \

   La logique du travail Spark est encapsulée dans une classe qui étend IlumJob, en particulier dans sa méthode run

De ilum . API importation IlumJob 

classe  PythonSparkExample ( IlumJob ) : 
    Def  Courir ( même , étincelle , Configuration ) : 
        # Logique du poste ici 

Exemple simple de spark pi interactif :

De aléatoire importation aléatoire 
De opérateur importation ajouter 

De ilum . API importation IlumJob 


classe  SparkPiInteractiveExemple ( IlumJob ) : 

    Def  Courir ( même , étincelle , Configuration ) : 
Partitions =  Int ( Configuration . Avoir ( « Cloisons » ,  '5' ) ) 
n =  100000  * Partitions 

        Def  is_inside_unit_circle ( _ :  Int )  - >  flotter : 
x = aléatoire ( )  *  2  -  1 
y = aléatoire ( )  *  2  -  1 
            rendre  1.0  si x **  2  + y **  2  <=  1  autre  0.0 

compter =  ( 
étincelle . sparkContext . paralléliser ( gamme ( 1 , n +  1 ) , Partitions ) 
            . carte ( is_inside_unit_circle ) 
            . réduire ( ajouter ) 
        ) 

pi_approx =  4.0  * compter / n 
        rendre  f"Pi est à peu près { pi_approx } " 

Vous pouvez trouver un exemple similaire sur Lien avec GitHub .

Envoi d’un travail Interactive Spark sur l’interface utilisateur ​

Après avoir créé un fichier contenant votre code Spark, vous devrez le soumettre à Ilum. Voici comment vous pouvez procéder :

Ouvrez Ilum UI dans votre navigateur et créez un nouveau service :

Dans le Généralités tab mettre le nom d’un service

Dans le Mémoire Tab Choisissez un cluster et configurez vos paramètres de mémoire

Dans le Ressource Onglet Téléchargez votre Spark lime

Presser Envoyer pour appliquer vos modifications, et Ilum créera automatiquement un pod de pilote Spark. Vous pouvez ajuster le nombre de pods d’exécuteur Spark en les mettant à l’échelle selon vos besoins.

Ensuite, allez dans le Charges pour localiser votre emploi. En cliquant sur son nom, vous pouvez accéder à sa vue détaillée. Une fois que le conteneur Spark est prêt, vous pouvez exécuter le travail en spécifiant l’attribut nom_fichier.nomclasse et la définition de paramètres facultatifs au format JSON.

Maintenant, nous devons mettre nom_fichier.nomclasse dans le groupe déposé :

Ilum_interactive_spark_pi. SparkPiInteractiveExemple

et définissez le paramètre slices au format JSON :

{ 
  « partitions » :  5 
} 

Les premières requêtes peuvent prendre quelques secondes en raison de la phase d’initialisation, les unes les autres seront immédiates.

En suivant ces étapes, vous pouvez soumettre et exécuter des travaux Spark interactifs à l’aide d’Ilum. Cette fonctionnalité permet de traiter les données en temps réel, d’améliorer l’interactivité de l’utilisateur et de réduire le temps d’attente des résultats.