JupyterHub

Note

Pre-requisites

  • A Kubernetes cluster

  • The Kubernetes cluster must have a suitable StorageClass configured to enable persistent storage

  • Similarly, a suitable Ingress controller is needed to enable external traffic to access the JupyterHub server

  • A client configured on the SKA IAM deployment to issue and validate access tokens for the service

IAM Configuration

For this service, the scopes required are:

  • `email`

  • `offline_access`

  • `openid`

  • `profile`

Follow the next instructions to create and manage the IAM Client Configuration, including these scopes.

Note

Once saved, note the Client Name, Client Secret, and Redirect URIs; these will be needed to configure the JupyterHub authentication and the YAML files. For more information, visit: IAM Client Registration.

JupyterHub Service

Helm Deployment

Create a values.yaml with the following fields; a description of the key configuration settings follows:

hub:
   config:
      Authenticator:
         enable_auth_state: true
         allow_all: true
      GenericOAuthenticator:
         login_service: "<Name of the Login Service that will appear within the Login Screen>"
         client_id: <CLIENT_ID>
         client_secret: <CLIENT_SECRET>
         oauth_callback_url: <REDIRECT_URI>
         authorize_url: https://ska-iam.stfc.ac.uk/authorize
         token_url: https://ska-iam.stfc.ac.uk/token
         userdata_url: https://ska-iam.stfc.ac.uk/userinfo
         scope:
         - openid
         - profile
         - email
         - offline_access
         userdata_token_method: GET
         userdata_params: {'state': 'state'}
         username_key: preferred_username
      JupyterHub:
         authenticator_class: generic-oauth

   extraConfig:
      logoConfig: |
            import urllib.request
            urllib.request.urlretrieve("<LOGO_URL>", "logo.png")
            c.JupyterHub.logo_file = '/srv/jupyterhub/logo.png'

   baseUrl: /<SERVICE_BASE_URL>/

   db:
      pvc:
         storageClassName: <STORAGE_CLASS>

singleuser:
   memory:
      limit: 1G
      guarantee: 1G

   cpu:
      limit: 0.5
      guarantee: 0.5

   storage:
      dynamic:
         storageClass: <STORAGE_CLASS>
      capacity: 1Gi

   # Defines the default image
   defaultUrl: "/lab"
   extraEnv:
      JUPYTERHUB_SINGLEUSER_APP: "jupyter_server.serverapp.ServerApp"
   image:
      name: jupyter/minimal-notebook
      tag: latest
   profileList:
      - display_name: "Minimal environment"
         description: "A Python environment."
         default: true
      - display_name: "Data science environment"
         description: "Python, R and Julia environments."
         kubespawner_override:
         image: jupyter/datascience-notebook:latest

The following values.yaml variables will need to be modified for each deployment:

  • <CLIENT_ID>: The ID for the SKA IAM client created above

  • <CLIENT_SECRET>: The corresponding client secret generated by SKA IAM

  • <REDIRECT_URI>: This will be the hostname of the service; if your Jupyter service will be hosted at https://example.com/jupyter/ the callback URL will be https://example.com/jupyter/hub/oauth_callback. This must match (one of) the Redirect URIs set above when configuring the IAM client

  • <LOGO_URL>: This is optional. The specified logo will appear in the left corner. You will need a URL for the logo in png or jpg format.

  • <SERVICE_BASE_URL>: If the JupyterHub service is to be hosted at a subdirectory URL, (e.g. example.com/jupyterhub), change the <SERVICE_BASE_URL> to reflect this; in this example, it would be: /jupyterhub/

  • <STORAGE_CLASS>: Include the name of the StorageClass of your Kubernetes cluster

Once the values.yaml has been updated, the Helm package manager can be used to install JupyterHub. Helm typically requires a release name and a chart identifier; the chart releases for JupyterHub can be found at: https://hub.jupyter.org/helm-chart/.

The following commands will add and update the JupyterHub Helm repository:

helm repo add jupyterhub https://hub.jupyter.org/helm-chart/
helm repo update

Then, to install JupyterHub with Helm, use the following command. The jupyterhub-release can be changed to a more appropriate name, as can the specified Namespace:

helm upgrade --cleanup-on-fail \
   --install jupyterhub-release jupyterhub/jupyterhub \
   --namespace jhub-srcnet-01 \
   --create-namespace \
   --values values.yaml

To install another version or to fix the deployment to a concrete version, use --version:

helm upgrade --cleanup-on-fail \
   --install jhub-release jupyterhub/jupyterhub --version 3.3.8 \
   --namespace jhub-srcnet-01 \
   --create-namespace \
   --values values.yaml

Use helm list -A to view see the current installed charts with their versions.