What is Jupyter?
Jupyter is an open-source, interactive web application for creating and running data science project Notebooks in an Integrated Development Environment (IDE). A Jupyter Notebook not only combines text, equations, multimedia, interactive code and formulas, but you can also share a Notebook among collaborators. JupyterHub hosts Notebooks and other resources as a service, so that they can be used without local installation. Teams run JupyterHub on Kubernetes to automate scaling and resource management for many users.
This lesson sets up the foundation you'll use to share and run Notebooks in later Lessons in the AI/ML with Jupyter on Kubernetes Learning Path. Rather than reinvent the wheel, this initial lesson follows the procedure explained in the JupyterHub for Kubernetes documentation, streamlining and adjusting it to form the foundation of this Learning Path.
JupyterHub provides a Helm Chart to make it easier to deploy on Kubernetes clusters. Helm is a package manager for managing the deployment of applications on Kubernetes. Helm Charts are YAML files describing a set of resources, usually the components of an application or application stack, for deployment on a Kubernetes cluster.
Download and run helm on your Kubernetes cluster:
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 chmod 700 get_helm.sh ./get_helm.sh
Verify that Helm was successfully deployed by invoking
helm version after the script runs. This lesson was written and tested with Helm version 3.7.1.
Use Helm to deploy JupyterHub
With Helm in place, you can work with Charts published in repositories or create your own. You'll use Helm to fetch the JupyterHub Chart, then install it. First, add JupyterHub's URL to your list of Chart repositories.
helm repo add jupyterhub https://jupyterhub.github.io/helm-chart/ helm repo update
Helm should wish you "Happy Helming" after the repository update succeeds:
"jupyterhub" has been added to your repositories Hang tight while we grab the latest from your chart repositories... ...Successfully got an update from the "jupyterhub" chart repository Update Complete. ⎈Happy Helming!⎈
Next, install the JupyterHub Chart from the chart repository. No configuration is required to get a basic JupyterHub running, but you do need a config.yaml file. This example uses an empty one. To learn more about configuring JupyterHub with parameters in a YAML file, please see the JupyterHub for Kubernetes documentation.
touch config.yaml helm upgrade --cleanup-on-fail \ --install hub jupyterhub/jupyterhub \ --namespace jup \ --create-namespace \ --version=1.2.0 \ --values config.yaml
You'll see output something like that below, showing the application of the arguments given to the helm upgrade command.
Release "hub" does not exist. Installing it now. NAME: hub LAST DEPLOYED: Thu Jan 20 14:00:55 2022 NAMESPACE: jup STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: Thank you for installing JupyterHub!
As this output shows, passing
hub to the install argument gives a unique arbitrary name to this deployment of this chart to distinguish it from others. The deployment called
hub is in its first
REVISION, as you can also see.
Make sure the hub and proxy pods are running with
kubectl get pods --namespace jup. Immediately after a completed
helm upgrade in a new namespace on a single node Kubernetes cluster, you typically see five running pods: the continuous-image-puller, the hub, the proxy, and two user-schedulers.
If your cluster runs on a public cloud service, you may have a load balancer configured and in turn a readily accessible public IP. You can discover it by listing the Kubernetes services in the jup namespace to find the
$ kubectl get service -n jup NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE hub ClusterIP 10.104.120.107 <none> 8081/TCP 11m proxy-api ClusterIP 10.98.157.6 <none> 8001/TCP 11m proxy-public LoadBalancer 10.110.127.88 <pending> 80:31353/TCP 11m
The baseline environment for most of the lessons here is a single-node minikube cluster. On minikube clusters, the EXTERNAL-IP will remain in the <pending> state. Use the
minikube service subcommand to wire up a local proxy to the internal cluster IP of the proxy-public service:
minikube service -n jup proxy-public
Minikube will return information about the selected Kubernetes service followed by the relevant digits for dialing the minikube tunnel connecting your host's network to that of the cluster:
? Starting tunnel for service proxy-public. |-----------|--------------|-------------|------------------------| | NAMESPACE | NAME | TARGET PORT | URL | |-----------|--------------|-------------|------------------------| | jup | proxy-public | | http://127.0.0.1:60114 | |-----------|--------------|-------------|------------------------| ? Opening service jup/proxy-public in default browser...
Minikube opens your default browser at the tunnel URL if possible. If not, you can paste the URL returned by
minikube service into a browser on the same machine to open JupyterHub.
Provide the log in dialog with any arbitrary user name and password.
This is safe enough when access is restricted to the local host, as in this example, but for any durable and/or public instance you must configure authorization and TLS encryption. That's beyond the scope of this initial experiment. Instead, let's explore creating Jupyter Notebooks and interactive virtual Unixes for each user with JupyterHub's terminals.
After providing any text for user and password, you will land on the JupyterHub Files tab.
Create any new Jupyter resource by pulling down the menu at right labeled New. In the default installation you've created, you can create a Python 3-driven Notebook, a text file or a folder to store it in, or a Terminal with a Unix command line. Try creating a new terminal and running some basic commands like
Creating a terminal is a quick way to test a script or do other chores. But JupyterHub exists to host Jupyter Notebooks. Return to the Jupyter Home Page Files tab and choose a Python 3 (ipykernel) Notebook from the New menu. A blank Notebook opens in a new browser tab.
In subsequent lessons, you'll use the JupyterHub foundation you've built here to deploy and run Notebooks for realistic analysis, with Kubernetes assisting in scaling the environments and keeping them running.