Skip to content

Latest commit

 

History

History
267 lines (221 loc) · 11.3 KB

README.md

File metadata and controls

267 lines (221 loc) · 11.3 KB
Raw

puppet-jupyterhub

The module installs, configures, and manages the JupyterHub service with batchspawner as a spawner and in conjunction with the job scheduler Slurm.

Requirements

  • Linux
  • Slurm >= 17.x

Hub

  • The hub ports 80 and 443 need to be opened to the users incoming network (i.e: Internet).
  • The hub needs to allow authentication of users through pam.
  • The hub must be able to talk to slurmctld to submit jobs on the users' behalf.
  • The hub port 8081 needs to be accessible from the compute node network.
  • The slurm binaries needs to be installed and accessible from PATH for the user jupyterhub, mainly : squeue, sbatch, sinfo, sacctmgr and scontrol.
  • The hub does not need the users to have SSH access.
  • The hub does not need access to the cluster filesystem.

Compute Node

Setup

hub

To install JuptyerHub with the default options:

include jupyterhub

compute

To install the Jupyter notebook component on the compute node:

include jupyterhub::node

If the compute nodes cannot access Internet, configure the puppet agent to use http_proxy_host.

Hieradata Configuration

General options

Variable Type Description Default
jupyterhub::jupyterhub::version String JupyterHub package version to install refer to data/common.yaml
jupyterhub::pip::version String pip package version to install refer to data/common.yaml
jupyterhub::notebook::version String notebook package version to install refer to data/common.yaml
jupyterhub::batchspawner::version String Url to batchspawner source code release file  refer to data/common.yaml
jupyterhub::slurmformspawner::version String  slurmformspawner package version to install  refer to data/common.yaml 
jupyterhub::oauthenticator::version String  oauthenticator package version to install  refer to data/common.yaml 
jupyterhub::ltiauthenticator::version String  ltiauthenticator package version to install  refer to data/common.yaml 
jupyterhub::oauth2freeipa::version String  oauth2freeipa package version to install  refer to data/common.yaml 
jupyterhub::pammfauthenticator::url   String Url to pammfauthenticator source code release file  refer to data/common.yaml 
jupyterhub::jupyterhub_traefik_proxy::version   String jupyterhub-traefik-proxy package version to install  refer to data/common.yaml 
jupyterhub::nbgitpuller::version String nbgitpuller package version to install refer to data/common.yaml

Hub options

Variable Type Description Default
jupyterhub::prefix Stdlib::Absolutepath Absolute path where JupyterHub will be installed  /opt/jupyterhub
jupyterhub::bind_url String Public facing URL of the whole JupyterHub application https://127.0.0.1:8000 
jupyterhub::slurm_home Stdlib::Absolutepath Path to Slurm installation folder  /opt/software/slurm 
jupyterhub::admin_groups Array[String] List of user groups that can act as JupyterHub admin []
jupyterhub::idle_timeout  Integer Time in seconds after which an inactive notebook is culled 0 (no timeout)
jupyterhub::traefik_version String Version of traefik to install on the hub instance '2.10.4'
jupyterhub::authenticator_class  String Class name of the authenticator JupyterHub will use pam
jupyterhub::jupyterhub_config_hash  Hash Custom hash merged to JupyterHub JSON main hash {}
jupyterhub::blocked_users List[String] List of users that cannot login ['root', 'toor', 'admin', 'centos', 'slurm']
jupyterhub::prometheus_token String Token that Prometheus can use to scrape JupyterHub's metrics undef

Announcement options

puppet-jupyterhub installs the service jupyterhub-announcement to broadcast messages for the users once connected to the hub.

Variable Type Description Default
jupyterhub::announcement::port Integer  Localhost port the service will listen on 8888
jupyterhub::announcement::fixed_message String Message that will always be displayed ''
jupyterhub::announcement::lifetime_days Integer Announcement duration in days 7
jupyterhub::announcement::persist_path String File where current and past annoucements are stored /var/run/jupyterhub/announcements.json

Compute node options

Variable Type Description Default
jupyterhub::node::prefix Stdlib::Absolutepath Absolute path where Jupyter Notebook and jupyterhub-singleuser will be installed  /opt/jupyterhub
jupyterhub::kernel::setup Enum['venv', 'module'] Determine if the Python kernel is provided by a local virtual environment or a module module
jupyterhub::kernel::venv::prefix Stdlib::Absolutepath Absolute path where the IPython kernel virtual environment will be installed  /opt/ipython-kernel
jupyterhub::kernel::venv::python Stdlib::Absolutepath Absolute path to the Python binary that will be used as the default kernel  /usr/bin/python3 
jupyterhub::kernel::venv::pip_environment Hash[String, String] Hash of environment variables configured before calling installing venv::packages {}
jupyterhub::kernel::venv::packages Array[String]  Python packages to install in the default kernel  []

SlurmFormSpawner's options

To control SlurmFormSpawner options, use jupyterhub::jupyterhub_config_hash like this:

jupyterhub::jupyterhub_config_hash:
  SbatchForm:
    account:
      def: 'def-account'
    runtime:
      min: 1.0
      def: 2.0
      max: 5.0
    nprocs:
      min: 1
      def: 2
      max: 8
    memory:
      min: 1024
      max: 2048
    gpus:
      def: 'gpu:0'
      choices: ['gpu:0', 'gpu:k20:1', 'gpu:k80:1']
    oversubscribe:
      def: false
      lock: true
    ui:
      def: 'lab'
      choices: ['lab', 'notebook', 'terminal', 'rstudio', 'code-server', 'desktop']
    partition:
      def: 'partition1'
      choices: ['partition1', 'partition2', 'partition3']
  SlurmFormSpawner:
    ui_args:
      notebook:
        name: Jupyter Notebook
        args: '/tree'
        modules: ['ipython-kernel/3.7']
      lab:
        name: JupyterLab
        modules: ['ipython-kernel/3.7']
      terminal:
        name: Terminal
        args: '/terminals/1'
      rstudio:
        name: RStudio
        args: '/rstudio'
        modules: ['gcc', 'rstudio-server']
      code-server:
        name: VS Code
        args: '/code-server'
        modules: ['code-server']
      desktop:
        name: Desktop
        url: '/Desktop'
  SlurmAPI:
    info_cache_ttl: 3600 # refresh sinfo cache at most every hour
    acct_cache_ttl: 3600 # refresh account cache at most every hour
    res_cache_ttl: 3600  # refresh reservation cache at most every hour

Refer to slurmformspawner documentation for more details on each parameter.

SlurmSpawner usage example

SlurmSpawner can be used instead of SlurmFormSpawner when job configuration with a form is not desirable:

jupyterhub::spawner_class: "batchspawner.SlurmSpawner"
jupyterhub::jupyterhub_config_hash:
  SlurmSpawner:
    req_account: "def-sponsor00"
    req_memory: "256"
    req_nprocs: "1"
    req_runtime: "3600"
    req_options: "--oversubscribe"
    default_url: "/tree" # use nbclassic instead of lab

OAuthenticator usage example

By default, puppet-jupyterhub configures the authentication with PAM, but the oauthenticator package is readily installed.

In this example, we configure JupyterHub to authenticate with GitHub and create an account in FreeIPA.

jupyterhub::authenticator_class: "ipa-github"
jupyterhub::jupyterhub_config_hash:
  GitHubOAuthenticator:
    auto_login: true
    oauth_callback_url: "https://[your-domain]/hub/oauth_callback"
    client_id: "XYZ"
    client_secret: "DCBA-123-456"

LTIAuthenticator usage example

By default, puppet-jupyterhub configures the authentication with PAM, but the ltiauthenticator package is readily installed. This allows to integrate with LTI (Learning Tools Interoperability) providers.

In this example, we configure JupyterHub to authenticate with an LTI 1.1 provider

jupyterhub::authenticator_class: "ipa-lti11"
jupyterhub::jupyterhub_config_hash:
  LTI11Authenticator:
    consumers: { '<lti_client_key>': '<lti_shared_secret'> ]}
    username_key: 'lis_person_sourcedid'

For more information about the LTI Authenticator for JupyterHub, see its documentation for version 1.1. For LTI 1.3, you would change ipa-lti11 by ipa-lti13 and adjust the hash according to LTI Authenticator's documentation for version 1.3.

Jupyter Notebook options

To control options and traitlets of Jupyter Notebook and its extensions, use jupyterhub::jupyter_notebook_config_hash like this:

jupyterhub::jupyter_notebook_config_hash:
  ServerProxy:
    servers:
      rstudio:
        command: ["rserver", "--www-port={port}", "--www-frame=same", "--www-address=127.0.0.1"]
        timeout: 30
        launcher_entry:
          title: RStudio
      code-server:
        command: ["code-server", "--auth=none", "--disable-telemetry", "--host=127.0.0.1", "--port={port}"]
        timeout: 30
        launcher_entry:
          title: VS Code
      openrefine:
        command: ["refine"]
        timeout: 30
        launcher_entry:
          title: OpenRefine

Submit addition option

Variable Type Description
jupyterhub::submit::additions String bash command(s) that should be added to submit.sh

Adds the following by default:

# Make sure Jupyter does not store its runtime in the home directory
export JUPYTER_RUNTIME_DIR=${SLURM_TMPDIR}/jupyter

# Disable variable export with sbatch
export SBATCH_EXPORT=NONE
# Avoid steps inheriting environment export
# settings from the sbatch command
unset SLURM_EXPORT_ENV

# Setup user pip install folder
export PIP_PREFIX=${SLURM_TMPDIR}
export PATH="${PIP_PREFIX}/bin":${PATH}
export PYTHONPATH=${PYTHONPATH}:"/opt/jupyterhub/lib/usercustomize"

# Make sure the environment-level directories does not
# have priority over user-level directories for config and data.
# Jupyter core is trying to be smart with virtual environments
# and it is not doing the right thing in our case.
export JUPYTER_PREFER_ENV_PATH=0