# Kernel Environment Variables

When the gateway provisioners are local to the Jupyter (notebook) Server, all environment variables
from the server process are made available to the launched kernel. In addition, when Jupyter Server
is configured to use a Gateway Server, the built-in gateway client software will also include _any_
environment variables prefixed with `KERNEL_` in the start kernel request sent to the Gateway Server.
This enables the ability to _statically parameterize_ aspects of kernel start requests relative to other
clients using the same Gateway Server instance.

There are several supported `KERNEL_` variables that the gateway provisioners look for and use, although
others can be sent to customize behaviors. The following kernel-specific environment variables are recognized
and used by the appropriate gateway provisioners. As mentioned above, all `KERNEL_` variables submitted
in the kernel startup request's JSON body will be available to the kernel for its launch.

```text
  KERNEL_GID=<from user> or 100
    Container-based provisioners only. This value represents the group id in which the container
    will run. The default value is 100 representing the users group - which is the default group ID
    when building images from within the Gateway Provisioners project.  See also KERNEL_UID.
    Kubernetes: Warning - If KERNEL_GID is set it is strongly recommended that feature-gate
    RunAsGroup be enabled, otherwise, this value will be ignored and the pod will run as
    the root group id.  As a result, the setting of this value into the Security Context
    of the kernel pod is commented out in the kernel-pod.yaml file and must be enabled
    by the administrator.
    Docker: Warning - This value is only added to the supplemental group ids.  As a result,
    if used with KERNEL_UID, the resulting container will run as the root group with this
    value listed in its supplemental groups.

  KERNEL_EXECUTOR_IMAGE=<from kernel.json kernel-provisioner stanza> or KERNEL_IMAGE
    Kubernetees w/ Spark provisioners only. This indicates the image that Spark-based Kubernetes
    deployments will use for its executors.  Although this value could come from the user, its strongly
    recommended that the kernel-provisioner stanza of the corresponding kernel's kernelspec
    (kernel.json) file be updated to include the image name.  If no image name is
    provided, the value of KERNEL_IMAGE will be used.

  KERNEL_EXTRA_SPARK_OPTS=<from user>
    Spark-based provisioners only. This variable allows users to add additional spark options
    to the current set of options specified in the corresponding kernel.json file.  This
    variable is purely optional with no default value.  In addition, it is the responsibility
    of the user setting this value to ensure the options passed are appropriate relative to
    the target environment.  Because this variable contains space-separate values, it requires
    appropriate quotation.  For example, to use with the notebook docker image
    jupyterhub/k8s-singleuser-sample, the environment variable would look something like this:

    docker run ... -e KERNEL_EXTRA_SPARK_OPTS=\"--conf spark.driver.memory=2g
    --conf spark.executor.memory=2g\" ... jupyterhub/k8s-singleuser-sample

  KERNEL_ID=<from user> or <system generated>
    This value represents the identifier used by the Jupyter framework to identify
    the kernel.  Although this value could be provided by the user, it is recommended
    that it be generated by the system.

  KERNEL_IMAGE=<from user> or <from kernel.json kernel-provisioner stanza>
    Container-based provisioners only. This indicates the image to use for the kernel in
    containerized environments - Kubernetes or Docker.  Although it can be provided by the
    user, it is strongly recommended that the kernel-provisioner stanza of the corresponding
    kernel's kernelspec (kernel.json) file be updated to include the image name.

  KERNEL_LAUNCH_TIMEOUT=<from user> or GP_KERNEL_LAUNCH_TIMEOUT
    Indicates the time (in seconds) to allow for a kernel's launch.  This value should
    be submitted in the kernel startup if that particular kernel's startup time is
    expected to exceed that of the GP_KERNEL_LAUNCH_TIMEOUT set when Gateway Provisioner's
    hosting application starts.

  KERNEL_NAMESPACE=<from user> or KERNEL_POD_NAME or GP_NAMESPACE
    Kubernetes provisioners only.  This indicates the name of the namespace to use or
    create on Kubernetes in which the kernel pod will be located.  For users wishing to
    use a pre-created namespace, this value should be submitted in the env stanza of
    the kernel startup request.  In such cases, the user must also provide KERNEL_SERVICE_ACCOUNT_NAME.
    If not provided, and GP_SHARED_NAMESPACE is False, Gateway Provisioners will attempt to
    create a new namespace for the kernel whose value is derived from KERNEL_POD_NAME.  When
    GP_SHARED_NAMESPACE is True (the default value in Gateway Provisioners), this value will
    be set to the value of GP_NAMESPACE.

    Note that if the namespace is created by Gateway Provisioners, it will be removed
    upon the kernel's termination.  Otherwise, the Gateway Provisioners will not
    remove the namespace.

  KERNEL_POD_NAME=<from user> or KERNEL_USERNAME-KERNEL_ID
    Kubernetes provisioners only. By default, Gateway Provisioners will use a kernel
    pod name whose value is derived from KERNEL_USERNAME and KERNEL_ID separated by
    a hyphen ('-').  This variable is typically NOT provided by the user, but, in
    such cases, Gateway Provisioners will honor that value.  However, when provided,
    it is the user's responsibility that KERNEL_POD_NAME is unique relative to
    any pods in the target namespace.  In addition, the pod must NOT exist -
    unlike the case if KERNEL_NAMESPACE is provided.

  KERNEL_REMOTE_HOST=<remote host name>
    Distributed provisioner only.  When specified, this value will override the
    configured load-balancing algorithm.

  KERNEL_SERVICE_ACCOUNT_NAME=<from user> or GP_DEFAULT_KERNEL_SERVICE_ACCOUNT_NAME
    Kubernetes provisioners only.  This value represents the name of the service account
    that Gateway Provisioners should equate with the kernel pod.  If Gateway Provisioners
    creates the kernel's namespace, it will be associated with the cluster role
    identified by GP_KERNEL_CLUSTER_ROLE.  If not provided, it will be derived
    from GP_DEFAULT_KERNEL_SERVICE_ACCOUNT_NAME.

  KERNEL_SPARKAPP_CONFIG_MAP=<from user> or None
    SparkOperator provisioner only. The name of a Kubernetes ConfigMap which will be used to
    configure the SparkApplication. This value is used to set the `sparkConfigMap` property
    in the spark operator's yaml template during launch.

  KERNEL_UID=<from user> or 1000
    Container-based provisioners only. This value represents the user id in which the container
    will run. The default value is 1000 representing the jovyan user - which is the default user ID
    when building images from within the Gateway Provisioners project.  See also KERNEL_GID.
    Kubernetes: Warning - If KERNEL_UID is set it is strongly recommended that feature-gate
    RunAsGroup be enabled and KERNEL_GID also be set, otherwise, the pod will run as
    the root group id. As a result, the setting of this value into the Security Context
    of the kernel pod is commented out in the kernel-pod.yaml file and must be enabled
    by the administrator.

  KERNEL_USERNAME=<from user> or <gateway-provisioner-hosting-application-user>
    This value represents the logical name of the user submitting the request to
    start the kernel. Of all the KERNEL_ variables, KERNEL_USERNAME is the one that
    should be submitted in the request. In environments in which impersonation is
    used it represents the target of the impersonation.

  KERNEL_WORKING_DIR=<from user> or None
    Container-based provisioners only.  This value should model the directory in which the
    active notebook file is running.   It is intended to be used in conjunction with
    appropriate volume mounts in the kernel container such that the user's notebook
    filesystem exists in the container and enables the sharing of resources used within
    the notebook. As a result, the primary use case for this is for Jupyter Hub users running
    in Kubernetes.  When a value is provided and GP_MIRROR_WORKING_DIRS=True, Gateway
    Provisioners will set the container's working directory to the value specified in
    KERNEL_WORKING_DIR.  If GP_MIRROR_WORKING_DIRS is False, KERNEL_WORKING_DIR will
    not be available for use during the kernel's launch.  See also GP_MIRROR_WORKING_DIRS.
```