Skip to main content

JupyterHub with KAI Scheduler

Overview​

The JupyterHub with KAI Scheduler template provisions a Kubernetes cluster with JupyterHub with KAI Scheduler for interactive notebook workloads and scheduled jobs. Use this template when you need a ready-to-use JupyterHub environment on Kubernetes.

Accessing the cluster​

Bridge provides two ways to work with your cluster after it is created:

  • Download kubeconfig — You can download the cluster kubeconfig file from the cluster menu. Use this file to access the cluster from your local machine or external tools (e.g., kubectl, IDEs, or CI/CD pipelines) by setting KUBECONFIG or merging the file into your default kubeconfig.

  • Kubectl Terminal — The Kubectl Terminal feature in Bridge lets you interact directly with the Kubernetes cluster from the Bridge UI. You do not need to log in to the cluster separately from an external terminal. With this feature you can:

    • Run kubectl commands directly from the UI
    • Manage and monitor cluster resources without switching to a separate command-line environment
    • Perform cluster operations from the Bridge UI and save time

This guide covers:

  • Configuring cluster name, version, and CNI
  • Selecting the JupyterHub with KAI Scheduler template and hostname
  • Selecting nodes and monitoring creation until the cluster is Running
  • Downloading kubeconfig, viewing nodes and GPUs, and using the Kubectl Terminal

Prerequisites​

  • Tenant Admin access — Log in as a Tenant Admin to create clusters.
  • Compute resources — Bare Metal or Virtual Machine resources allocated to your tenant.
  • Port-forward on Bridge node — For cluster creation to succeed, port-forward must be running on the Bridge-deployed node (see note below).
Port-forward for cluster creation

Run the port forwarding on the Bridge node so that cluster creation can complete.

kubectl -n amcop-system port-forward --address 0.0.0.0 svc/ingress-ingress-nginx-controller 443:443
  • Keep this command running during cluster creation.
  • If you do not have access to the Bridge node, contact your Bridge Super Administrator.

Create a JupyterHub with KAI Scheduler Cluster​

Step 1: Start Cluster Creation​

  1. Log in to Armada Bridge as a Tenant Admin.
  2. In the left sidebar, click Compute → Cluster.
  3. Click Create Cluster. Create Cluster Button

Step 2: Configure Cluster Details​

  1. Enter a name and description for the cluster.
  2. Select the Kubernetes version.
  3. Select the CNI plugin. Bridge supports Flannel and Cilium.
  4. (Optional) Enable Install NVIDIA GPU tools if you want GPU tooling on the cluster.
  5. Click Next. Cluster Setup Details Cluster CNI Plugin

Step 3: Select Cluster Template​

  1. Choose Launch JupyterHub with Kai Scheduler Template.
  2. Enter the Hostname (for example, jupyter.armada.ai) as required by your environment.
  3. Click Next. Create Cluster Button

Step 4: Select Nodes and Create​

  1. Select the cluster node(s) (Bare Metal or Virtual Machine).
  2. Click Create to start cluster creation. Create Cluster Button

Step 5: Monitor Cluster Creation​

Cluster creation runs through several states. Wait until the status is Running.

  1. Initializing Control Planes — Status shows Processing. Cluster Process State
  2. Initializing Workers — Status remains Processing. Cluster Initialize State
  3. When creation completes, the Status shows Running. Cluster Success State

Step 6: Configure Local Hostname (if DNS is not resolvable)​

If the configured hostname is not resolvable through public or internal DNS, add an entry to /etc/hosts on your local machine.

<GPU_VM_Public_IP> <jupyter_hostname>

Replace:

  • <GPU_VM_Public_IP> with the public IP of the VM/Bare Metal node used for cluster creation
  • <jupyter_hostname> with the hostname configured in Step 3 (e.g., jupyter.armada.ai)

Step 7: Download Kubeconfig​

  1. Click the menu (ellipsis) icon for the cluster.
  2. Select Kubeconfig to download the cluster kubeconfig file. Create Cluster Button

Step 8: View Cluster Details and Access Tools​

Click the cluster view icon (or cluster name) to open cluster details.

  • Overview — Cluster information, and options to scale the cluster, download kubeconfig, access the dashboard, and delete the cluster. The Nodes tab shows details of the nodes allocated to the cluster.

    Cluster Overview

  • GPUs — Click the GPUs tab to view allocated GPU details.

    Cluster GPU Details

  • Kubectl Terminal — Click the Kubectl Terminal (arrow) icon to access the cluster and run kubectl commands.

    Cluster K8s Terminal

    Cluster K8s Command

note

Ensure all pods are in Running state before using the cluster for workloads. In the Kubectl Terminal, run:

kubectl get pods -A

Next Steps​

Last updated on