Major upgrade: 1.* to 2.*#
Z2JH 2 contains several breaking changes, including some that affect the security of your deployment. This guide will help you upgrade from 1.* to 2.*.
Security: breaking change to
NetworkPolicy egress rules have been extended with a new property. If you have configured any of:
you must review your configuration as additional default egress routes have been added.
*.networkPolicy.egress controlled all egress but a new property
*.networkPolicy.egressAllowRules add additional egress rules by default.
If you have configured
singleuser to restrict the permissions to establish
outbound network connections, then this upgrade is likely to escalate those
permissions unless you revise your configuration. The new configuration
*.networkPolicy.egressAllowRules are by default granting most of the egress
permissions previously granted by default via the
*.networkPolicy.egress are now by default not providing
If you for example had overridden the previously very permissive default value
singleuser.networkPolicy.egress to be less permissive, you should consider
singleuser.networkPolicy.egressAllowRules like this
to not risk escalating the permissions.
singleuser: networkPolicy: egressAllowRules: cloudMetadataServer: false dnsPortsPrivateIPs: false nonPrivateIPs: false privateIPs: false
JupyterLab and Jupyter Server#
The default singleuser server is JupyterLab, running on Jupyter server. To switch back to Jupyter Notebook either configure/rebuild your singleuser image to default to notebook, or see the documentation on user interfaces
KubeSpawner prevents privilege escalation such as sudo by default#
By default processes cannot escalate their privileges.
For example, a user cannot use sudo to switch to root.
If you have configured sudo or some other privilege escalation method inside your singleuser image you must set
singleuser: allowPrivilegeEscalation: true
If you want to add custom arguments to the command, you must specify the full command and any arguments in
singleuser.cmd, for example:
singleuser: cmd: - jupyterhub-singleuser - "--collaborative" - "--debug"
hub.config was used to configure some JupyterHub traitlets it would override any custom configuration files mounted into
jupyterhub_config.d in the hub container.
In 2.0.0 all extra customisations (e.g. using
hub.extraConfig to provide in-line configuration, or
hub.extraFiles to mount files into
jupyterhub_config.d) will always take precedence over any Helm chart values.
Advanced customisation of the user scheduler using plugins now requires Kubernetes 1.21+, and the configuration must follow
Customisation is no longer possible with Kubernetes 1.20.
If you are using the user scheduler without custom plugin configuration you are not affected.
This Helm chart uses Kubernetes resources that are not available in Kubernetes versions prior to 1.20.
In previous versions of Z2JH
hub.fsGid set a supplemental group ID, which is required on some K8s systems to ensure JupyterHub has permissions to read/write files on a volume.
This has been replaced by the more general
To upgrade set:
hub: podSecurityContext: fsGroup: GROUP-ID
The hub container base image has switched from
python:3.9-slim-bullseye which is based on
If you have extended the Z2JH hub image please review the hub Dockerfile.
Note the singleuser image is not affected.
If you previously disabled RBAC using
rbac.enable: False you should set
rbac: create: False hub: serviceAccount: create: false proxy: traefik: serviceAccount: create: false scheduling: userScheduler: serviceAccount: create: false prePuller: hook: serviceAccount: create: false
When you have updated your configuration follow the rest of the upgrade guide.