Jupyter notebook environment variables

For built-in Jupyter notebooks, these environment variables are supported.

Precedence of environment variable values

Depending on your role and permissions, you can define notebook environment variables in the various ways:
  1. A notebook user can define environment variables for their own notebooks. An administrator can also do this by configuring the notebook for the user.
  2. An administrator can define environment variables when enabling notebooks for an instance group.
  3. A cluster administrator can define environment variables when defining a notebook package.
In the case that a notebook environment variable name is already defined elsewhere, the system uses the value in the order listed here, and makes that the default value for the others. For example if the administrator creates an instance group with a notebook and sets environment variable ABC, and then the notebook user also sets environment variable ABC, the notebook user's values will be used.
Table 1. Environment variables for Jupyter notebooks
Environment variables Description Default value
JEG_LOG_LEVEL Specifies the log level for the Jupyter Enterprise Gateway server (string).

Valid values are: 0, 10, 20, 30, 40, 50, DEBUG, INFO, WARN, ERROR, or CRITICAL.

Default: INFO

 INFO
JUPYTER_CULL_BUSY Specifies whether to kill a kernel when it is busy. Specify True to kill the kernel.

Valid values are True or False.

 False
JUPYTER_CULL_CONNECTED Specifies whether kill a kernel if a connection to the kernel exists. Specify True to kill the kernel.

Valid values are True or False.

 False
JUPYTER_CULL_IDLE_TIMEOUT Specifies the amount of time to wait in order to kill a kernel.

Valid value is a positive integer, specified in seconds. The minimum allowed value is 1.

To disable culling, set this environment variable to 0.

 3600
JUPYTER_CULL_INTERVAL Specifies the time interval to query the JUPYTER_CULL_IDLE_TIMEOUT environment variable value.

Valid value is a positive integer, specified in seconds.

 600
JUPYTER_IP_BLACKLIST A comma-separated list of local IPv4 addresses (or regular expressions) that are not to be used when determining the response address that is used to convey connection information back to the Jupyter Enterprise Gateway from a remote kernel. In some cases, other network interfaces (for example Docker with 172.17.0.*) can interfere, which leads to connection failures during kernel startup.

Valid values are: Single IPv4 address or a comma-separated list of IPv4 addresses. Both entries can contain a wildcard character.

Example: 172.17.0.*,192.168.0.27, which eliminates the use of all addresses that start with 172.17.0, as well as the single IPv4 address 192.168.0.27.

 No default value
JUPYTER_KERNEL_START_TIMEOUT Specifies the amount of time until the kernel times out.

Valid value is a positive integer, specified in seconds.

 300
JUPYTER_REQUEST_TIMEOUT Specifies the amount of time to wait until kernel error.

Valid value is a positive integer, specified in seconds.

 400
JUPYTER_SPARK_OPTS Specifies additional Spark parameters (such as priority) to be used in either the Spark submit command if you enable a notebook for a instance group, or in the kernel startup if you configure a notebook package.

Example: JUPYTER_SPARK_OPTS = "--conf spark.ego.priority=3000", which specifies that after starting the kernel, the notebook application has priory of 3000 instead of the default 5000.

 No default value
JUPYTER_USER_SPARK_OPTS Specifies additional notebook user parameters (such as your principal and the location of your keytab file for your notebook. The system can then use this information when starting the Kerberos authenticated notebook using a service-level impersonation user).

Notebook users can add this environment variable to the notebooks that they own, and the notebook user's value takes precedence if the same environment variable name is defined elsewhere.

This environment variable uses the same format as the JUPYTER_SPARK_OPTS parameter. For example: 
JUPYTER_USER_SPARK_OPTS = "--conf spark.yarn.principal=user@realm --conf spark.yarn.keytab=/path_to_user.keytab"
such as, 
"--conf spark.yarn.principal=jsmith@example.com --conf spark.yarn.keytab=/home/mykeytabdirectory/jsmith.keytab"
This example specifies that the system can start the Kerberos authenticated notebook using a service-level impersonation user.
 No default value
JUPYTERLAB_ENABLED Toggles to use the JupyterLab web based interface instead of the default Jupyter notebook interface.

Valid values are true or false.

 false
NOTEBOOK_EXTRA_CONF_FILE The path to an extra configuration file that runs a notebook at start time. The path can define extra customization to the environment in which the notebook starts.
Tip: If you want to customize environment variables with the script defined in the path of the NOTEBOOK_EXTRA_CONF_FILE, consider the environment variables that might already have values as part of the process environment in which the service runs. You might want to append the existing environment variables where applicable, rather than completely overwrite them. For example, if your instance group contains data connectors, the notebook service automatically have a value for the JUPYTER_SPARK_OPTS environment variable that contains configuration for the data connectors.
To see the current environment variable list for your notebook services:
  1. Open the cluster management console in a web browser. For details, see Locating the cluster management console topic.
  2. Select Workload > Instance Groups.
  3. Under the Name column, click an instance group.
  4. Select the Notebooks tab of the instance group.
  5. Select a notebook and click View Service Details.
  6. Select the Service Profile tab.
  7. Under the ego:ActivitySpecification section, for the list of service environment variables see the ego:EnvironmentVariable entries.
 No default value
Tip: Additionally, you can tune kernel culling for Jupyter notebooks using Jupyter kernel culling environment variables.