hub.extraEnv / singleuser.extraEnv in dict format to support k8s EnvVar spec

[consideRatio]

Background

In short, specifying an environment variable for the JupyterHub pod or the user pods could only be done in a limited fashion that excluded specifying an environment variable that got its value from some Kubernetes ConfigMap/Secret or similar. This has only been only possible with intrusive workarounds. This PR closes #1103 and an associated KubeSpawner PR has already closed jupyterhub/kubespawner#306 (comment).

hub.extraEnv advanced syntax support

This PR enables hub.extraEnv to function with a format either exactly like Kubernetes EnvVar specification or a shorthand where a name: ... is implied. This format is now also documented in the configuration reference (docs preview).

singleuser.extraEnv advanced syntax support

This PR doesn't fully close #1103 because this only enables the new syntax support for hub.extraEnv but not also for singleuser.extraEnv. jupyterhub/kubespawner#426 is now merged which takes care of the singleuser.extraEnv part.

Technical breakdown regarding singleuser.extraEnv

The Helm chart configuration singleuser.extraEnv propegates without issues to c.KubeSpawner.environment which is defined in the Spawner base class, so it turned out that no changes were needed in this repo. Below are still some of the notes I made along the way to ensure that was the case and to develop the PR (jupyterhub/kubespawner#426) in KubeSpawner that fixed it over there.

1. Either directly configuring c.KubeSpawner.environment or doing it through singleuser.extraEnv should be fine even if we use the new syntax.
2. KubeSpawner references the environment traitlet from the end of the jupyterhub.Spawner.get_env function.
3. The get_env function is then called to provide the env argument to the make_pod function.
4. The make_pod function use the the passed env vars once, that assuming support for new syntax should be able to get a dummyKey1 with a value of {name: "MY_ENV", value: "my-value"} passed to it.
5. The V1EnvVar constructor allows for name/value/value_from, but is only used to pass a name/value combination rather than the possible name/valueFrom combination.
6. The issue found in the point above is fixed in Support EnvVar's with 'valueFrom' as well as with 'value' kubespawner#426
7. Documentation is also added in this PR to use singleuser.extraEnv with this new syntax.

Relevant references for this tech breakdown are the k8s api specs and the Python API for Kubernetes.

Discussion

• @minrk considered the implementation options in A secrets friendly version of extraEnv #1103 (comment).
• @manics suggested the implicit syntax where name: ... is implied. This is now supported.

Todo

• Get KubeSpawner 0.13.0 releaased (Changelog for the 0.13.0 release kubespawner#429)
• Bump the KubeSpawner version in the hub image we build in this Helm chart (https://travis-ci.org/github/jupyterhub/zero-to-jupyterhub-k8s/builds/724045064)

Related

• Closing Added doc example of mounting k8s secrets as ENV variables to user pods without values.yaml #1462 in favor of this as the added documentation regards the no longer needed workaround.

[manics]

Thanks, I think this is a good compromise!

I made some minor formatting suggestions based on https://zero-to-jupyterhub--1757.org.readthedocs.build/en/1757/reference/reference.html

[consideRatio]

Thanks @manics!

[consideRatio]

I consider this PR now ready for merge. @yuvipanda since you just looked at the KubeSpawner equivalent PR, perhaps you could have a look at this as well? Thank you @manics and @yuvipanda for the attention! ❤️

[yuvipanda]

Thanks a lot for working on this, @consideRatio!