Vai al contenuto principale

Iniziare

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
  • Hive Metastore for centralized table metadata
  • PostgreSQL as the primary metadata store (MongoDB remains supported for legacy deployments)
  • MinIO (default) or RustFS (opt-in; planned default in 6.8.0) S3-compatible object storage. See Object Storage in Ilum.
  • Apache Kyuubi SQL gateway for multi-engine query routing
  • Marquez for OpenLineage-based data lineage (default-on)
  • Giove notebook integration
  • REST API for programmatic access

Optional modules enable additional engines, catalogs, and integrations:

  • Engines: Trino, Apache Flink
  • Cataloghi: Project Nessie, Unity Catalog
  • Notebook: JupyterHub (Enterprise), Apache Zeppelin
  • Orchestrazione: Apache Airflow, Kestra, Mage, n8n, Apache NiFi
  • BI and visualization: Apache Superset, Streamlit
  • AI and ML: MLflow, LangFuse
  • Osservabilità: 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.

Prerequisiti​

Per eseguire Ilum sul tuo computer, avrai bisogno di quanto segue:

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 (Guida all'installazione) or Microk8s (Guida all'installazione).

This guide uses Minikube for examples. Verify installation with:

minikube version

Problemi con Minikube su sistema operativo Windows​

Se utilizzi Windows, potresti riscontrare problemi con Minikube relativi al driver.

Su Windows, Minikube può scegliere tra una varietà di driver (host per il cluster Kubernetes), tuttavia, in generale si desidera utilizzare uno dei due Hyper-V o Scaricatore. Se hai installato Docker, è consigliabile utilizzare Minikube con il driver Docker o abilitare il supporto Kubernetes integrato in Docker Desktop.

Se Docker non è disponibile, è consigliabile usare il driver Hyper-V. Per fare ciò, puoi consultare questo guida. Tieni presente che dovrai concedere a Minikube i privilegi di amministratore per interfacciarti con 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:

    ricciolo -LO "https://dl.k8s.io/release/$(ricciolo -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

Timone​

Helm è un gestore di pacchetti per Kubernetes che consente di definire, installare e aggiornare le applicazioni Kubernetes. Se non hai ancora installato Helm, puoi trovare le istruzioni qui.

Cluster Resource Allocation​

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

Configuration Options:

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

Inizio Minikube --cpus 12 --memory 18192 --addons metrics-server

For minimal Spark workloads:

Inizio Minikube --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.

Alternative: Use the Ilum CLI

For a streamlined installation experience, you can use the Ilum CLI instead of manual Helm commands. The CLI wraps Helm and kubectl, providing guided setup, module management, and one-command deployment with ilum quickstart. See the CLI Getting Started guide.

Distribuzione Helm​

Add the Ilum chart repository:

helm repo Aggiungere ilum https://charts.ilum.cloud
Aggiornamento del repo Helm

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

helm install ilum ilum/ilum \
  --mettere ilum-hive-metastore.enabled=vero \
  --mettere ilum-core.metastore.enabled=vero \
  --mettere ilum-core.metastore.type=alveare \
  --mettere ilum-sql.enabled=vero \
  --mettere ilum-core.sql.enabled=vero \
  --mettere globale.lineage.enabled=vero

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.

Problemi di installazione​

In caso di problemi relativi all'installazione di Ilum, sezione di risoluzione dei problemi di visione qui 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 servizio 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.

Autenticazione:

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

Invio di un'applicazione Spark sull'interfaccia utente​

mancia

New to Ilum? Learn the fastest path from install → first job. Take the official Ilum Course.

Ora che il cluster Kubernetes è configurato per gestire i processi Spark tramite Ilum, è possibile inviare un'applicazione Spark. Per questo esempio, si userà l'esempio "SparkPi" di Spark documentazione. You can download the required JAR file from one of these links:

Spark 4 / Scala 2.13: spark-examples_2.13-4.1.1.jar

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

E questo è tutto! Hai configurato correttamente Ilum ed eseguito il tuo primo processo Spark. Sentiti libero di esplorare l'interfaccia utente e l'API di Ilum per l'invio e la gestione delle applicazioni Spark. Per gli approcci tradizionali, è possibile utilizzare anche il familiare scintilla-invio comando.

Processo Spark interattivo con Scala/Java​

I processi interattivi in Ilum sono sessioni a esecuzione prolungata in grado di eseguire immediatamente i dati dell'istanza del processo. Ciò è particolarmente utile in quanto non è necessario attendere l'inizializzazione del contesto Spark ogni volta. Se più utenti puntano allo stesso ID processo, interagiranno con lo stesso contesto Spark.

Per abilitare le funzionalità interattive nei processi Spark esistenti, è necessario implementare un'interfaccia semplice per la parte del codice che deve essere interattiva. Ecco come puoi farlo:

Innanzitutto, aggiungi la dipendenza API del processo Ilum al tuo progetto:

Gradle​

Implementazione 'cloud.ilum:ilum-job-api:6.3.0'

Intenditore​

<dipendenza>
    <groupId>cloud.ilumgroupId>
    <artifactId>ilum-job-apiartifactId>
    <Versione>6.3.0Versione>
dipendenza>

sbt​

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

Quindi, implementa il Lavoro tratto/interfaccia nel processo Spark. Ecco un esempio:

Scala​

pacco interattivo.job.example

importazione nuvola.ilum.job.Lavoro
importazione org.apache.scintilla.SQL.Sessione scintilla

classe InteractiveJobExample extends Lavoro {

  override def Correre(sparkSession: Sessione scintilla, configurazione: Map[String, Qualunque]): Option[String] = {
    val userParam = configurazione.getOrElse("userParam", "Nessuno").toString
    Some(s"Hello ${userParam}")
  }
}

Giava​

pacco interattivo.job.example;

importazione nuvola.ilum.job.Lavoro;
importazione org.apache.scintilla.SQL.Sessione scintilla;
importazione Scala.Option;
importazione Scala.Some;
importazione Scala.collection.immutable.Map;
pubblico classe InteractiveJobExample implements Lavoro {
    @Override
    pubblico Option<String> Correre(Sessione scintilla sparkSession, Map<String, Object> configurazione) {
        String userParam = configurazione.getOrElse("userParam", () -> "Nessuno");
        ritorno Some.apply("Hello " + userParam);
    }
}

In questo esempio, il metodo Correre viene sovrascritto per accettare un metodo Sessione scintilla e una mappa di configurazione. Recupera un parametro utente dalla mappa di configurazione e restituisce un messaggio di saluto.

Puoi trovare un esempio simile su GitHub.

Seguendo questo modello, è possibile trasformare i processi Spark in processi interattivi in grado di eseguire calcoli immediatamente, migliorando l'interattività dell'utente e riducendo i tempi di attesa.

Processo Spark interattivo con Python​

Di seguito è riportato un esempio di come configurare un processo Spark interattivo in Python utilizzando il ilum biblioteca:

  1. Configurazione dell'immagine Spark

    a) Usare un'immagine Docker da DockerHub
    Ogni immagine Spark che forniamo su DockerHub ha già i componenti necessari integrati.

    b) Installare il ilum pacco
    Se, per qualsiasi motivo, l'immagine Docker non include l'opzione ilum o se si crea un'immagine personalizzata, è possibile installarla (all'interno del contenitore o in locale) eseguendo:

    pip install ilum-job-api

  2. Struttura delle mansioni in ilum \

    La logica del processo Spark è incapsulata in una classe che estende IlumJob, in particolare all'interno del metodo run

Da ilum.API importazione IlumJob

classe Esempio di PythonSpark(IlumJob):
    def Correre(stesso, scintilla, configurazione):
        # Logica del lavoro qui

Semplice esempio interattivo di spark pi:

Da aleatorio importazione aleatorio
Da operatore importazione Aggiungere

Da ilum.API importazione IlumJob


classe SparkPiInteractiveExample(IlumJob):

    def Correre(stesso, scintilla, configurazione):
        Partizioni = Int(configurazione.Ottieni('Partizioni', '5'))
        n = 100000 * Partizioni

        def is_inside_unit_circle(_: Int) -> galleggiare:
            x = aleatorio() * 2 - 1
            y = aleatorio() * 2 - 1
            ritorno 1.0 se x ** 2 + y ** 2 <= 1 altro 0.0

        contare = (
            scintilla.sparkContext.parallelizzare(gamma(1, n + 1), Partizioni)
            .mappa(is_inside_unit_circle)
            .ridurre(Aggiungere)
        )

        pi_approx = 4.0 * contare / n
        ritorno f"Pi è approssimativamente {pi_approx}"

Puoi trovare un esempio simile su GitHub.

Invio di un processo Spark interattivo nell'interfaccia utente​

Dopo aver creato un file che contiene il tuo codice Spark, dovrai inviarlo a Ilum. Ecco come puoi farlo:

Apri l'interfaccia utente di Ilum nel tuo browser e crea un nuovo servizio:

Ilum

Nel Generale tab inserire un nome di un servizio

Ilum

Nel Memoria Scegli un cluster e configura le impostazioni di memoria

Ilum

Nel Risorsa Scheda Carica la tua scintilla file

Ilum

Passeggiata Invia per applicare le modifiche e Ilum creerà automaticamente un pod driver Spark. È possibile regolare il numero di pod dell'executor Spark ridimensionandoli in base alle esigenze.

Quindi, vai alla sezione Carichi per individuare il tuo lavoro. Cliccando sul suo nome, è possibile accedere alla sua visualizzazione dettagliata. Una volta che il contenitore Spark è pronto, è possibile eseguire il processo specificando il nomefile.nomeclasse e definendo eventuali parametri facoltativi in formato JSON.

Ilum

Ora dobbiamo mettere nomefile.nomeclasse nella Classe archiviata:

Ilum_interactive_spark_pi. SparkPiInteractiveExample

e definisci il parametro slices in formato JSON:

{
  "Partizioni": 5
}

Le prime richieste potrebbero richiedere alcuni secondi a causa della fase di inizializzazione, l'una con l'altra sarà immediata.

Ilum

Seguendo questi passaggi, è possibile inviare ed eseguire processi Spark interattivi utilizzando Ilum. Questa funzionalità fornisce l'elaborazione dei dati in tempo reale, migliora l'interattività dell'utente e riduce il tempo di attesa dei risultati.

Last updated on