JupyterHub¶

Aperçu¶

JupyterHub fournit l'environnement de notebooks multi-utilisateurs pour AKKO, accessible à https://lab.akko.local. Il authentifie les utilisateurs via Keycloak SSO et lance des pods Kubernetes individuels (akko-notebook) par utilisateur, chacun équipé d'une boîte à outils complète pour l'ingénierie et l'analyse de données.

Architecture¶

                Keycloak SSO
                    |
           +--------+--------+
           |   JupyterHub    |  (image akko-jupyterhub)
           |  lab.akko.local   |
           +--------+--------+
                    |  KubeSpawner
        +-----------+-----------+
        |           |           |
   +---------+ +---------+ +---------+
   | alice   | |  bob    | | carol   |  (conteneurs akko-notebook)
   | notebook| | notebook| | notebook|
   +---------+ +---------+ +---------+

JupyterHub fonctionne comme un service hub central derrière Traefik.
KubeSpawner crée un pod akko-notebook par utilisateur authentifié.
Chaque pod utilisateur dispose de 6 Go de RAM et 2 CPU maximum.
Le travail de chaque utilisateur est persisté dans un PersistentVolumeClaim : akko-user-{username}.

Noyaux disponibles¶

Noyau	Version	Notes
Python 3	base scipy-notebook	Noyau par défaut, stack données complet
R (IRkernel)	R système + tidyverse, sf, DBI, RPostgres	Prêt pour le géospatial
Julia (IJulia)	1.11.3	Packages DataFrames, CSV pré-installés
Scala 2.13 (Almond)	0.14.0-RC15	Pour les développeurs Spark Scala, REPL Ammonite

Packages Python pré-installés¶

L'image akko-notebook embarque un stack complet d'ingénierie de données :

Ingénierie de données & Lakehouse¶

Package	Fonction
`pyspark` 3.5.1	Client Spark Connect
`trino`	Pilote Python DB-API pour Trino
`pyiceberg[s3fs]`	Client Python Apache Iceberg
`duckdb`	Base de données analytique embarquée
`polars`	Bibliothèque DataFrame rapide
`pandas`	Bibliothèque DataFrame (depuis la base scipy-notebook)
`pyarrow`	Format colonnaire en mémoire
`dbt-core` + `dbt-trino`	Framework de transformation de données
`sqlalchemy` + `sqlalchemy-trino`	Boîte à outils SQL avec dialecte Trino
`boto3`	SDK AWS/object storage S3
`psycopg2-binary`	Pilote PostgreSQL

Analytique & Visualisation¶

Package	Fonction
`altair`	Visualisation statistique déclarative
`plotly`	Graphiques interactifs
`folium`	Cartes Leaflet.js
`geopandas`	DataFrames géospatiales
`great-expectations`	Validation de la qualité des données

IA & LLM¶

Package	Fonction
`jupyter-ai[all]`	Assistant IA dans JupyterLab
`langchain` + `langchain-ollama`	Framework d'orchestration LLM
`langchain-community`	Intégrations communautaires

Extensions JupyterLab¶

Extension	Fonction
`jupyterlab-git`	Intégration Git
`jupyterlab-lsp`	Language Server Protocol
`jupyterlab-execute-time`	Affichage du temps d'exécution des cellules
`jupyterlab-code-formatter`	Formatage Black + isort
`jupyterlab-favorites`	Barre latérale de fichiers favoris
`jupyterlab-mermaid`	Rendu de diagrammes Mermaid (architecture, flux, diagrammes ER) directement dans les notebooks
`jupyter-resource-usage`	Indicateur d'utilisation RAM/CPU
`ipywidgets`	Widgets interactifs

code-server (VS Code dans le navigateur)¶

Chaque conteneur notebook inclut code-server, offrant une expérience VS Code complète dans le navigateur. Il est accessible via le lanceur JupyterLab ou le chemin proxy /code-server.

Extensions pré-installées :

Langages : Python, R, Julia, Scala (kernel Almond), Go
Données : SQLTools (pilotes PostgreSQL + Trino), Rainbow CSV, Data Table viewer
dbt : dbt Power User
DevOps : Docker, REST Client, GitLens, Error Lens
Quarto : Extension Quarto pour la rédaction de rapports
Diagrammes : Mermaid (diagrammes inline dans les notebooks et les cellules Markdown)
Thème : Dracula + Material Icon Theme

Extensions système

Les extensions sont installées dans /opt/code-server-extensions (système, immuables) et liées symboliquement dans le répertoire personnel de chaque utilisateur au démarrage du conteneur via un hook before-notebook.d.

Publication Quarto¶

Quarto (v1.6.43) est pré-installé pour la rédaction et le rendu de rapports de données. La sortie HTML rendue peut être écrite dans le volume published-reports, qui est partagé avec le service AKKO Docs à l'adresse https://docs.akko.local.

# Rendre un rapport Quarto depuis un terminal notebook
quarto render 04-akko-banking-report.qmd --to html \
  --output-dir ~/published-reports/

Notebooks partagés¶

Le répertoire notebooks/ de l'hôte est monté en lecture seule dans chaque conteneur utilisateur à l'emplacement /home/{username}/work/notebooks/. Cela fournit des notebooks de référence partagés :

Notebook	Description
`akko-banking-demo.ipynb`	Démo bancaire de bout en bout (Spark Connect + Trino)
`rag-pipeline-demo.ipynb`	Pipeline RAG (Ollama + pgvector + LangChain)
`spark-iceberg-demo.ipynb`	Opérations sur les tables Spark Iceberg

Montage en lecture seule

Les notebooks partagés sont en lecture seule. Pour les modifier, copiez-les d'abord dans votre répertoire work/.

Variables d'environnement¶

Les variables d'environnement suivantes sont injectées dans chaque conteneur notebook utilisateur par le spawner JupyterHub :

Variable	Valeur par défaut	Fonction
`TRINO_HOST`	`trino`	Nom d'hôte du coordinateur Trino
`TRINO_PORT`	`8080`	Port HTTP de Trino
`SPARK_REMOTE`	`sc://spark-connect:15002`	Point d'accès gRPC Spark Connect
`OLLAMA_HOST`	`http://ollama:11434`	API LLM Ollama
`MINIO_ENDPOINT`	`http://minio:9000`	Point d'accès S3 object storage
`POSTGRES_AKKO_PASSWORD`	(depuis `.env`)	Mot de passe PostgreSQL
`POLARIS_ROOT_SECRET`	(depuis `.env`)	Secret OAuth2 Polaris
`MINIO_ROOT_USER`	(depuis `.env`)	Clé d'accès object storage
`MINIO_ROOT_PASSWORD`	(depuis `.env`)	Clé secrète object storage
`DBT_PROFILES_DIR`	`/home/{user}/work/dbt`	Emplacement des profils dbt
`NB_USER`	(dynamique)	Nom d'utilisateur depuis Keycloak

Authentification & RBAC¶

JupyterHub utilise Keycloak SSO via le GenericOAuthenticator (flux d'autorisation OpenID Connect par code).

Client ID : jupyterhub
Scopes : openid, profile, email
Claim du nom d'utilisateur : preferred_username
Auto-login : activé (redirige directement vers Keycloak)
Utilisateurs admin : configurable via la variable d'environnement JUPYTERHUB_ADMIN_USER

Groupes Keycloak

Les groupes Keycloak (akko-admin, akko-engineer, akko-analyst, akko-viewer) contrôlent l'accès à travers la plateforme AKKO. JupyterHub autorise actuellement tous les utilisateurs authentifiés (allow_all = True), mais les groupes Keycloak se propagent aux services en aval comme Trino pour le RBAC à granularité fine.

Limites de ressources¶

Ressource	Limite
Mémoire	6 Go par conteneur utilisateur
CPU	2 coeurs par conteneur utilisateur
Délai de lancement	180 secondes

Gestion des ressources¶

Arrêt automatique des serveurs inactifs (Cull)¶

JupyterHub arrête automatiquement les serveurs notebook inactifs pour libérer les ressources du cluster (CPU, RAM). Cela est géré par le composant intégré jupyterhub-idle-culler.

Paramètre	Défaut	Description
`cull.enabled`	`true`	Activer l'arrêt automatique des serveurs inactifs
`cull.timeout`	`1800`	Secondes d'inactivité avant arrêt (30 min)
`cull.every`	`300`	Fréquence de vérification (5 min)
`cull.maxAge`	`28800`	Durée de vie maximale d'un serveur en secondes (8h), même si actif

Pour modifier ces valeurs, éditez values-dev.yaml (ou votre fichier de valeurs production) :

jupyterhub:
  cull:
    enabled: true
    timeout: 3600       # 1 heure d'inactivité
    every: 300          # vérification toutes les 5 minutes
    maxAge: 43200       # 12 heures max

Puis appliquez :

helm upgrade akko helm/akko/ -n akko -f <votre-fichier-values>.yaml \
  --set-file akko-keycloak.realm.data=<fichier-realm>.json

Les données utilisateur sont préservées

L'arrêt automatique ne supprime que le pod (ressources de calcul). Les fichiers de l'utilisateur sont stockés sur un PersistentVolumeClaim (claim-<username>) qui persiste entre les redémarrages. Quand l'utilisateur se reconnecte, un nouveau pod est créé et le PVC est remonté automatiquement.

Recommandations pour la production

Data Scientists avec des entraînements longs : augmentez timeout à 7200 (2h) et maxAge à 86400 (24h).
Environnements sensibles aux coûts : réduisez timeout à 600 (10 min).
Ateliers / démos : définissez maxAge à 14400 (4h) pour garantir le nettoyage après la session.

Problèmes connus¶

Points d'attention importants

CHOWN_HOME_OPTS=-R ne fonctionne pas avec les volumes en lecture seule : L'image notebook utilise CHOWN_HOME=no et un hook personnalisé before-notebook.d qui exécute chown 2>/dev/null || true.
jupyterlab-drawio : Ne jamais installer -- force JupyterLab 3.
jupyterlab-lsp : Doit être >= 5 pour la compatibilité JupyterLab 4.
emailVerified dans Keycloak : Tous les utilisateurs de test doivent avoir emailVerified=true dans Keycloak, sinon oauth2-proxy les rejette.