Setting up JupyterHub¶
Now that we have a Kubernetes cluster and helm setup, we can begin setting up a JupyterHub.
Prepare configuration file¶
This step prepares a configuration file (config file). We will use the YAML file format to specify JupyterHub’s configuration.
It’s important to save the config file in a safe place. The config file is needed for future changes to JupyterHub’s settings.
For the following steps, use your favorite code editor. We’ll use the nano editor as an example.
Create a file called
config.yaml
. Using the nano editor, for example, enteringnano config.yaml
at the terminal will start the editor and open the config file.Create a random hex string to use as a security token. Run this command in a terminal
openssl rand -hex 32
Copy the output for use in the next step
Insert these lines into the
config.yaml
file. When editing YAML files, use straight quotes and spaces and avoid using curly quotes or tabs. SubstituteRANDOM_STRING
below with the output ofopenssl rand -hex 32
from step 2.proxy: secretToken: "<OUTPUT-OF-`openssl rand -hex 32`>"
Azure AKS only If you’re on Microsoft Azure AKS, you must disable RBAC. Do so by putting the following in
config.yaml
rbac: enabled: false
See the RBAC documentation for more details.
Save the
config.yaml
file.
Install JupyterHub¶
Let’s add the JupyterHub helm repository to your helm, so you can install JupyterHub from it. This makes it easy to refer to the JupyterHub chart without having to use a long URL each time.
helm repo add jupyterhub https://jupyterhub.github.io/helm-chart/ helm repo update
This should show output like:
Hang tight while we grab the latest from your chart repositories... ...Skip local chart repository ...Successfully got an update from the "stable" chart repository ...Successfully got an update from the "jupyterhub" chart repository Update Complete. ⎈ Happy Helming!⎈
Now you can install the chart! Run this command from the directory that contains the
config.yaml
file to spin up JupyterHub:helm install jupyterhub/jupyterhub \ --version=v0.6 \ --name=<YOUR-RELEASE-NAME> \ --namespace=<YOUR-NAMESPACE> \ -f config.yaml
where:
--name
is an identifier used by helm to refer to this deployment. You need it when you are changing the configuration of this install or deleting it. Use something descriptive that you will easily remember. For a class called data8 you might wish set the name to data8-jupyterhub. In the future you can find out the name by usinghelm list
.--namespace
is an identifier used by Kubernetes (among other things) to identify a particular application that might be running on a single Kubernetes cluster. You can install many applications into the same Kubernetes cluster, and each instance of an application is usually separated by being in its own namespace. You’ll need the namespace identifier for performing any commands withkubectl
.
We recommend providing the same value to
--name
and--namespace
for now to avoid too much confusion, but advanced users of Kubernetes and helm should feel free to use different values.Note
- This step may take a moment, during which time there will be no output to your terminal. JupyterHub is being installed in the background.
- If you get a
release named <YOUR-RELEASE-NAME> already exists
error, then you should delete the release by runninghelm delete --purge <YOUR-RELEASE-NAME>
. Then reinstall by repeating this step. If it persists, also dokubectl delete <YOUR-NAMESPACE>
and try again. - In general, if something goes wrong with the install step, delete the
Helm namespace by running
helm delete --purge <YOUR-RELEASE-NAME>
before re-running the install command. - If you’re pulling from a large Docker image you may get a
Error: timed out waiting for the condition
error, add a--timeout=SOME-LARGE-NUMBER
parameter to thehelm install
command. - The
--version
parameter corresponds to the version of the helm chart, not the version of JupyterHub. Each version of the JupyterHub helm chart is paired with a specific version of JupyterHub. E.g., v0.5 of the helm chart runs JupyterHub v0.8.
While Step 1 is running, you can see the pods being created by entering in a different terminal:
kubectl --namespace=<YOUR-NAMESPACE> get pod
Wait for the hub and proxy pod to begin running.
You can find the IP to use for accessing the JupyterHub with:
kubectl --namespace=<YOUR-NAMESPACE> get svc
The external IP for the
proxy-public
service should be accessible in a minute or two.Note
If the IP for
proxy-public
is too long to fit into the window, you can find the longer version by calling:kubectl --namespace=<YOUR-NAMESPACE> describe svc proxy-public --output=wide
To use JupyterHub, enter the external IP for the
proxy-public
service in to a browser. JupyterHub is running with a default dummy authenticator so entering any username and password combination will let you enter the hub.
Congratulations! Now that you have JupyterHub running, you can extend it in many ways. You can use a pre-built image for the user container, build your own image, configure different authenticators, and more!