Configuration Reference¶
The JupyterHub Helm
chart is configurable by
values in your config.yaml
. In this way, you can extend user resources, build off
of different Docker images, manage security and authentication, and more.
Below is a description of many but not all of the configurable values for the Helm chart. To see all configurable options, inspect their default values defined here.
For more guided information about some specific things you can do with modifications to the helm chart, see the Customization Guide.
imagePullSecret¶
This is configuration to create a k8s Secret resource of type: kubernetes.io/dockerconfigjson
, with credentials to pull images from a
private image registry. If you opt to do so, it will be available for use
by all pods in their respective spec.imagePullSecrets
alongside other
k8s Secrets defined in imagePullSecrets
or the pod respective
...image.pullSecrets
configuration.
In other words, using this configuration option can automate both the otherwise manual creation of a k8s Secret and the otherwise manual configuration to reference this k8s Secret in all the pods of the Helm chart.
# you won't need to create a k8s Secret manually...
kubectl create secret docker-registry image-pull-secret \
--docker-server=<REGISTRY> \
--docker-username=<USERNAME> \
--docker-email=<EMAIL> \
--docker-password=<PASSWORD>
If you just want to let all Pods reference an existing secret, use the
imagePullSecrets
configuration instead.
To learn the username and password fields to access a gcr.io registry from a Kubernetes cluster not associated with the same google cloud credentials, look into this guide and read the notes about the password.
imagePullSecret.create¶
Toggle the creation of the k8s Secret with provided credentials to access a private image registry.
imagePullSecret.automaticReferenceInjection¶
Toggle the automatic reference injection of the created Secret to all
pods’ spec.imagePullSecrets
configuration.
imagePullSecret.registry¶
Name of the private registry you want to create a credential set for. It will default to Docker Hub’s image registry.
Examples:
https://index.docker.io/v1/
quay.io
eu.gcr.io
alexmorreale.privatereg.net
imagePullSecret.username¶
Name of the user you want to use to connect to your private registry.
For external gcr.io, you will use the _json_key
.
Examples:
alexmorreale
alex@pfc.com
_json_key
imagePullSecret.password¶
Password for the private image registry’s user.
Examples:
plaintextpassword
abc123SECRETzyx098
For gcr.io registries the password will be a big JSON blob for a Google cloud service account, it should look something like below.
password: |-
{
"type": "service_account",
"project_id": "jupyter-se",
"private_key_id": "f2ba09118a8d3123b3321bd9a7d6d0d9dc6fdb85",
...
}
Learn more in this guide.
imagePullSecrets¶
Chart wide configuration to append k8s Secret references to all its
pod’s spec.imagePullSecrets
configuration.
This will not override or get overridden by pod specific configuration, but instead augment the pod specific configuration.
You can use both the k8s native syntax, where each list element is like
{"name": "my-secret-name"}
, or you can let list elements be strings
naming the secrets directly.
hub¶
hub.command¶
A list of strings to be used to replace the JupyterHub image’s
ENTRYPOINT
entry. Note that in k8s lingo, the Dockerfile’s
ENTRYPOINT
is called command
. The list of strings will be expanded
with Helm’s template function tpl
which can render Helm template
logic inside curly braces ({{... }}
).
This could be useful to wrap the invocation of JupyterHub itself in some custom way.
For more details, see the Kubernetes documentation.
hub.args¶
A list of strings to be used to replace the JupyterHub image’s CMD
entry as well as the Helm chart’s default way to start JupyterHub.
Note that in k8s lingo, the Dockerfile’s CMD
is called args
. The
list of strings will be expanded with Helm’s template function tpl
which can render Helm template logic inside curly braces ({{... }}
).
Warning
By replacing the entire configuration file, which is mounted to
/etc/jupyterhub/jupyterhub_config.py
by the Helm chart, instead of
appending to it with hub.extraConfig
, you expose your deployment for
issues stemming from getting out of sync with the Helm chart’s config
file.
These kind of issues will be significantly harder to debug and diagnose, and can due to this could cause a lot of time expenditure for both the community maintaining the Helm chart as well as yourself, even if this wasn’t the reason for the issue.
Due to this, we ask that you do your _absolute best to avoid replacing
the default provided jupyterhub_config.py
file. It can often be
possible. For example, if your goal is to have a dedicated .py file
for more extensive additions that you can syntax highlight and such
and feel limited by passing code in hub.extraConfig
which is part of
a YAML file, you can use this
trick
instead.
hub:
args:
- "jupyterhub"
- "--config"
- "/etc/jupyterhub/jupyterhub_config.py"
- "--debug"
- "--upgrade-db"
For more details, see the Kubernetes documentation.
hub.cookieSecret¶
A 32-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. A value set here will make JupyterHub overwrite any previous file.
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.
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
# to generate a value, run
openssl rand -hex 32
hub.image¶
Set custom image name, tag, pullPolicy, or pullSecrets for the pod.
hub.image.tag¶
The tag of the image to pull. This is the value following :
in
complete image specifications.
# example tags
v1.11.1
zhy270a
hub.image.pullPolicy¶
Configures the Pod’s spec.imagePullPolicy
.
See the Kubernetes docs for more info.
hub.image.pullSecrets¶
A list of references to existing Kubernetes Secrets with credentials to pull the image.
This Pod’s final imagePullSecrets
k8s specification will be a
combination of:
This list of k8s Secrets, specific for this pod.
The list of k8s Secrets, for use by all pods in the Helm chart, declared in this Helm charts configuration called
imagePullSecrets
.A k8s Secret, for use by all pods in the Helm chart, if conditionally created from image registry credentials provided under
imagePullSecret
ifimagePullSecret.create
is set to true.
# example - k8s native syntax
pullSecrets:
- name: my-k8s-secret-with-image-registry-credentials
# example - simplified syntax
pullSecrets:
- my-k8s-secret-with-image-registry-credentials
hub.networkPolicy¶
This configuration regards the creation and configuration of a k8s NetworkPolicy resource.
hub.networkPolicy.enabled¶
Toggle the creation of the NetworkPolicy resource for this pod.
hub.networkPolicy.ingress¶
Additional ingress rules to add except those that is known to be needed by the respective pods in the Helm chart.
hub.networkPolicy.egress¶
Additional egress rules to add except those that is known to be needed by the respective pods in the Helm chart.
The default value of this egress is to allow all traffic, except for the singleuser.networkPolicy.egress
, which is also limiting access to a metadata server that can be exploited.
If you want to restrict egress, you can override this permissive default to be an empty list.
hub.networkPolicy.interNamespaceAccessLabels¶
This configuration option determines if both namespaces and pods
in other namespaces, that have specific access labels, should be
accepted to allow ingress (set to accept
), or, if the labels are
to be ignored when applied outside the local namespace (set to
ignore
).
The available access labels for respective NetworkPolicy resources are:
hub.jupyter.org/network-access-hub: "true"
(hub)hub.jupyter.org/network-access-proxy-http: "true"
(proxy.chp, proxy.traefik)hub.jupyter.org/network-access-proxy-api: "true"
(proxy.chp)hub.jupyter.org/network-access-singleuser: "true"
(singleuser)
hub.networkPolicy.allowedIngressPorts¶
A rule to allow ingress on these ports will be added no matter
what the origin of the request is. The default setting for
proxy.chp
and proxy.traefik
’s networkPolicy configuration is
[http, https]
, while it is []
for other networkPolicies.
Note that these port names or numbers target a Pod’s port name or number, not a k8s Service’s port name or number.
hub.db¶
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 created by the cloud provider using dynamic provisioning configured by a storage class. 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.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.
See the Kubernetes documentation for more details about annotations.
hub.db.pvc.selector¶
Label selectors to set for the PVC containing the sqlite database.
Useful when you are using a specific PV, and want to bind to that and only that.
See the Kubernetes documentation for more details about using a label selector for what PV to bind to.
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.password¶
Password for the database when hub.db.type
is mysql or postgres.
hub.initContainers¶
list of initContainers to be run with hub pod. See Kubernetes Docs
hub:
initContainers:
- name: init-myservice
image: busybox:1.28
command: ['sh', '-c', 'command1']
- name: init-mydb
image: busybox:1.28
command: ['sh', '-c', 'command2']
hub.extraEnv¶
Extra environment variables that should be set for the hub pod.
Environment variables are usually used to:
Pass parameters to some custom code in
hub.extraConfig
.Configure code running in the hub pod, such as an authenticator or spawner.
String literals with $(ENV_VAR_NAME)
will be expanded by Kubelet which
is a part of Kubernetes.
hub:
extraEnv:
# basic notation (for literal values only)
MY_ENV_VARS_NAME1: "my env var value 1"
# explicit notation (the "name" field takes precedence)
HUB_NAMESPACE:
name: HUB_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# implicit notation (the "name" field is implied)
PREFIXED_HUB_NAMESPACE:
value: "my-prefix-$(HUB_NAMESPACE)"
SECRET_VALUE:
valueFrom:
secretKeyRef:
name: my-k8s-secret
key: password
For more information, see the Kubernetes EnvVar specification.
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 write the raw Python to do it here.
extraConfig is a dict, so there can be multiple configuration snippets under different names. The configuration sections are run in alphabetical order.
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:
myConfig.py: |
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!
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.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.service¶
Object to configure the service the JupyterHub will be exposed on by the Kubernetes server.
hub.service.type¶
The Kubernetes ServiceType to be used.
The default type is ClusterIP
.
See the Kubernetes docs
to learn more about service types.
hub.service.ports¶
Object to configure the ports the hub service will be deployed on.
hub.service.ports.nodePort¶
The nodePort to deploy the hub service on.
hub.service.annotations¶
Kubernetes annotations to apply to the hub service.
hub.pdb¶
Set the Pod Disruption Budget for the hub pod.
See the Kubernetes documentation for more details about disruptions.
hub.pdb.enabled¶
Whether PodDisruptionBudget is enabled for the hub pod.
hub.existingSecret¶
Name of the existing secret in the kubernetes cluster, typically the hub-secret
.
This secret should represent the structure as otherwise generated by this chart:
apiVersion: v1
data:
proxy.token: < FILL IN >
values.yaml: < FILL IN >
kind: Secret
metadata:
name: hub-secret
NOTE: if you choose to manage the secret yourself, you are in charge of ensuring the secret having the proper contents.
hub.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
hub.tolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
proxy¶
proxy.chp¶
Configure the configurable-http-proxy (chp) pod managed by jupyterhub to route traffic both to itself and to user pods.
proxy.chp.networkPolicy¶
This configuration regards the creation and configuration of a k8s NetworkPolicy resource.
proxy.chp.networkPolicy.enabled¶
Toggle the creation of the NetworkPolicy resource for this pod.
proxy.chp.networkPolicy.ingress¶
Additional ingress rules to add except those that is known to be needed by the respective pods in the Helm chart.
proxy.chp.networkPolicy.egress¶
Additional egress rules to add except those that is known to be needed by the respective pods in the Helm chart.
The default value of this egress is to allow all traffic, except for the singleuser.networkPolicy.egress
, which is also limiting access to a metadata server that can be exploited.
If you want to restrict egress, you can override this permissive default to be an empty list.
proxy.chp.networkPolicy.interNamespaceAccessLabels¶
This configuration option determines if both namespaces and pods
in other namespaces, that have specific access labels, should be
accepted to allow ingress (set to accept
), or, if the labels are
to be ignored when applied outside the local namespace (set to
ignore
).
The available access labels for respective NetworkPolicy resources are:
hub.jupyter.org/network-access-hub: "true"
(hub)hub.jupyter.org/network-access-proxy-http: "true"
(proxy.chp, proxy.traefik)hub.jupyter.org/network-access-proxy-api: "true"
(proxy.chp)hub.jupyter.org/network-access-singleuser: "true"
(singleuser)
proxy.chp.networkPolicy.allowedIngressPorts¶
A rule to allow ingress on these ports will be added no matter
what the origin of the request is. The default setting for
proxy.chp
and proxy.traefik
’s networkPolicy configuration is
[http, https]
, while it is []
for other networkPolicies.
Note that these port names or numbers target a Pod’s port name or number, not a k8s Service’s port name or number.
proxy.chp.extraCommandLineFlags¶
A list of strings to be added as command line options when
starting
configurable-http-proxy
that will be expanded with Helm’s template function tpl
which
can render Helm template logic inside curly braces ({{ ... }}
).
proxy:
chp:
extraCommandLineFlags:
- "--auto-rewrite"
- "--custom-header {{ .Values.myCustomStuff }}"
Note that these will be appended last, and if you provide the same flag twice, the last flag will be used, which mean you can override the default flag values as well.
proxy.chp.extraEnv¶
Extra environment variables that should be set for the chp pod.
Environment variables are usually used here to:
override HUB_SERVICE_PORT or HUB_SERVICE_HOST default values
set CONFIGPROXY_SSL_KEY_PASSPHRASE for setting passphrase of SSL keys
String literals with $(ENV_VAR_NAME)
will be expanded by Kubelet which
is a part of Kubernetes.
proxy:
chp:
extraEnv:
# basic notation (for literal values only)
MY_ENV_VARS_NAME1: "my env var value 1"
# explicit notation (the "name" field takes precedence)
CHP_NAMESPACE:
name: CHP_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# implicit notation (the "name" field is implied)
PREFIXED_CHP_NAMESPACE:
value: "my-prefix-$(CHP_NAMESPACE)"
SECRET_VALUE:
valueFrom:
secretKeyRef:
name: my-k8s-secret
key: password
For more information, see the Kubernetes EnvVar specification.
proxy.chp.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
proxy.chp.tolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
proxy.secretToken¶
A 32-byte cryptographically secure randomly generated string used to secure communications between the hub and the configurable-http-proxy.
# to generate a value, run
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
proxy.service¶
Configuration of the k8s Service proxy-public
which either will
point to the autohttps
pod running Traefik for TLS termination, or
the proxy
pod running ConfigurableHTTPProxy. Incoming traffic from
users on the internet should always go through this k8s Service.
When this service targets the autohttps
pod which then routes to the
proxy
pod, a k8s Service named proxy-http
will be added targeting
the proxy
pod and only accepting HTTP traffic on port 80.
proxy.service.type¶
Default LoadBalancer
. See hub.service.type
for supported values.
proxy.service.labels¶
Extra labels to add to the proxy service.
See the Kubernetes docs to learn more about labels.
proxy.service.annotations¶
Annotations to apply to the service that is exposing the proxy.
See the Kubernetes documentation for more details about annotations.
proxy.service.nodePorts¶
Object to set NodePorts to expose the service on for http and https.
See the Kubernetes documentation for more details about NodePorts.
proxy.service.nodePorts.http¶
The HTTP port the proxy-public service should be exposed on.
proxy.service.nodePorts.https¶
The HTTPS port the proxy-public service should be exposed on.
proxy.service.extraPorts¶
Extra ports the k8s Service should accept incoming traffic on,
which will be redirected to either the autohttps
pod (treafik)
or the proxy
pod (chp).
See the Kubernetes documentation for the structure of the items in this list.
proxy.service.loadBalancerIP¶
The public IP address the proxy-public Kubernetes service should
be exposed on. This entry will end up at the configurable proxy
server that JupyterHub manages, which will direct traffic to user
pods at the /user
path and the hub pod at the /hub
path.
Set this if you want to use a fixed external IP address instead of a dynamically acquired one. This is relevant if you have a domain name that you want to point to a specific IP and want to ensure it doesn’t change.
proxy.service.loadBalancerSourceRanges¶
A list of IP CIDR ranges that are allowed to access the load balancer service. Defaults to allowing everyone to access it.
proxy.https¶
Object for customizing the settings for HTTPS used by the JupyterHub’s proxy. For more information on configuring HTTPS for your JupyterHub, see the HTTPS section in our security guide
proxy.https.enabled¶
Indicator to set whether HTTPS should be enabled or not on the proxy. Defaults to true
if the https object is provided.
proxy.https.type¶
The type of HTTPS encryption that is used.
Decides on which ports and network policies are used for communication via HTTPS. Setting this to secret
sets the type to manual HTTPS with a secret that has to be provided in the https.secret
object.
Defaults to letsencrypt
.
proxy.https.letsencrypt¶
proxy.https.letsencrypt.contactEmail¶
The contact email to be used for automatically provisioned HTTPS certificates by Let’s Encrypt. For more information see Set up automatic HTTPS. Required for automatic HTTPS.
proxy.https.manual¶
Object for providing own certificates for manual HTTPS configuration. To be provided when setting https.type
to manual
.
See Set up manual HTTPS
proxy.https.manual.key¶
The RSA private key to be used for HTTPS. To be provided in the form of
key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
proxy.https.manual.cert¶
The certificate to be used for HTTPS. To be provided in the form of
cert: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
proxy.https.secret¶
Secret to be provided when setting https.type
to secret
.
proxy.https.secret.name¶
Name of the secret
proxy.https.secret.key¶
Path to the private key to be used for HTTPS.
Example: 'tls.key'
proxy.https.secret.crt¶
Path to the certificate to be used for HTTPS.
Example: 'tls.crt'
proxy.https.hosts¶
You domain in list form. Required for automatic HTTPS. See Set up automatic HTTPS. To be provided like:
hosts:
- <your-domain-name>
proxy.pdb¶
Set the Pod Disruption Budget for the proxy pod.
See the Kubernetes documentation for more details about disruptions.
proxy.pdb.enabled¶
Whether PodDisruptionBudget is enabled for the proxy pod.
proxy.traefik¶
Configure the traefik proxy used to terminate TLS when ‘autohttps’ is enabled
proxy.traefik.labels¶
Extra labels to add to the traefik pod.
See the Kubernetes docs to learn more about labels.
proxy.traefik.networkPolicy¶
This configuration regards the creation and configuration of a k8s NetworkPolicy resource.
proxy.traefik.networkPolicy.enabled¶
Toggle the creation of the NetworkPolicy resource for this pod.
proxy.traefik.networkPolicy.ingress¶
Additional ingress rules to add except those that is known to be needed by the respective pods in the Helm chart.
proxy.traefik.networkPolicy.egress¶
Additional egress rules to add except those that is known to be needed by the respective pods in the Helm chart.
The default value of this egress is to allow all traffic, except for the singleuser.networkPolicy.egress
, which is also limiting access to a metadata server that can be exploited.
If you want to restrict egress, you can override this permissive default to be an empty list.
proxy.traefik.networkPolicy.interNamespaceAccessLabels¶
This configuration option determines if both namespaces and pods
in other namespaces, that have specific access labels, should be
accepted to allow ingress (set to accept
), or, if the labels are
to be ignored when applied outside the local namespace (set to
ignore
).
The available access labels for respective NetworkPolicy resources are:
hub.jupyter.org/network-access-hub: "true"
(hub)hub.jupyter.org/network-access-proxy-http: "true"
(proxy.chp, proxy.traefik)hub.jupyter.org/network-access-proxy-api: "true"
(proxy.chp)hub.jupyter.org/network-access-singleuser: "true"
(singleuser)
proxy.traefik.networkPolicy.allowedIngressPorts¶
A rule to allow ingress on these ports will be added no matter
what the origin of the request is. The default setting for
proxy.chp
and proxy.traefik
’s networkPolicy configuration is
[http, https]
, while it is []
for other networkPolicies.
Note that these port names or numbers target a Pod’s port name or number, not a k8s Service’s port name or number.
proxy.traefik.extraEnv¶
Extra environment variables that should be set for the traefik pod.
Environment Variables here may be used to configure traefik.
String literals with $(ENV_VAR_NAME)
will be expanded by Kubelet which
is a part of Kubernetes.
proxy:
traefik:
extraEnv:
# basic notation (for literal values only)
MY_ENV_VARS_NAME1: "my env var value 1"
# explicit notation (the "name" field takes precedence)
TRAEFIK_NAMESPACE:
name: TRAEFIK_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# implicit notation (the "name" field is implied)
PREFIXED_TRAEFIK_NAMESPACE:
value: "my-prefix-$(TRAEFIK_NAMESPACE)"
SECRET_VALUE:
valueFrom:
secretKeyRef:
name: my-k8s-secret
key: password
For more information, see the Kubernetes EnvVar specification.
proxy.traefik.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
proxy.traefik.tolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
auth¶
auth.state¶
auth.state.enabled¶
Enable persisting auth_state (if available). See: the documentation on authenticators
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 ;) 32-byte 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.
# to generate a value, run
openssl rand -hex 32
If encryption is unavailable, auth_state cannot be persisted.
singleuser¶
Options for customizing the environment that is provided to the users after they log in.
singleuser.networkPolicy¶
This configuration regards the creation and configuration of a k8s NetworkPolicy resource.
singleuser.networkPolicy.enabled¶
Toggle the creation of the NetworkPolicy resource for this pod.
singleuser.networkPolicy.ingress¶
Additional ingress rules to add except those that is known to be needed by the respective pods in the Helm chart.
singleuser.networkPolicy.egress¶
Additional egress rules to add except those that is known to be needed by the respective pods in the Helm chart.
The default value of this egress is to allow all traffic, except for the singleuser.networkPolicy.egress
, which is also limiting access to a metadata server that can be exploited.
If you want to restrict egress, you can override this permissive default to be an empty list.
singleuser.networkPolicy.interNamespaceAccessLabels¶
This configuration option determines if both namespaces and pods
in other namespaces, that have specific access labels, should be
accepted to allow ingress (set to accept
), or, if the labels are
to be ignored when applied outside the local namespace (set to
ignore
).
The available access labels for respective NetworkPolicy resources are:
hub.jupyter.org/network-access-hub: "true"
(hub)hub.jupyter.org/network-access-proxy-http: "true"
(proxy.chp, proxy.traefik)hub.jupyter.org/network-access-proxy-api: "true"
(proxy.chp)hub.jupyter.org/network-access-singleuser: "true"
(singleuser)
singleuser.networkPolicy.allowedIngressPorts¶
A rule to allow ingress on these ports will be added no matter
what the origin of the request is. The default setting for
proxy.chp
and proxy.traefik
’s networkPolicy configuration is
[http, https]
, while it is []
for other networkPolicies.
Note that these port names or numbers target a Pod’s port name or number, not a k8s Service’s port name or number.
singleuser.podNameTemplate¶
Template for the pod name of each user, such as jupyter-{username}{servername}
.
singleuser.cpu¶
Set CPU limits & guarantees that are enforced for each user. See: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
singleuser.cpu.limit¶
singleuser.cpu.guarantee¶
singleuser.memory¶
Set Memory limits & guarantees that are enforced for each user.
See the Kubernetes docs for more info.
singleuser.memory.limit¶
singleuser.memory.guarantee¶
Note that this field is referred to as requests by the Kubernetes API.
singleuser.image¶
Set custom image name, tag, pullPolicy, or pullSecrets for the pod.
singleuser.image.name¶
The name of the image, without the tag.
# example name
gcr.io/my-project/my-image
singleuser.image.tag¶
The tag of the image to pull. This is the value following :
in
complete image specifications.
# example tags
v1.11.1
zhy270a
singleuser.image.pullPolicy¶
Configures the Pod’s spec.imagePullPolicy
.
See the Kubernetes docs for more info.
singleuser.image.pullSecrets¶
A list of references to existing Kubernetes Secrets with credentials to pull the image.
This Pod’s final imagePullSecrets
k8s specification will be a
combination of:
This list of k8s Secrets, specific for this pod.
The list of k8s Secrets, for use by all pods in the Helm chart, declared in this Helm charts configuration called
imagePullSecrets
.A k8s Secret, for use by all pods in the Helm chart, if conditionally created from image registry credentials provided under
imagePullSecret
ifimagePullSecret.create
is set to true.
# example - k8s native syntax
pullSecrets:
- name: my-k8s-secret-with-image-registry-credentials
# example - simplified syntax
pullSecrets:
- my-k8s-secret-with-image-registry-credentials
singleuser.initContainers¶
list of initContainers to be run every singleuser pod. See Kubernetes Docs
singleuser:
initContainers:
- name: init-myservice
image: busybox:1.28
command: ['sh', '-c', 'command1']
- name: init-mydb
image: busybox:1.28
command: ['sh', '-c', 'command2']
singleuser.profileList¶
For more information about the profile list, see KubeSpawner’s documentation as this is simply a passthrough to that configuration.
NOTE: The image-pullers are aware of the overrides of images in
singleuser.profileList
but they won’t be if you configure it in
JupyterHub’s configuration of ‘c.KubeSpawner.profile_list
.
singleuser:
profileList:
- display_name: "Default: Shared, 8 CPU cores"
description: "Your code will run on a shared machine with CPU only."
default: True
- display_name: "Personal, 4 CPU cores & 26GB RAM, 1 NVIDIA Tesla K80 GPU"
description: "Your code will run a personal machine with a GPU."
kubespawner_override:
extra_resource_limits:
nvidia.com/gpu: "1"
singleuser.schedulerStrategy¶
Deprecated and no longer does anything. Use the user-scheduler instead in order to accomplish a good packing of the user pods.
singleuser.extraEnv¶
Extra environment variables that should be set for the user pods.
String literals with $(ENV_VAR_NAME)
will be expanded by Kubelet which
is a part of Kubernetes. Note that the user pods will already have
access to a set of environment variables that you can use, like
JUPYTERHUB_USER
and JUPYTERHUB_HOST
. For more information about these
inspect this source
code.
singleuser:
extraEnv:
# basic notation (for literal values only)
MY_ENV_VARS_NAME1: "my env var value 1"
# explicit notation (the "name" field takes precedence)
USER_NAMESPACE:
name: USER_NAMESPACE
valueFrom:
fieldRef:
fieldPath: metadata.namespace
# implicit notation (the "name" field is implied)
PREFIXED_USER_NAMESPACE:
value: "my-prefix-$(USER_NAMESPACE)"
SECRET_VALUE:
valueFrom:
secretKeyRef:
name: my-k8s-secret
key: password
For more information, see the Kubernetes EnvVar specification.
singleuser.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
singleuser.extraTolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
singleuser.extraNodeAffinity¶
Affinities describe where pods prefer or require to be scheduled, they may prefer or require a node where they are to be scheduled to have a certain label (node affinity). They may also require to be scheduled in proximity or with a lack of proximity to another pod (pod affinity and anti pod affinity).
See the Kubernetes docs for more info.
singleuser.extraNodeAffinity.required¶
Pass this field an array of
NodeSelectorTerm
objects.
singleuser.extraNodeAffinity.preferred¶
Pass this field an array of
PreferredSchedulingTerm
objects.
singleuser.extraPodAffinity¶
See the description of singleuser.extraNodeAffinity
.
singleuser.extraPodAffinity.required¶
Pass this field an array of
PodAffinityTerm
objects.
singleuser.extraPodAffinity.preferred¶
Pass this field an array of
WeightedPodAffinityTerm
objects.
singleuser.extraPodAntiAffinity¶
See the description of singleuser.extraNodeAffinity
.
singleuser.extraPodAntiAffinity.required¶
Pass this field an array of
PodAffinityTerm
objects.
singleuser.extraPodAntiAffinity.preferred¶
Pass this field an array of
WeightedPodAffinityTerm
objects.
scheduling¶
Objects for customizing the scheduling of various pods on the nodes and related labels.
scheduling.userScheduler¶
The user scheduler is making sure that user pods are scheduled tight on nodes, this is useful for autoscaling of user node pools.
scheduling.userScheduler.enabled¶
Enables the user scheduler.
scheduling.userScheduler.replicas¶
You can have multiple schedulers to share the workload or improve availability on node failure.
scheduling.userScheduler.image¶
Set custom image name, tag, pullPolicy, or pullSecrets for the pod.
scheduling.userScheduler.image.name¶
The name of the image, without the tag.
# example name
gcr.io/my-project/my-image
scheduling.userScheduler.image.tag¶
The tag of the image to pull. This is the value following :
in
complete image specifications.
# example tags
v1.11.1
zhy270a
scheduling.userScheduler.image.pullPolicy¶
Configures the Pod’s spec.imagePullPolicy
.
See the Kubernetes docs for more info.
scheduling.userScheduler.image.pullSecrets¶
A list of references to existing Kubernetes Secrets with credentials to pull the image.
This Pod’s final imagePullSecrets
k8s specification will be a
combination of:
This list of k8s Secrets, specific for this pod.
The list of k8s Secrets, for use by all pods in the Helm chart, declared in this Helm charts configuration called
imagePullSecrets
.A k8s Secret, for use by all pods in the Helm chart, if conditionally created from image registry credentials provided under
imagePullSecret
ifimagePullSecret.create
is set to true.
# example - k8s native syntax
pullSecrets:
- name: my-k8s-secret-with-image-registry-credentials
# example - simplified syntax
pullSecrets:
- my-k8s-secret-with-image-registry-credentials
scheduling.userScheduler.pdb¶
Set the Pod Disruption Budget for the user scheduler.
See the Kubernetes documentation for more details about disruptions.
scheduling.userScheduler.pdb.enabled¶
Whether PodDisruptionBudget is enabled for the user scheduler.
scheduling.userScheduler.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
scheduling.userScheduler.tolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
scheduling.podPriority¶
Pod Priority is used to allow real users evict placeholder pods that in turn triggers a scale up by a cluster autoscaler. So, enabling this option will only make sense if the following conditions are met:
Your Kubernetes cluster has at least version 1.11
A cluster autoscaler is installed
user-placeholer pods is configured to get a priority equal or higher than the cluster autoscaler’s priority cutoff
Normal user pods have a higher priority than the user-placeholder pods
Note that if the default priority cutoff if not configured on cluster autoscaler, it will currently default to 0, and that in the future this is meant to be lowered. If your cloud provider is installing the cluster autoscaler for you, they may also configure this specifically.
Recommended settings for a cluster autoscaler…
… with a priority cutoff of -10 (GKE):
podPriority:
enabled: true
globalDefault: false
defaultPriority: 0
userPlaceholderPriority: -10
… with a priority cutoff of 0:
podPriority:
enabled: true
globalDefault: true
defaultPriority: 10
userPlaceholderPriority: 0
scheduling.podPriority.enabled¶
scheduling.podPriority.globalDefault¶
Warning! This will influence all pods in the cluster.
The priority a pod usually get is 0. But this can be overridden with a PriorityClass resource if it is declared to be the global default. This configuration option allows for the creation of such global default.
scheduling.podPriority.defaultPriority¶
The actual value for the default pod priority.
scheduling.podPriority.userPlaceholderPriority¶
The actual value for the user-placeholder pods’ priority.
scheduling.userPlaceholder¶
User placeholders simulate users but will thanks to PodPriority be evicted by the cluster autoscaler if a real user shows up. In this way placeholders allow you to create a headroom for the real users and reduce the risk of a user having to wait for a node to be added. Be sure to use the the continuous image puller as well along with placeholders, so the images are also available when real users arrive.
To test your setup efficiently, you can adjust the amount of user placeholders with the following command:
# Configure to have 3 user placeholders
kubectl scale sts/user-placeholder --replicas=3
scheduling.userPlaceholder.enabled¶
scheduling.userPlaceholder.replicas¶
How many placeholder pods would you like to have?
scheduling.userPlaceholder.resources¶
Unless specified here, the placeholder pods will request the same resources specified for the real singleuser pods.
scheduling.corePods¶
These settings influence the core pods like the hub, proxy and user-scheduler pods.
scheduling.corePods.nodeAffinity¶
Where should pods be scheduled? Perhaps on nodes with a certain label is preferred or even required?
scheduling.corePods.nodeAffinity.matchNodePurpose¶
Decide if core pods ignore, prefer or require to schedule on nodes with this label:
hub.jupyter.org/node-purpose=core
scheduling.userPods¶
These settings influence the user pods like the user-placeholder, user-dummy and actual user pods named like jupyter-someusername.
scheduling.userPods.nodeAffinity¶
Where should pods be scheduled? Perhaps on nodes with a certain label is preferred or even required?
scheduling.userPods.nodeAffinity.matchNodePurpose¶
Decide if user pods ignore, prefer or require to schedule on nodes with this label:
hub.jupyter.org/node-purpose=user
ingress¶
ingress.enabled¶
Enable the creation of a Kubernetes Ingress to proxy-public service.
See Advanced Topics — Zero to JupyterHub with Kubernetes 0.7.0 documentation for more details.
ingress.annotations¶
Annotations to apply to the Ingress.
See the Kubernetes documentation for more details about annotations.
ingress.hosts¶
List of hosts to route requests to the proxy.
ingress.pathSuffix¶
Suffix added to Ingress’s routing path pattern.
Specify *
if your ingress matches path by glob pattern.
ingress.tls¶
TLS configurations for Ingress.
See the Kubernetes documentation for more details about annotations.
prePuller¶
prePuller.annotations¶
Annotations to apply to the hook and continous image puller pods. One example use case is to disable istio sidecars which could interfere with the image pulling.
prePuller.resources¶
These are standard Kubernetes resources with requests and limits for cpu and memory. They will be used on the containers in the pods pulling images. These should be set extremely low as the containers shut down directly or is a pause container that just idles.
They were made configurable as usage of ResourceQuota may require containers in the namespace to have explicit resources set.
prePuller.extraTolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
prePuller.hook¶
See the optimization section for more details.
prePuller.hook.enabled¶
prePuller.hook.podSchedulingWaitDuration¶
The hook-image-awaiter
has a criteria to await all the
hook-image-puller
DaemonSet’s pods to both schedule and finish
their image pulling. This flag can be used to relax this criteria
to instead only await the pods that has already scheduled to
finish image pulling after a certain duration.
The value of this is that sometimes the newly created
hook-image-puller
pods cannot be scheduled because nodes are
full, and then it probably won’t make sense to block a helm upgrade
.
An infinite duration to wait for pods to schedule can be
represented by -1
. This was the default behavior of version
0.9.0 and earlier.
prePuller.hook.nodeSelector¶
An object with key value pairs representing labels. K8s Nodes are required to have match all these labels for this Pod to scheduled on them.
disktype: ssd
nodetype: awesome
See the Kubernetes documentation for more details.
prePuller.hook.tolerations¶
Tolerations allow a pod to be scheduled on nodes with taints. These
are additional tolerations other than the user pods and core pods
default ones hub.jupyter.org/dedicated=user:NoSchedule
or
hub.jupyter.org/dedicated=core:NoSchedule
. Note that a duplicate set
of tolerations exist where /
is replaced with _
as the Google
cloud does not support the character /
yet in the toleration.
Pass this field an array of
Toleration
objects.
See the Kubernetes docs for more info.
prePuller.continuous¶
See the optimization section for more details.
NOTE: If used with a Cluster Autoscaler (an autoscaling node pool), also add user-placeholders and enable pod priority.
prePuller.continuous.enabled¶
prePuller.pullProfileListImages¶
The singleuser.profileList configuration can let the user choose an image through the selection of a profile. This option determines if those images will be pulled, both by the hook and continuous pullers.
The reason to disable this, is that if you have for example 10 images which start pulling in order from 1 to 10, a user that arrives and wants to start a pod with image number 10 will need to wait for all images to be pulled, and then it may be preferable to just let the user arriving wait for a single image to be pulled on arrival.
prePuller.extraImages¶
See the optimization section for more details.
prePuller:
extraImages:
myExtraImageIWantPulled:
name: jupyter/all-spark-notebook
tag: 2343e33dec46
custom¶
Additional values to pass to the Hub.
JupyterHub will not itself look at these,
but you can read values in your own custom config via hub.extraConfig
.
For example:
custom:
myHost: "https://example.horse"
hub:
extraConfig:
myConfig.py: |
c.MyAuthenticator.host = get_config("custom.myHost")