Setting up a dev environment to work with the Kubernetes Spawner can be a bit tricky, since normally you'd run JupyterHub in a container in the Kubernetes cluster itself. But the dev cycle for that is longer than comfortable, since you've to rebuild the container and redeploy.
There is an easier way, with minikube and some networking tricks. Only tested on Linux at this time, but should work for OS X too.
-
Install minikube. Use the VirtualBox provider. This will set up a kubernetes cluster inside a VM on your machine.
-
Run
minikube start
. This will start your kubernetes cluster if it isn't already up. Runkubectl get node
to make sure it is.Note that the
minikube start
command will also setupkubectl
on your host machine to interact with the kubernetes cluster along with a~/.kube/config
file with credentials for connecting to this cluster. -
Make it possible for your host to talk to the pods on minikube.
# Linux sudo ip route add 172.17.0.0/16 via $(minikube ip) # MACOS sudo route -n add -net 172.17.0.0/16 $(minikube ip)
Got an error like below?
RTNETLINK answers: File exists
It most likely means you have Docker running on your host using the same IP range minikube is using. You can fix this by editing your
/etc/docker/daemon.json
file to add the following:{ "bip": "172.19.1.1/16" }
If some JSON already exists in that file, make sure to just add the
bip
key rather than replace it all. The final file needs to be valid JSON.Once edited, restart docker with
sudo systemctl restart docker
. It should come up using a different IP range, and you can run thesudo ip route add
command again. Note that restarting docker will restart all your running containers by default.
Once you have Kubernetes setup this way, you can setup JupyterHub for development fairly easily on your host machine.
-
Clone this repository
# Clone over HTTPS https://github.com/jupyterhub/kubespawner.git # Clone over SSH git clone git@github.com:jupyterhub/kubespawner.git
-
Setup a virtualenv
cd kubespawner python3 -m venv . source bin/activate
-
Setup a development installation of the Kubernetes spawner:
pip install jupyterhub jupyterhub-dummyauthenticator pip install -e .
-
Install the nodejs configurable HTTP proxy:
sudo npm install -g configurable-http-proxy
-
Ensure user pods can communicate with the hub:
# LINUX: export HUB_CONNECT_IP=`ip addr show vboxnet0 | grep 'scope global' | awk '{ print $2; }' | sed 's/\/.*$//'` # MACOS: export HUB_CONNECT_IP=`ifconfig vboxnet0 | grep inet | awk '{ print $2; }' | sed 's/\/.*$//'`
JupyterHub will read that environment variable and use it to tell the spawned user pods to connect to communicate with JupyterHub on that address.
-
Start JupyterHub and start spawning user pods your Kubernetes cluster:
# Make sure jupyterhub finds the provided jupyterhub_config.py and run this # from the repo's root directory. jupyterhub --no-ssl
The
jupyterhub_config.py
file that ships in this repo will read that environment variable to figure out what IP the pods should connect to the JupyterHub on. Replacevboxnet4
with whatever interface name you used in step 4 of the previous section.This will give you a running JupyterHub that spawns nodes inside the minikube VM! It'll be setup with DummyAuthenticator, so any user + password combo will allow you to log in. You can make changes to the spawner and restart jupyterhub, and rapidly iterate :)
python setup.py test
If you a huge amount of errors, make sure your minikube is up and running and see it if helps to clear your .eggs directory.
rm -rf .eggs
cd docs
conda env update --file environment.yml
conda activate kubespawner
make html