Install JupyterHub on AWS Elastic Kubernetes Service (EKS)

Adding a Custom User Environment

To add a new Python or ML environment to an existing JupyterHub deployment on EKS:

1. Build a Dockerfile containing the libraries your team needs.
2. Base your image on one of the official Jupyter Docker Stacks so the notebook server and hub hooks are already wired up.
3. Push the custom image to Docker Hub (or ECR).
4. Open hub/config.yaml, which holds the Helm values for the Zero to JupyterHub deployment.
5. Register the new image under singleuser.profileList; see the Zero to JupyterHub profile documentation for the exact schema.
6. Commit the change and run your Helm upgrade; JupyterHub will reload and surface the new profile in the server spawn menu.
7. Restart your personal notebook server from the JupyterHub control panel to pick up the new image.

GPU-Enabled Docker Image

• To expose NVIDIA GPUs cleanly inside user notebooks, use cschranz/gpu-jupyter. It is already preconfigured in config.yaml, so you can select it directly from the launcher.
• Avoid stock tensorflow/tensorflow:latest-gpu images directly in JupyterHub, as mismatched CUDA/cuDNN paths and missing JupyterHub single-user entrypoints often prevent the notebook kernel from seeing the attached GPU.

Provisioning EKS from Scratch

Initial IAM Setup

Reference: AWS EKS Getting Started Guide

1. Create an IAM group named admin and attach the AdministratorAccess policy.
2. Create an IAM user with both programmatic (CLI) and AWS Management Console access, and add that user to admin.
3. Enable virtual MFA (for example, Microsoft Authenticator or 1Password) on the AWS root account.
4. Delete any root account access keys, sign out of root, and sign back in as your IAM user.
5. Create an IAM role for CloudFormation with permissions to provision VPC and EKS resources.

Create the VPC

Reference: Creating a Public and Private VPC for EKS

1. Attach the required EC2/VPC creation policies to your CloudFormation IAM role.
2. Launch the official EKS CloudFormation VPC stack using the default Public and Private subnet topology.

Create the EKS Cluster

Reference: Modifying EKS Cluster Endpoint Access

1. Create the cluster in the EKS console.
2. Attach the subnets and security group created by your VPC CloudFormation stack (look for the security group with ControlPlaneSecurityGroup in its name).
3. Configure cluster endpoint access (it defaults to Public).

Attach Worker Nodes (and Common Gotchas)

• GPU quota: New AWS accounts usually have a 0 vCPU quota for G and P GPU instance families. Open a Service Quotas support ticket early if you need GPU node groups.
• Nodes failing to join the cluster: If worker nodes spin up in EC2 but never register with kubectl get nodes, check your public subnet settings. AWS occasionally defaults MapPublicIpOnLaunch to false, so nodes come up without an outbound route to the EKS control plane. Flip MapPublicIpOnLaunch to true on the public subnets:
  • 5 Things You Need to Know to Add Worker Nodes in AWS EKS
  • De-mystifying Cluster Networking for Amazon EKS Worker Nodes
  • CloudFormation EC2 Subnet Reference
  • EKS Worker Node Troubleshooting Gist (Liz Rice)
  • Quick CLI check for MapPublicIpOnLaunch: aws ec2 describe-subnets --filters "Name=vpc-id,Values=<your-vpc-id>" | grep 'MapPublicIpOnLaunch|SubnetId|VpcId|State'

JupyterHub Helm Configuration

• Follow the Zero to JupyterHub on Kubernetes guide for the base Helm chart install.
• AWS LoadBalancer port mismatch: By default, the Classic/NLB service annotation can route port 80/443 to the wrong backend port on the proxy pod. See zero-to-jupyterhub-k8s#1637 for the service annotations needed to expose the JupyterHub UI properly.
• Always pass -n jhub (or switch your active context namespace to jhub) before running helm upgrade so you don’t accidentally deploy a second release into default.