Reference¶

class multicluster_kubespawner.MultiClusterKubeSpawner(**kwargs)¶

args c.MultiClusterKubeSpawner.args = List()¶

Extra arguments to be passed to the single-user server.

Some spawners allow shell-style expansion here, allowing you to use environment variables here. Most, including the default, do not. Consult the documentation for your spawner to verify!

auth_state_hook c.MultiClusterKubeSpawner.auth_state_hook = Any(None)¶

An optional hook function that you can implement to pass auth_state to the spawner after it has been initialized but before it starts. The auth_state dictionary may be set by the .authenticate() method of the authenticator. This hook enables you to pass some or all of that information to your spawner.

Example:

def userdata_hook(spawner, auth_state):
    spawner.userdata = auth_state["userdata"]

c.Spawner.auth_state_hook = userdata_hook

cmd c.MultiClusterKubeSpawner.cmd = Command()¶

The command used for starting the single-user server.

Provide either a string or a list containing the path to the startup script command. Extra arguments, other than this path, should be provided via args.

This is usually set if you want to start the single-user server in a different python environment (with virtualenv/conda) than JupyterHub itself.

Some spawners allow shell-style expansion here, allowing you to use environment variables. Most, including the default, do not. Consult the documentation for your spawner to verify!

consecutive_failure_limit c.MultiClusterKubeSpawner.consecutive_failure_limit = Int(0)¶

Maximum number of consecutive failures to allow before shutting down JupyterHub.

This helps JupyterHub recover from a certain class of problem preventing launch in contexts where the Hub is automatically restarted (e.g. systemd, docker, kubernetes).

A limit of 0 means no limit and consecutive failures will not be tracked.

cpu_guarantee c.MultiClusterKubeSpawner.cpu_guarantee = Float(None)¶

Minimum number of cpu-cores a single-user notebook server is guaranteed to have available.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

This is a configuration setting. Your spawner must implement support for the limit to work. The default spawner, LocalProcessSpawner, does not implement this support. A custom spawner must add support for this setting for it to be enforced.

cpu_limit c.MultiClusterKubeSpawner.cpu_limit = Float(None)¶

Maximum number of cpu-cores a single-user notebook server is allowed to use.

If this value is set to 0.5, allows use of 50% of one CPU. If this value is set to 2, allows use of up to 2 CPUs.

The single-user notebook server will never be scheduled by the kernel to use more cpu-cores than this. There is no guarantee that it can access this many cpu-cores.

create_namespace c.MultiClusterKubeSpawner.create_namespace = Bool(True)¶

Create namespace for each user when needed.

For each user, a namespace is created if needed based on namespace_template.

If set to false, set namespace_template to always resolve to a string that points to an existing template.

debug c.MultiClusterKubeSpawner.debug = Bool(False)¶: Enable debug-logging of the single-user server

default_url c.MultiClusterKubeSpawner.default_url = Unicode('')¶

The URL the single-user server should start in.

{username} will be expanded to the user’s username

Example uses:

You can set notebook_dir to / and default_url to /tree/home/{username} to allow people to navigate the whole filesystem from their notebook server, but still start in their home directory.
Start with /notebooks instead of /tree if default_url points to a notebook instead of a directory.
You can set this to /lab to have JupyterLab start by default, rather than Jupyter Notebook.

environment c.MultiClusterKubeSpawner.environment = Dict()¶

Extra environment variables to set for the single-user server’s process.

Environment variables that end up in the single-user server’s process come from 3 sources:

This environment configurable
The JupyterHub process’ environment variables that are listed in env_keep
Variables to establish contact between the single-user notebook and the hub (such as JUPYTERHUB_API_TOKEN)

The environment configurable should be set by JupyterHub administrators to add installation specific environment variables. It is a dict where the key is the name of the environment variable, and the value can be a string or a callable. If it is a callable, it will be called with one parameter (the spawner instance), and should return a string fairly quickly (no blocking operations please!).

Note that the spawner class’ interface is not guaranteed to be exactly same across upgrades, so if you are using the callable take care to verify it continues to work after upgrades!

Changed in version 1.2: environment from this configuration has highest priority, allowing override of ‘default’ env variables, such as JUPYTERHUB_API_URL.

http_timeout c.MultiClusterKubeSpawner.http_timeout = Int(30)¶

Timeout (in seconds) before giving up on a spawned HTTP server

Once a server has successfully been spawned, this is the amount of time we wait before assuming that the server is unable to accept connections.

hub_connect_url c.MultiClusterKubeSpawner.hub_connect_url = Unicode(None)¶

The URL the single-user server should connect to the Hub.

If the Hub URL set in your JupyterHub config is not reachable from spawned notebooks, you can set differnt URL by this config.

Is None if you don’t need to change the URL.

image c.MultiClusterKubeSpawner.image = Unicode('pangeo/pangeo-notebook:latest')¶

Docker image to use for spawning user’s containers.

Defaults to pangeo/pangeo-notebook:latest

Name of the container + a tag, same as would be used with a docker pull command. If tag is set to latest, kubernetes will check the registry each time a new user is spawned to see if there is a newer image available. If available, new image will be pulled. Note that this could cause long delays when spawning, especially if the image is large. If you do not specify a tag, whatever version of the image is first pulled on the node will be used, thus possibly leading to inconsistent images on different nodes. For all these reasons, it is recommended to specify a specific immutable tag for the image.

If your image is very large, you might need to increase the timeout for starting the single user container from the default. You can set this with:

c.Spawner.start_timeout = 60 * 5  # Up to 5 minutes

ingress_public_url c.MultiClusterKubeSpawner.ingress_public_url = Unicode('')¶: Address of the ingress controller’s public endpoint in the targe cluster

kubernetes_context c.MultiClusterKubeSpawner.kubernetes_context = Unicode('')¶: Kubernetes context to use for connecting to the kubernetes cluster.

mem_guarantee c.MultiClusterKubeSpawner.mem_guarantee = ByteSpecification(None)¶

Minimum number of bytes a single-user notebook server is guaranteed to have available.

Allows the following suffixes:

K -> Kilobytes
M -> Megabytes
G -> Gigabytes
T -> Terabytes

mem_limit c.MultiClusterKubeSpawner.mem_limit = ByteSpecification(None)¶

Maximum number of bytes a single-user notebook server is allowed to use.

Allows the following suffixes:

K -> Kilobytes
M -> Megabytes
G -> Gigabytes
T -> Terabytes

If the single user server tries to allocate more memory than this, it will fail. There is no guarantee that the single-user notebook server will be able to allocate this much memory - only that it can not allocate more than this.

namespace_template c.MultiClusterKubeSpawner.namespace_template = Unicode('jupyter-{{username}}')¶: Jinja2 template to generate namespace each user is spawned into.

notebook_dir c.MultiClusterKubeSpawner.notebook_dir = Unicode('')¶

Path to the notebook directory for the single-user server.

The user sees a file listing of this directory when the notebook interface is started. The current interface does not easily allow browsing beyond the subdirectories in this directory’s tree.

~ will be expanded to the home directory of the user, and {username} will be replaced with the name of the user.

Note that this does not prevent users from accessing files outside of this path! They can do so with many other means.

oauth_roles c.MultiClusterKubeSpawner.oauth_roles = Union()¶

Allowed roles for oauth tokens.

This sets the maximum and default roles assigned to oauth tokens issued by a single-user server’s oauth client (i.e. tokens stored in browsers after authenticating with the server), defining what actions the server can take on behalf of logged-in users.

Default is an empty list, meaning minimal permissions to identify users, no actions can be taken on their behalf.

options_form c.MultiClusterKubeSpawner.options_form = Union()¶

An HTML form for options a user can specify on launching their server.

The surrounding <form> element and the submit button are already provided.

For example:

Set your key:
<input name="key" val="default_key"></input>
<br>
Choose a letter:
<select name="letter" multiple="true">
  <option value="A">The letter A</option>
  <option value="B">The letter B</option>
</select>

The data from this form submission will be passed on to your spawner in self.user_options

Instead of a form snippet string, this could also be a callable that takes as one parameter the current spawner instance and returns a string. The callable will be called asynchronously if it returns a future, rather than a str. Note that the interface of the spawner class is not deemed stable across versions, so using this functionality might cause your JupyterHub upgrades to break.

options_from_form c.MultiClusterKubeSpawner.options_from_form = Callable()¶

Interpret HTTP form data

Form data will always arrive as a dict of lists of strings. Override this function to understand single-values, numbers, etc.

This should coerce form data into the structure expected by self.user_options, which must be a dict, and should be JSON-serializeable, though it can contain bytes in addition to standard JSON data types.

This method should not have any side effects. Any handling of user_options should be done in .start() to ensure consistent behavior across servers spawned via the API and form submission page.

Instances will receive this data on self.user_options, after passing through this function, prior to Spawner.start.

Changed in version 1.0: user_options are persisted in the JupyterHub database to be reused on subsequent spawns if no options are given. user_options is serialized to JSON as part of this persistence (with additional support for bytes in case of uploaded file data), and any non-bytes non-jsonable values will be replaced with None if the user_options are re-used.

patches c.MultiClusterKubeSpawner.patches = Dict()¶

Customize generated resources by patching them where necessary.

A jinja2 template that can produce multiple YAML documents, which will be merged with generated resources from resources. metadata.name will be used to decide which resources are patched.

The patches are sorted by key before they are evaluated.

poll_interval c.MultiClusterKubeSpawner.poll_interval = Int(30)¶

Interval (in seconds) on which to poll the spawner for single-user server’s status.

At every poll interval, each spawner’s .poll method is called, which checks if the single-user server is still running. If it isn’t running, then JupyterHub modifies its own state accordingly and removes appropriate routes from the configurable proxy.

port c.MultiClusterKubeSpawner.port = Int(8888)¶

The port the user server process listens on inside the container.

Since each pod gets its own network stack with its own IP, all servers can listen on the same well known port 8888. A JupyterHub operator will most likely not need to change this.

post_stop_hook c.MultiClusterKubeSpawner.post_stop_hook = Any(None)¶

An optional hook function that you can implement to do work after the spawner stops.

This can be set independent of any concrete spawner implementation.

pre_spawn_hook c.MultiClusterKubeSpawner.pre_spawn_hook = Any(None)¶

An optional hook function that you can implement to do some bootstrapping work before the spawner starts. For example, create a directory for your user or load initial content.

This can be set independent of any concrete spawner implementation.

This maybe a coroutine.

Example:

from subprocess import check_call
def my_hook(spawner):
    username = spawner.user.name
    check_call(['./examples/bootstrap-script/bootstrap.sh', username])

c.Spawner.pre_spawn_hook = my_hook

profile_form_template c.MultiClusterKubeSpawner.profile_form_template = Unicode("\n <style>\n /* The profile description should not be bold, even though it is inside the <label> tag */\n #multicluster-kubespawner-profiles-list label p {\n font-weight: normal;\n }\n </style>\n\n <div class='form-group' id='multicluster-kubespawner-profiles-list'>\n {% for profile in profile_list %}\n <label for='profile-item-{{ profile.slug }}' class='form-control input-group'>\n <div class='col-md-1'>\n <input type='radio' name='profile' id='profile-item-{{ profile.slug }}' value='{{ profile.slug }}' {% if profile.default %}checked{% endif %} />\n </div>\n <div class='col-md-11'>\n <strong>{{ profile.display_name }}</strong>\n {% if profile.description %}\n <p>{{ profile.description }}</p>\n {% endif %}\n </div>\n </label>\n {% endfor %}\n </div>\n ")¶

Jinja2 template for constructing profile list shown to user.

Used when profile_list is set.

The contents of profile_list are passed in to the template. This should be used to construct the contents of a HTML form. When posted, this form is expected to have an item with name profile and the value the index of the profile in profile_list.

profile_list c.MultiClusterKubeSpawner.profile_list = Union()¶

List of profiles to offer for selection by the user.

Signature is: List(Dict()), where each item is a dictionary that has two keys:

display_name: the human readable display name (should be HTML safe)
slug: the machine readable slug to identify the profile (missing slugs are generated from display_name)
description: Optional description of this profile displayed to the user.
spawner_override: a dictionary with overrides to apply to the Spawner settings. Each value can be either the final value to change or a callable that take the Spawner instance as parameter and return the final value.
default: (optional Bool) True if this is the default selected option

Instead of a list of dictionaries, this could also be a callable that takes as one parameter the current spawner instance and returns a list of dictionaries. The callable will be called asynchronously if it returns a future, rather than a list. Note that the interface of the spawner class is not deemed stable across versions, so using this functionality might cause your JupyterHub or MultiClusterKubeSpawner upgrades to break.

resources c.MultiClusterKubeSpawner.resources = Dict()¶

Jinja2 Template to generate kubernetes resources generated by the spawner.

Resources are sorted by key before they are evaluated.

ssl_alt_names c.MultiClusterKubeSpawner.ssl_alt_names = List()¶

List of SSL alt names

May be set in config if all spawners should have the same value(s), or set at runtime by Spawner that know their names.

ssl_alt_names_include_local c.MultiClusterKubeSpawner.ssl_alt_names_include_local = Bool(True)¶: Whether to include DNS:localhost, IP:127.0.0.1 in alt names

start_timeout c.MultiClusterKubeSpawner.start_timeout = Int(60)¶

Timeout (in seconds) before giving up on starting of single-user server.

This is the timeout for start to return, not the timeout for the server to respond. Callers of spawner.start will assume that startup has failed if it takes longer than this. start should return when the server process is started and its location is known.

Create additional per-user kubernetes resources with resources