Address changes in docs and deployment scripts

Author: kevin-bates

docs/source/developers/custom-images.md

@@ -164,6 +164,6 @@ cp -r python_kubernetes python_myCustomKernel
 }
 ```
 
-- If using a whitelist (`EG_KERNEL_WHITELIST`), be sure to update it with the new kernel specification directory name (e.g., `python_myCustomKernel`) and restart/redeploy Enterprise Gateway.
+- If using kernel filtering (`EG_ALLOWED_KERNELS`), be sure to update it with the new kernel specification directory name (e.g., `python_myCustomKernel`) and restart/redeploy Enterprise Gateway.
 - Launch or refresh your Notebook session and confirm `My Custom Kernel` appears in the _new kernel_ drop-down.
 - Create a new notebook using `My Custom Kernel`.

docs/source/operators/config-cli.md

@@ -121,6 +121,10 @@ EnterpriseGatewayApp(EnterpriseGatewayConfigMixin, JupyterApp) options
     The full path to a certificate authority certificate for SSL/TLS client
     authentication. (EG_CLIENT_CA env var)
     Default: None
+--EnterpriseGatewayApp.client_envs=<list-item-1>...
+    Environment variables allowed to be set when a client requests a
+    new kernel. (EG_CLIENT_ENVS env var)
+    Default: []
 --EnterpriseGatewayApp.conductor_endpoint=<Unicode>
     The http url for accessing the Conductor REST API. (EG_CONDUCTOR_ENDPOINT
     env var)
@@ -140,13 +144,10 @@ EnterpriseGatewayApp(EnterpriseGatewayConfigMixin, JupyterApp) options
     (EG_DYNAMIC_CONFIG_INTERVAL env var)
     Default: 0
 --EnterpriseGatewayApp.env_process_whitelist=<list-item-1>...
-    Environment variables allowed to be inherited from the spawning process by
-    the kernel. (EG_ENV_PROCESS_WHITELIST env var)
+    DEPRECATED, use inherited_envs
     Default: []
 --EnterpriseGatewayApp.env_whitelist=<list-item-1>...
-    Environment variables allowed to be set when a client requests a new kernel.
-    Use '*' to allow all environment variables sent in the request.
-    (EG_ENV_WHITELIST env var)
+    DEPRECATED, use client_envs.
     Default: []
 --EnterpriseGatewayApp.expose_headers=<Unicode>
     Sets the Access-Control-Expose-Headers header. (EG_EXPOSE_HEADERS env var)
@@ -158,6 +159,10 @@ EnterpriseGatewayApp(EnterpriseGatewayConfigMixin, JupyterApp) options
     Indicates whether impersonation will be performed during kernel launch.
     (EG_IMPERSONATION_ENABLED env var)
     Default: False
+--EnterpriseGatewayApp.inherited_envs=<list-item-1>...
+    Environment variables allowed to be inherited
+    from the spawning process by the kernel. (EG_INHERITED_ENVS env var)
+    Default: []
 --EnterpriseGatewayApp.ip=<Unicode>
     IP address on which to listen (EG_IP env var)
     Default: '127.0.0.1'

docs/source/operators/config-kernel-override.md

@@ -38,8 +38,10 @@ those same-named variables in the kernel.json `env` stanza.
 
 Environment variables for which this can occur are any variables prefixed with `KERNEL_`
 as well as any variables
-listed in the `EnterpriseGatewayApp.env_whitelist` configurable trait (or via
-the `EG_ENV_WHITELIST` variable). Locally defined variables listed in `EG_PROCESS_ENV_WHITELIST`
+listed in the `EnterpriseGatewayApp.client_envs` configurable trait (or via
+the `EG_CLIENT_ENVS` variable). Likewise, environment variables of the Enterprise Gateway
+server process listed in the `EnterpriseGatewayApp.inherited_envs` configurable trait
+(or via the  `EG_INHERITED_ENVS` variable)
 are also available for replacement in the kernel process' environment.
 
 See [Kernel Environment Variables](../users/kernel-envs.md) in the Users documentation section for a complete set of recognized `KERNEL_` variables.

enterprise_gateway/enterprisegatewayapp.py

@@ -236,8 +236,8 @@ def init_webapp(self) -> None:
             eg_expose_headers=self.expose_headers,
             eg_max_age=self.max_age,
             eg_max_kernels=self.max_kernels,
-            eg_env_process_whitelist=self.env_process_whitelist,
-            eg_env_whitelist=self.env_whitelist,
+            eg_inherited_envs=self.inherited_envs,
+            eg_client_envs=self.client_envs,
             eg_kernel_headers=self.kernel_headers,
             eg_list_kernels=self.list_kernels,
             eg_authorized_users=self.authorized_users,

enterprise_gateway/mixins.py

@@ -374,13 +374,9 @@ def list_kernels_default(self) -> bool:
 
     env_whitelist = ListTrait(
         config=True,
-        help="""DEPRECATED, use allowed_envs.""",
+        help="""DEPRECATED, use client_envs.""",
     )
 
-    @default("env_whitelist")
-    def env_whitelist_default(self) -> List[str]:
-        return os.getenv(self.env_whitelist_env, os.getenv("KG_ENV_WHITELIST", "")).split(",")
-
     @observe("env_whitelist")
     def _update_env_whitelist(self, change):
         self.log.warning("env_whitelist is deprecated, use client_envs")

enterprise_gateway/services/api/swagger.json

@@ -160,7 +160,7 @@
                 },
                 "env": {
                   "type": "object",
-                  "description": "A dictionary of environment variables and values to include in the kernel process - subject to whitelisting.",
+                  "description": "A dictionary of environment variables and values to include in the kernel process - subject to filtering.",
                   "additionalProperties": {
                     "type": "string"
                   }

enterprise_gateway/services/api/swagger.yaml

@@ -141,7 +141,7 @@ paths:
                 type: object
                 description: |
                   A dictionary of environment variables and values to include in the
-                  kernel process - subject to whitelisting.
+                  kernel process - subject to filtering.
                 additionalProperties:
                   type: string
       responses:

enterprise_gateway/services/kernels/handlers.py

@@ -22,12 +22,12 @@ class MainKernelHandler(
     """
 
     @property
-    def env_whitelist(self):
-        return self.settings["eg_env_whitelist"]
+    def client_envs(self):
+        return self.settings["eg_client_envs"]
 
     @property
-    def env_process_whitelist(self):
-        return self.settings["eg_env_process_whitelist"]
+    def inherited_envs(self):
+        return self.settings["eg_inherited_envs"]
 
     async def post(self):
         """Overrides the super class method to manage env in the request body.
@@ -59,19 +59,15 @@ async def post(self):
                 {
                     key: value
                     for key, value in os.environ.items()
-                    if key in self.env_process_whitelist
+                    if key in self.inherited_envs
                 }
             )
-            # Whitelist KERNEL_* args and those allowed by configuration from client.  If all
-            # envs are requested, just use the keys from the payload.
-            env_whitelist = self.env_whitelist
-            if env_whitelist == ["*"]:
-                env_whitelist = model["env"].keys()
+            # Allow KERNEL_* args and those allowed by configuration.
             env.update(
                 {
                     key: value
                     for key, value in model["env"].items()
-                    if key.startswith("KERNEL_") or key in env_whitelist
+                    if key.startswith("KERNEL_") or key in self.client_envs
                 }
             )
 

enterprise_gateway/services/kernels/remotemanager.py

@@ -427,8 +427,8 @@ def _link_dependent_props(self):
             "port_range",
             "impersonation_enabled",
             "max_kernels_per_user",
-            "env_whitelist",
-            "env_process_whitelist",
+            "client_envs",
+            "inherited_envs",
             "yarn_endpoint",
             "alt_yarn_endpoint",
             "yarn_endpoint_security_enabled",
@@ -470,8 +470,8 @@ def _capture_user_overrides(self, **kwargs):
                 key: value
                 for key, value in env.items()
                 if key.startswith("KERNEL_")
-                or key in self.env_process_whitelist
-                or key in self.env_whitelist
+                or key in self.inherited_envs
+                or key in self.client_envs
             }
         )
 

enterprise_gateway/services/processproxies/k8s.py

@@ -53,7 +53,7 @@ async def launch_process(
         # transfer its env to each launched kernel.
         kwargs["env"] = dict(
             os.environ, **kwargs["env"]
-        )  # FIXME: Should probably use process-whitelist in JKG #280
+        )
         self.kernel_pod_name = self._determine_kernel_pod_name(**kwargs)
         self.kernel_namespace = self._determine_kernel_namespace(
             **kwargs

enterprise_gateway/tests/test_handlers.py

@@ -24,11 +24,12 @@ def setup_app(self):
         os.environ["JUPYTER_PATH"] = RESOURCES
 
         # These are required for setup of test_kernel_defaults
+        # Note: We still reference the DEPRECATED config parameter and environment variable so that
+        # we can test client_envs and inherited_envs, respectively.
+        self.app.env_whitelist = ['TEST_VAR', 'OTHER_VAR1', 'OTHER_VAR2']
         os.environ["EG_ENV_PROCESS_WHITELIST"] = "PROCESS_VAR1,PROCESS_VAR2"
         os.environ["PROCESS_VAR1"] = "process_var1_override"
 
-        self.app.env_whitelist = ["TEST_VAR", "OTHER_VAR1", "OTHER_VAR2"]
-
     def tearDown(self):
         """Shuts down the app after test run."""
 

etc/docker/docker-compose.yml

@@ -22,7 +22,8 @@ services:
       - "EG_DOCKER_NETWORK=${EG_DOCKER_NETWORK:-enterprise-gateway_enterprise-gateway}"
       - "EG_KERNEL_LAUNCH_TIMEOUT=${EG_KERNEL_LAUNCH_TIMEOUT:-60}"
       - "EG_CULL_IDLE_TIMEOUT=${EG_CULL_IDLE_TIMEOUT:-3600}"
-      - "EG_KERNEL_WHITELIST=${EG_KERNEL_WHITELIST:-'r_docker','python_docker','python_tf_docker','python_tf_gpu_docker','scala_docker'}"
+      # Use double-defaulting for B/C.  Support for EG_KERNEL_WHITELIST will be removed in a future release
+      - "EG_ALLOWED_KERNELS=${EG_ALLOWED_KERNELS:-${EG_KERNEL_WHITELIST:-'r_docker','python_docker','python_tf_docker','python_tf_gpu_docker','scala_docker'}}"
       - "EG_MIRROR_WORKING_DIRS=${EG_MIRROR_WORKING_DIRS:-False}"
       - "EG_RESPONSE_PORT=${EG_RESPONSE_PORT:-8877}"
       - "KG_PORT=${KG_PORT:-8888}"

etc/docker/enterprise-gateway/start-enterprise-gateway.sh

@@ -26,19 +26,19 @@ export EG_LOG_LEVEL=${EG_LOG_LEVEL:-DEBUG}
 export EG_CULL_IDLE_TIMEOUT=${EG_CULL_IDLE_TIMEOUT:-43200}  # default to 12 hours
 export EG_CULL_INTERVAL=${EG_CULL_INTERVAL:-60}
 export EG_CULL_CONNECTED=${EG_CULL_CONNECTED:-False}
-EG_KERNEL_WHITELIST=${EG_KERNEL_WHITELIST:-"null"}
-export EG_KERNEL_WHITELIST=`echo ${EG_KERNEL_WHITELIST} | sed 's/[][]//g'` # sed is used to strip off surrounding brackets as they should no longer be included.
+EG_ALLOWED_KERNELS=${EG_ALLOWED_KERNELS:-${EG_KERNEL_WHITELIST:-"null"}}
+export EG_ALLOWED_KERNELS=`echo ${EG_ALLOWED_KERNELS} | sed 's/[][]//g'` # sed is used to strip off surrounding brackets as they should no longer be included.
 export EG_DEFAULT_KERNEL_NAME=${EG_DEFAULT_KERNEL_NAME:-python_docker}
 
 # Determine whether the kernels-allowed list should be added to the start command.
 # This is conveyed via a 'null' value for the env - which indicates no kernel names
 # were used in the helm chart or docker-compose yaml.
 allowed_kernels_option=""
-if [ "${EG_KERNEL_WHITELIST}" != "null" ]; then
-	allowed_kernels_option="--KernelSpecManager.whitelist=[${EG_KERNEL_WHITELIST}]"
+if [ "${EG_ALLOWED_KERNELS}" != "null" ]; then
+  # Update to --KernelSpecManager.allowed_kernelspecs once jupyter_client >= 7 can be supported
+	allowed_kernels_option="--KernelSpecManager.whitelist=[${EG_ALLOWED_KERNELS}]"
 fi
 
-
 echo "Starting Jupyter Enterprise Gateway..."
 
 exec jupyter enterprisegateway \

etc/kernel-launchers/docker/scripts/launch_docker.py

@@ -42,7 +42,7 @@ def launch_docker_kernel(kernel_id, port_range, response_addr, public_key, spark
     param_env["RESPONSE_ADDRESS"] = response_addr
     param_env["KERNEL_SPARK_CONTEXT_INIT_MODE"] = spark_context_init_mode
 
-    # Since the environment is specific to the kernel (per env stanza of kernelspec, KERNEL_ and ENV_WHITELIST)
+    # Since the environment is specific to the kernel (per env stanza of kernelspec, KERNEL_ and EG_CLIENT_ENVS)
     # just add the env here.
     param_env.update(os.environ)
     param_env.pop(

etc/kubernetes/helm/enterprise-gateway/templates/deployment.yaml

@@ -69,8 +69,8 @@ spec:
           value: {{ .Values.logLevel }}
         - name: EG_KERNEL_LAUNCH_TIMEOUT
           value: !!str {{ .Values.kernel.launchTimeout }}
-        - name: EG_KERNEL_WHITELIST
-          value: {{ toJson .Values.kernel.whitelist | squote }}
+        - name: EG_ALLOWED_KERNELS
+          value: {{ toJson .Values.kernel.allowedKernels | squote }}
         - name: EG_DEFAULT_KERNEL_NAME
           value: {{ .Values.kernel.defaultKernelName }}
         # Optional authorization token passed in all requests

etc/kubernetes/helm/enterprise-gateway/values.yaml

@@ -78,8 +78,8 @@ kernel:
   cullIdleTimeout: 3600
   # List of kernel names that are available for use. To allow additional kernelspecs without
   # requiring redeployment (and assuming kernelspecs are mounted or otherwise accessible
-  # outside the pod), comment out (or remove) the entries, leaving only `whitelist:`.
-  whitelist:
+  # outside the pod), comment out (or remove) the entries, leaving only `allowedKernels:`.
+  allowedKernels:
     - r_kubernetes
     - python_kubernetes
     - python_tf_kubernetes