Previous Next

Helm Chart Configuration Reference¶

The JupyterHub helm chart is configurable so that you can customize your JupyterHub setup however you’d like. You can extend user resources, build off of different Docker images, manage security and authentication, and more.

Below is a description of the fields that are exposed with the JupyterHub helm chart. For more guided information about some specific things you can do with modifications to the helm chart, see the extending jupyterhub and user environment pages.

singleuser¶

Options for customizing the environment that is provided to the users after they log in.

singleuser.image¶

Set custom image name / tag used for spawned users.

This image is used to launch the pod for each user.

singleuser.image.tag¶

The tag of the image to use.

This is the value after the : in your full image name.

singleuser.image.name¶

Name of the image, without the tag.

Examples:

yuvipanda/wikimedia-hub-user
gcr.io/my-project/my-user-image

singleuser.imagePullPolicy¶

Set the imagePullPolicy on the singleuser pods that are spun up by the hub.

See the kubernetes docs for more info on what the values mean.

singleuser.cpu¶

Set CPU limits & guarantees that are enforced for each user. See: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/

singleuser.cpu.limit¶

singleuser.cpu.guarantee¶

singleuser.imagePullSecret¶

Create a custom image pull secret used for spawned users.

This secret is created in the same namespace as your jupyterhub deployment and will be used to pull your single user image.

singleuser.imagePullSecret.registry¶

Name of the private registry you want to create a credential set for.

Examples:

private.jfrog.io
alexmorreale.privatereg.net

singleuser.imagePullSecret.username¶

Name of the user you want to use to connect to your private registry.

Examples:

alexmorreale
alex@pfc.com

singleuser.imagePullSecret.password¶

Password of the user you want to use to connect to your private registry.

Examples:

plaintextpassword
abc123SECRETzyx098

singleuser.memory¶

Set Memory limits & guarantees that are enforced for each user. See: https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/

singleuser.memory.limit¶

singleuser.memory.guarantee¶

hub¶

hub.fsGid¶

The gid the hub process should be using when touching any volumes mounted. Use this only if you are building your own image & know that a group with this gid exists inside the hub container! Advanced feature, handle with care! Defaults to 1000, which is the gid of the jovyan user that is present in the default hub image.

hub.uid¶

The UID the hub process should be running as. Use this only if you are building your own image & know that a user with this uid exists inside the hub container! Advanced feature, handle with care! Defaults to 1000, which is the uid of the jovyan user that is present in the default hub image.

hub.imagePullPolicy¶

Set the imagePullPolicy on the hub pod.

See the kubernetes docs for more info on what the values mean.

hub.extraEnv¶

Extra environment variables that should be set for the hub pod.

A list of EnvVar objects.

These are usually used in two circumstances:

Passing parameters to some custom code specified with extraConfig
Passing parameters to an authenticator or spawner that can be directly customized by environment variables (rarer)

hub.image¶

Set custom image name / tag for the hub pod.

Use this to customize which hub image is used. Note that you must use a version of the hub image that was bundled with this particular version of the helm-chart - using other images might not work.

hub.image.tag¶

The tag of the image to pull.

This is the value after the : in your full image name.

hub.image.name¶

Name of the image, without the tag.

Examples:

yuvipanda/wikimedia-hub
gcr.io/my-project/my-hub

hub.labels¶

Extra labels to add to the hub pod.

See the kubernetes documentation to learn more about labels.

hub.db¶

hub.db.pvc¶

Customize the Persistent Volume Claim used when hub.db.type is sqlite-pvc.

hub.db.pvc.annotations¶

Annotations to apply to the PVC containing the sqlite database.

TODO: Link to pvc annotations

hub.db.pvc.selector¶

Selectors to set for the PVC containing the sqlite database.

Useful when you are using a static PVC.

TODO: Link to pvc selector docs.

hub.db.pvc.storage¶

Size of disk to request for the database disk.

hub.db.url¶

Connection string when hub.db.type is mysql or postgres.

See documentation for hub.db.type for more details on the format of this property.

hub.db.type¶

Type of database backend to use for the hub database.

The Hub requires a persistent database to function, and this lets you specify where it should be stored.

The various options are:

sqlite-pvc

Use an sqlite database kept on a persistent volume attached to the hub.

By default, this disk is dynamically created using the default [dynamic provisioner]. You can customize how this disk is created / attached by setting various properties under hub.db.pvc.

This is the default setting, and should work well for most cloud provider deployments.
sqlite-memory

Use an in-memory sqlite database. This should only be used for testing, since the database is erased whenever the hub pod restarts - causing the hub to lose all memory of users who had logged in before.

When using this for testing, make sure you delete all other objects that the hub has created (such as user pods, user PVCs, etc) every time the hub restarts. Otherwise you might run into errors about duplicate resources.
mysql

Use an externally hosted mysql database.

You have to specify an sqlalchemy connection string for the mysql database you want to connect to in hub.db.url if using this option.

The general format of the connection string is:
```
mysql+pymysql://<db-username>:<db-password>@<db-hostname>:<db-port>/<db-name>
```
The user specified in the connection string must have the rights to create tables in the database specified.

Note that if you use this, you must also set hub.cookieSecret.
postgres

Use an externally hosted postgres database.

You have to specify an sqlalchemy connection string for the postgres database you want to connect to in hub.db.url if using this option.

The general format of the connection string is:
```
postgres+psycopg2://<db-username>:<db-password>@<db-hostname>:<db-port>/<db-name>
```
The user specified in the connection string must have the rights to create tables in the database specified.

Note that if you use this, you must also set hub.cookieSecret.

hub.cookieSecret¶

A 64-byte cryptographically secure randomly generated string used to sign values of secure cookies set by the hub. If unset, jupyterhub will generate one on startup and save it in the file jupyterhub_cookie_secret in the /srv/jupyterhub directory of the hub container. Value set here will override the value in jupyterhub_cookie_secret.

You do not need to set this at all if you are using the default configuration for storing databases - sqlite on a persistent volume (with hub.db.type set to the default sqlite-pvc). If you are using an external database, then you must set this value explicitly - or your users will keep getting logged out each time the hub pod restarts.

This must be generated with openssl rand -hex 32.

Changing this value will all user logins to be invalidated. If this secret leaks, immediately change it to something else, or user data can be compromised

hub.extraConfig¶

Arbitrary extra python based configuration that should be in jupyterhub_config.py.

This is the escape hatch - if you want to configure JupyterHub to do something specific that is not present here as an option, you can just write the raw Python to do it here.

Non-exhaustive examples of things you can do here:

Subclass authenticator / spawner to do a custom thing
Dynamically launch different images for different sets of images
Inject an auth token from GitHub authenticator into user pod
Anything else you can think of!

Since this is usually a multi-line string, you want to format it using YAML’s | operator.

For example:

hub:
  extraConfig: |
    c.JupyterHub.something = 'something'
    c.Spawner.somethingelse = 'something else'

No validation of this python is performed! If you make a mistake here, it will probably manifest as either the hub pod going into Error or CrashLoopBackoff states, or in some special cases, the hub running but… just doing very random things. Be careful!

proxy¶

proxy.secretToken¶

A 64-byte cryptographically secure randomly generated string used to secure communications between the hub and the configurable-http-proxy.

This must be generated with openssl rand -hex 32.

Changing this value will cause the proxy and hub pods to restart. It is good security practice to rotate these values over time. If this secret leaks, immediately change it to something else, or user data can be compromised

auth¶

auth.state¶

auth.state.cryptoKey¶

auth_state will be encrypted and stored in the Hub’s database. This can include things like authentication tokens, etc. to be passed to Spawners as environment variables. Encrypting auth_state requires the cryptography package. It must contain one (or more, separated by ;) 32B encryption keys. These can be either base64 or hex-encoded. The JUPYTERHUB_CRYPT_KEY environment variable for the hub pod is set using this entry.

This can be generated with openssl rand -hex 32.

If encryption is unavailable, auth_state cannot be persisted.

auth.state.enabled¶

Enable persisting auth_state (if available). See: http://jupyterhub.readthedocs.io/en/latest/api/auth.html

Tips and command snippets Official JupyterHub and Project Jupyter Documentation