Notebooks Stack (JupyterHub)

What the Notebooks Stack is

The Notebooks template deploys JupyterHub 5 into a cluster you choose, from a single form. A developer opens the hub’s address, signs in, picks a server size and an image, and works in JupyterLab in the browser or from VS Code. Their home folder is kept between sessions. A server that sits idle stops itself, so you pay for compute only while someone is working. Notebooks read and write one S3 bucket through an IAM role, with no access keys to hand out.

It is built for a team of roughly 10 to 50 people sharing one hub. With a dedicated entrance the hub was ready about seven minutes after Deploy in a live run, most of it the load balancer warming up; the shared entrance skips that wait. A developer’s first server took about two and a half minutes to start.

The template is available on paid plans. It needs a native (sgt-k8s) cluster with two add-ons: EBS CSI (home volumes) and cert-manager (the HTTPS certificate), plus Load Balancer when you choose a dedicated entrance, and an environment with a domain. The wizard tells you which add-on is missing on the cluster you pick.

What gets deployed

One application with one component, hub: a release of the sg-notebooks Helm chart, which wraps the upstream Zero to JupyterHub chart, pinned to one cluster. Nothing cluster-wide is installed.

Deploy it

1. Open Applications → Templates and choose Notebooks. Clicking the card opens its details; Deploy starts the wizard.
2. First step: name, environment, cluster and space, then the sign-in method and whether the data bucket is new or one you already own.
3. Second step: who may sign in, the sizes and images developers can pick, home storage, the idle timeout, the Allowed IPs and the bucket details. With an existing bucket, its name or ARN is required.
4. Review and deploy. When the stack is ready, the Stack tab shows the hub address, the sign-in details and code to copy.

Sign-in

With the first three, sign-in is handled by the hub itself. With the last two, an Auth Proxy (oauth2-proxy) signs people in and the hub accepts its session.

Shared passwords

The Stack tab shows the admin and team passwords masked. Each reveal needs update access to the app and is written to the audit log. Admins sign in with the admin password; the usernames you listed sign in with the team password. Anyone else is refused, with either password.

GitHub and single sign-on

Create the OAuth app or client with your provider, paste its client ID and secret into the form, and deploy. The secret is stored encrypted and is not shown again. Register the OAuth callback URL with the provider. Set Hub address to the application name and the hub lives at https://<application name>.<domain>: the wizard shows the callback URL under that choice, so you can register it before you deploy. This needs your own domain on the environment (not Seagit’s shared domain), and an address already used on that domain is refused. With a generated name, copy the callback URL from the Stack tab after the first deploy. For single sign-on, the endpoints are read from the issuer’s discovery document. To restrict access by group, set Allowed groups; Okta sends the groups claim only when groups is added under Extra scopes.

Through an Auth Proxy

New sign-in for this stack runs a sign-in service beside the hub, on the hub’s own address. Create the OAuth app or client with your provider, choose the provider, and paste its client ID and secret. Register the Redirect URL to register (https://<hub address>/services/auth/callback) with the provider: shown in the wizard when Hub address is the application name, otherwise on the Stack tab after the first deploy. GitHub needs an organization and can be limited to one team; Google needs the email domains allowed to sign in.

An existing Auth Proxy stack reuses the sign-in you already run for MLflow and other tools: people who are signed in there are signed in to the hub, with nothing to register. The Auth Proxy can be in any of your environments, on any cluster, as long as its cookie domain covers the hub’s address: an Auth Proxy in an environment on ns.example.com serves hubs on ns.example.com and its sub-domains. On the same cluster the hub checks sessions at the Auth Proxy’s in-cluster address, otherwise at its public one. If the picker is empty, the note under it names your Auth Proxy stacks and the domains they are on. Allowed groups narrow who may use this hub.

In both cases the hub checks the session with the sign-in service over the cluster network. It does not trust identity headers, so a notebook cannot pretend to be someone else. Usernames are email addresses.

Log out ends the sign-in service’s session as well as the hub’s, then shows a signed-out page. With an existing Auth Proxy stack this signs you out of every app behind it, MLflow included, because they share one session. Your notebook server keeps running until it is idle. You stay signed in to your provider (GitHub, Google or your identity provider), so signing in again does not ask for a password.

Admins

Admins see every server in the hub’s admin page and can stop them. With GitHub they are GitHub usernames; with single sign-on, the username claim (usually the email) or members of the Admin groups. Through an Auth Proxy, email addresses or members of the Admin groups.

Servers

Sizes

Tick each size developers may pick, in any combination. The limit is what a server may use; the guaranteed memory is what must be free on one node for the server to start.

Check the guaranteed memory against your nodes. On a pool of 2 GB nodes a Small server may not fit beside the system pods; offer X-Small there or add a larger pool.

Images

The built-in images are pinned to a dated tag, so every developer gets the same versions. Packages installed with pip into the home folder survive a restart; packages installed system-wide do not. For a stable team environment, build an image.

Home storage

Each developer gets an EBS volume (10 GiB by default) mounted as the home folder, created on first start. It is kept when the server stops and deleted when the stack is deleted. Put data you want to outlive the stack in the bucket.

Idle servers

A server with no activity for the chosen time (30 minutes to 24 hours, 1 hour by default) is stopped. The home is kept, and the server starts again at the next sign-in. A kernel that is busy counts as activity.

Spot nodes

The hub and the servers stay off spot nodes by default. Allow spot for experiments where downtime is fine: a reclaimed node stops the hub or the servers on it. The hub database and the homes are disks in one availability zone, so they start again only once a spot node is free in that same zone, which can take a while. Homes are kept; unsaved kernel state is lost. The environment chooses the node pool; this option chooses spot or on-demand within it.

Data bucket

Every server runs under one Kubernetes service account tied to an IAM role for that bucket or folder, so it reaches the bucket without keys. Each server installs s3fs and boto3 when it starts (about 15 seconds; the images do not include them). These variables are set in every server:

import os
import pandas as pd

base = os.environ["SEAGIT_BUCKET_URI"]
pd.DataFrame({"x": [1, 2, 3]}).to_csv(base + "examples/hello.csv", index=False)
print(pd.read_csv(base + "examples/hello.csv"))

pandas reads and writes s3:// addresses through s3fs, so code that builds paths from SEAGIT_BUCKET_URI needs no AWS-specific calls. Use boto3 when you want the S3 API itself, for example to list objects or set metadata.

Access is shared: every developer on the hub can read and write the whole bucket or folder. Use separate stacks for teams that must not see each other’s data.

Network and security

• Allowed IPs limit who can reach the sign-in page, at the shared entrance or at the dedicated load balancer. They are optional: left empty (or 0.0.0.0/0), anyone can reach the page (sign-in is still required) and the Stack tab says so. Set your office or VPN addresses. They apply with every sign-in method.
• Servers cannot reach the cloud metadata address, so a notebook cannot pick up the node’s own AWS permissions.
• Servers get no Kubernetes API token and cannot reach other buckets in the account.
• By default servers reach the internet only. Reach private addresses lets them connect to databases and services in the VPC and the cluster.

Track experiments in MLflow

Deploy an MLflow stack on the same cluster first. In the Notebooks wizard, set Track experiments in MLflow to Use an MLflow stack in this environment and pick the stack. The list shows only MLflow stacks on the cluster you chose, and one on another cluster is refused at create, because notebooks reach it at its in-cluster address. Every server then gets MLFLOW_TRACKING_URI set to MLflow’s in-cluster address, and a network rule that lets servers reach MLflow on port 5000 in its namespace, whatever Reach private addresses is set to. Servers started before the change pick it up at their next start.

The Connect panel shows an MLflow snippet:

%pip install mlflow==3.17.1

import mlflow

mlflow.set_experiment("my-experiment")
with mlflow.start_run():
    mlflow.log_param("model", "baseline")
    mlflow.log_metric("accuracy", 0.91)

Notebooks reach MLflow inside the cluster, so they do not sign in. With per-experiment access control on the MLflow stack, runs from notebooks act as its in-cluster service identity.

Use it from VS Code

1. Open the hub, sign in and start your server.
2. In the hub: File → Hub Control Panel → Token → Request new API token.
3. In VS Code with the Jupyter extension: Select Kernel → Existing JupyterHub Server, then enter the hub address, your username and the token.

Changing and deleting

There is no Stop action for this stack: servers already stop when idle, and the hub itself is small.

Deleting the stack stops every server and deletes the hub, the load balancer and all home volumes. The delete dialog offers to also delete a bucket SeaGit created; left unticked, the bucket and its data stay in your account. A bucket you brought is never deleted.

Limits in this version

• No GPU sizes.
• No shared team folder between homes; share through the bucket.
• The hub is internet-facing with an IP allowlist; there is no private-only option yet.
• One hub per stack, on one cluster.

Troubleshooting

Related

• How to evaluate a RAG or LLM app: build test questions from traces in a notebook
• MLOps Platform: how the stacks fit together
• Clusters and Certificates
• Redis Stack, RAG Stacks and LLM Gateway, the other stack templates
• MLflow Stack, for experiment tracking from notebooks