Starting a Jupyter notebook appears to be one simple action. At approximately 5,000 real notebook-server sessions on a typical day, that action becomes considerably more complex - especially because the workloads are not identical. Each notebook may require a different combination of CPU, memory, GPU capacity, container image, storage, and runtime configuration, with some resources available only in particular clusters.

This talk presents how we extended KubeSpawner to separate the JupyterHub control plane from the Kubernetes clusters where notebook servers run. We follow a notebook through its complete lifecycle: interpreting its resource requirements, selecting a suitable cluster, creating its pod and service in the correct context, observing startup, retrieving its endpoint, monitoring health, and terminating it safely.

We cover context-aware Kubernetes clients, per-cluster state tracking, progress reporting, timeout recovery, stale-state detection, and cross-cluster cleanup. The result is a reusable architecture that lets JupyterHub operate across bare-metal and managed cloud clusters without exposing infrastructure complexity to notebook users.