Major upgrade: 3.* to 4.*#

zero-to-jupyterhub 4.0 is a major upgrade that may require some changes to your configuration, depending on what features you may use. This mostly comes in the form of some upgraded packages, described below.

See also

JupyterHub 5#

zero-to-jupyterhub 4.0 upgrades the JupyterHub version from 4.1.6 to 5.2.1.

See also

For more detailed changes in JupyterHub, see JupyterHub’s own documentation on upgrading to version 5:

Especially if you use features like per-user subdomains or custom page templates.

Allowing users#

JupyterHub 5 promotes the allow_all and allow_existing_users configuration used on OAuthenticator to all other Authenticators. If you have not explicitly allowed users, the default is to allow no users (this was already the default if you were using OAuth). If you are using an Authenticator where all users who can successfully authenticate should have access, set:

hub:
  config:
    Authenticator:
      allow_all: true

to explicitly opt in to this behavior that was previously the default for some authenticators.

KubeSpawner 7#

zero-to-jupyterhub 4.0 upgrades the KubeSpawner version from 6 to 7. The main relevant change here is the “slug scheme” used to compute names of resources such as pods and PVC (user storage) is changed.

The new scheme is called “safe” and is the default, whereas the old scheme is called “escape”. If you do not have any custom templated fields, it is unlikely that anything should change for you and everything should work. If, however, you specify custom templated fields such as volume mounts or environment variables, especially those that have the {username} or {servername} fields, those values are likely to change under the new scheme for some usernames. In particular, there are new fields that should make things easier:

  • {user_server} combines the username and server name, and is equivalent to {username}{servername} in the old escape scheme. It is the recommended value when a string should be unique per named server, as opposed to per user.

  • {pod_name}, {pvc_name} are now available to reference the fully resolved names of these objects and can be used to avoid duplicating templates.

You can opt in globally to keep the kubespawner 6 behavior with:

hub:
  config:
    KubeSpawner:
      slug_scheme: escape

which should result in no changes for you from previous behavior.

One user-facing place where a default template may require administrator action is if you are using:

singleuser:
  storage:
    type: static

The default value for subPath is {username} which may resolve to a different value for some usernames, which could appear like a ‘lost’ home directory because the mount path changes. The data is not lost, but the mount location has changed. To ensure this value doesn’t change, you can use:

singleuser:
  storage:
    type: static
    static:
      subPath: "{escaped_username}"

which applies the previous ‘escape’ scheme to the subPath. Alternatively, you can keep the new scheme, and perform a one-time migration to move files for the affected usernames.

See also