wrapspawner for Jupyterhub

This package includes WrapSpawner and ProfilesSpawner, which provide mechanisms for runtime configuration of spawners. The inspiration for their development was to allow users to select from a range of pre-defined batch job profiles, but their operation is completely generic.

Installation

From root directory of this repo (where setup.py is), run pip install -e .

If you don't actually need an editable version, you can simply run:

pip install git+https://github.com/jupyterhub/wrapspawner

Add lines in jupyterhub_config.py for the spawner you intend to use, e.g.

   c = get_config()
   c.JupyterHub.spawner_class = 'wrapspawner.ProfilesSpawner'

Depending on the spawner, additional configuration will likely be needed.

Wrapper and Profile Spawners

Overview

WrapSpawner provides a mechanism to wrap the interface of a JupyterHub Spawner such that the Spawner class to use for single-user servers can be chosen dynamically. Subclasses may modify the class or properties of the child Spawner at any point before start() is called (e.g. from Authenticator pre_spawn hooks or options form processing) and that state will be preserved on restart. The start/stop/poll methods are not real coroutines, but simply pass through the Futures returned by the wrapped Spawner class.

ProfilesSpawner leverages JupyterHub's Spawner "options form" feature to allow user-driven configuration of Spawner classes while permitting:

configuration of Spawner classes that don't natively implement options_form
administrator control of allowed configuration changes
runtime choice of which Spawner backend to launch

FilteredSpawner allows the definition of profiles that can be assigned only to authenticated users belonging to a specific set of groups.Based over the original ProfilesSpawner it exploits a specific additional configuration profile parameter to specify the set of allowed groups or a * wildcard for enabling that specific profile for all the users

Example

Here is a screenshot of a typical dropdown menu letting the user choose between several SLURM instances:

The following configuration snippet lets the user choose between a Jupyter server running as a local process or one of two different Docker Images to run within DockerSpawner.

c.JupyterHub.spawner_class = 'wrapspawner.ProfilesSpawner'
c.Spawner.http_timeout = 120
#------------------------------------------------------------------------------
# ProfilesSpawner configuration
#------------------------------------------------------------------------------
# List of profiles to offer for selection. Signature is:
#   List(Tuple( Unicode, Unicode, Type(Spawner), Dict ))
# corresponding to profile display name, unique key, Spawner class,
# dictionary of spawner config options.
# 
# The first three values will be exposed in the input_template as {display},
# {key}, and {type}
#
 c.ProfilesSpawner.profiles = [
       ( "Host process", 'local', 'jupyterhub.spawner.LocalProcessSpawner', {'ip':'0.0.0.0'} ),
       ('Docker Python 2/3', 'systemuser', 'dockerspawner.SystemUserSpawner', dict(container_image="jupyterhub/systemuser")),
       ('Docker Python 2/3,R,Julia', 'datasciencesystemuser', 'dockerspawner.SystemUserSpawner', dict(container_image="jupyterhub/datasciencesystemuser")),
 ]

FilteredSpawner example

c.JupyterHub.spawner_class = 'wrapspawner.FilteredSpawner'
c.Spawner.http_timeout = 120
#------------------------------------------------------------------------------
# ProfilesSpawner configuration
#------------------------------------------------------------------------------
# List of profiles to offer for selection. Signature is:
#   List(Tuple( Unicode, Unicode, Type(Spawner), Dict, Unicode ))
# corresponding to profile display name, unique key, Spawner class,
# dictionary of spawner config options, comma separated list of authorized groups..
# 
# The first three values will be exposed in the input_template as {display},
# {key}, and {type}
#
 c.ProfilesSpawner.default_profiles = [
    ( "Sudospawner group1", 'sudospawner', 'sudospawner.SudoSpawner', {'cmd':['sudospawner-singleuser'], 'notebook_dir':''}, 'group1' ),
    ( "Sudospawner group2", 'sudospawner', 'sudospawner.SudoSpawner', {'cmd':['sudospawner-singleuser'], 'notebook_dir':''}, 'group2' ),
    ( "Global spawner", 'sudospawner', 'sudospawner.SudoSpawner', {'cmd':['sudospawner-singleuser'], 'notebook_dir':''}, '*' )

]

History