Merge pull request #2820 from minrk/null-opt-in

Restore jupyterhub-singleuser as the default command

Author: manics

docs/source/administrator/upgrading/upgrade-1-to-2.md

@@ -81,19 +81,6 @@ singleuser:
   allowPrivilegeEscalation: true
 ```
 
-## Default to using the container image's command instead of `jupyterhub-singleuser` [#2449](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2449)
-
-Z2JH now launches the container's default command (equivalent to setting `CMD` in a `Dockerfile`) instead of overriding it.
-This ensures that containers that use a custom start command to configure their environment, such as some
-[Jupyter Docker Stacks](https://jupyter-docker-stacks.readthedocs.io/en/latest/)
-images, will work without any changes.
-To restore the old behaviour set:
-
-```yaml
-singleuser:
-  cmd: jupyterhub-singleuser
-```
-
 ## Configuration in `jupyterhub_config.d` has a higher priority than `hub.config` [#2457](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/pull/2457)
 
 Previously if `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.

docs/source/jupyterhub/customizing/user-environment.md

@@ -44,6 +44,9 @@ image containing useful tools and libraries for data science, complete these ste
        # https://github.com/jupyter/docker-stacks/tree/HEAD/datascience-notebook/Dockerfile
        name: jupyter/datascience-notebook
        tag: latest
+       # `cmd: null` allows the custom CMD of the Jupyter docker-stacks to be used
+       # which performs further customization on startup.
+       cmd: null
    ```
 
    ```{note}
@@ -244,10 +247,9 @@ FROM jupyter/minimal-notebook:latest
 RUN pip install --no-cache-dir astropy
 
 # set the default command of the image,
-# if the parent image will not launch a jupyterhub singleuser server.
-# The JupyterHub "Docker stacks" do not need to be overridden.
-# Set either here or in `singleuser.cmd` in your values.yaml
-# CMD ["jupyterhub-singleuser"]
+# if you want to launch more complex startup than the default `juptyerhub-singleuser`.
+# To launch an image's custom CMD instead of the default `jupyterhub-singleuser`
+# set `singleuser.cmd: null` in your config.yaml.
 ```
 
 ```{note}
@@ -529,25 +531,33 @@ this is best done in the ENTRYPOINT of the image,
 and not in the CMD, so that overriding the command does not skip your preparation.
 ```
 
-By default, zero-to-jupyterhub will launch the default CMD that is specified in your chosen image,
-respecting any startup customization that image may have.
-If the image doesn't launch `jupyterhub-singleuser` by default,
-you will additionally need to specify `singleuser.cmd`
-in your `values.yaml` as the command to launch,
-so that it ultimately launches `jupyterhub-singleuser`.
-The simplest version:
+By default, zero-to-jupyterhub will launch the command `jupyterhub-singleuser`.
+If you have an image (such as `jupyter/scipy-notebook` and other Jupyter Docker stacks)
+that defines a CMD with startup customization and ultimately launches `jupyterhub-singleuser`,
+you can chose to launch the image's default CMD instead by setting:
 
 ```yaml
 singleuser:
-  cmd: jupyterhub-singleuser
+  cmd: null
 ```
 
-```{versionchanged} 2.0
-Prior to 2.0, the default behavior of zero-to-jupyterhub was to launch `jupyterhub-singleuser` explicitly,
-ignoring what was in the image.
-The default command is now whatever the image runs by default.
+Alternately, you can specify an explicit custom command as a string or list of strings:
+
+```yaml
+singleuser:
+  cmd:
+    - /usr/local/bin/custom-command
+    - "--flag"
+    - "--other-flag"
 ```
 
+:::{note}
+Docker has `ENTRYPOINT` and `CMD`,
+which k8s calls `command` and `args`.
+zero-to-jupyterhub always respects the ENTRYPOINT of the image,
+and setting `singleuser.cmd` only overrides the CMD.
+:::
+
 ## Disable specific JupyterLab extensions
 
 Sometimes you want to temporarily disable a JupyterLab extension on a JupyterHub

jupyterhub/files/hub/jupyterhub_config.py

@@ -408,8 +408,13 @@ def camelCaseify(s):
 
     c.JupyterHub.load_roles.append(role)
 
+# respect explicit null command (distinct from unspecified)
+# this avoids relying on KubeSpawner.cmd's default being None
+_unspecified = object()
+specified_cmd = get_config("singleuser.cmd", _unspecified)
+if specified_cmd is not _unspecified:
+    c.Spawner.cmd = specified_cmd
 
-set_config_if_not_none(c.Spawner, "cmd", "singleuser.cmd")
 set_config_if_not_none(c.Spawner, "default_url", "singleuser.defaultUrl")
 
 cloud_metadata = get_config("singleuser.cloudMetadata", {})

jupyterhub/schema.yaml

@@ -1019,7 +1019,7 @@ properties:
           extraPorts:
             type: array
             description: |
-              Extra ports to add to the Hub Service object besides `hub` / `8081`.  
+              Extra ports to add to the Hub Service object besides `hub` / `8081`.
               This should be an array that includes `name`, `port`, and `targetPort`.
               See [Multi-port Services](https://kubernetes.io/docs/concepts/services-networking/service/#multi-port-services) for more details.
           loadBalancerIP:
@@ -2124,6 +2124,10 @@ properties:
         description: |
           Passthrough configuration for
           [KubeSpawner.cmd](https://jupyterhub-kubespawner.readthedocs.io/en/latest/spawner.html#kubespawner.KubeSpawner.cmd).
+          The default is "jupyterhub-singleuser".
+          Use `cmd: null` to launch a custom CMD from the image,
+          which must launch jupyterhub-singleuser or an equivalent process eventually.
+          For example: Jupyter's docker-stacks images.
       defaultUrl:
         type: [string, "null"]
         description: |
@@ -2636,7 +2640,7 @@ properties:
         description: |
           The path type to use. The default value is 'Prefix'.
 
-          See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types) 
+          See [the Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#path-types)
           for more details about path types.
       tls:
         type: array

jupyterhub/values.yaml

@@ -394,7 +394,7 @@ singleuser:
   extraResource:
     limits: {}
     guarantees: {}
-  cmd:
+  cmd: jupyterhub-singleuser
   defaultUrl:
   extraPodConfig: {}
   profileList: []