Improved documentation for commonly used functionality, with example for `existingSecret`

[qTipTip]

Proposed change

This issue directly references this post on how to use the existing secret functionality of JupyterHub. Some of the "hidden" features of JupyterHub can be hard to get a grasp of for developers new to the stack (me included).

Some of the features in particular can greatly benefit from some step-by-step examples.

Who would use this feature?

All developers looking for points of reference when deploying the Z2JH-stack or when figuring out whether Z2JH is the right tool for the job.

(Optional): Suggest a solution

I documented a step-by-step solution for the hub.existingSecret functionality here, but will by request copy-paste it here for ease of reference. I think similar walkthroughs can be beneficial for other features as well, and hopefully this example can serve as a "guideline" of sorts.

One year anniversary update.

Thanks for all the replies, and sorry for my lack of engagement. I have revisited the issue, and after some hacking around I finally managed to get it to work.

In the following I will outline how to set up authentication (AAD in this case) in a VCS-friendly way (using existingSecret). This has also been updated to the new version of Z2JH (using helm chart version 1.1.0 at the time of writing).

Restating the problem

When setting up authentication we need to specify the following in the values.yaml-file:

# in values.yaml
hub:
  config:
     AzureAdOAuthenticator:
       client_id: <my secret client_id>
       client_secret: <my secret client secret>
       tenant_id: <my tenant id>
       oauth_callback_url: <callback url>
    JupyterHub:
       authenticator_class: azuread

Some of these values are things you do not want to commit to VCS’ like GitHub.

The Solution

To solve this problem, we can use the existingSecret keyword in values.yaml and let Jupyter Hub pull configuration settings from an already existing K8s secret. To me the documentation is still lacking in providing a clear example on how to do this, especially on how exactly the secret should be set up.

After some trial and error, I realised that the existing secret has to mirror exactly the values.yaml-syntax. And that the config residing in the secret, and the config residing in the original values.yaml-file will be merged.

Thus, for me, the solution was to create a my_secret_aad_config.yaml containing the authentication settings from above:

# in my_secret_aad_config.yaml
hub:
  config:
     AzureAdOAuthenticator:
       client_id: <my secret client_id>
       client_secret: <my secret client secret>
       tenant_id: <my tenant id>
       oauth_callback_url: <callback url>
    JupyterHub:
       authenticator_class: azuread

Then creating a kubernetes secret from this file:

kubectl create secret generic secret-aad-config --from-file=values.yaml=my_secret_aad_config.yaml -n <namespace jupyterhub deployed to>

(I then delete the file my_secret_aad_config.yaml as this is no longer needed).

Then, in values.yaml (which is the config commited to GitHub), we remove the auth-config, and reference the existing secret as such:

# in values.yaml
hub:
  existingSecret: secret-aad-config # name of the k8s secret
  # Removed the config set in the secret

Verify the solution

I was struggling to figure out how to verify that the hub properly picks up on the existing secret. However, when the hub-pod is being deployed, the first few lines of logs are:

Loading /usr/local/etc/jupyterhub/secret/values.yaml                                                                                                                                                             
Loading /usr/local/etc/jupyterhub/existing-secret/values.yaml

Documentation

I had to spend a fair bit of time figuring this out, and I think that the documentation could greatly benefit from a walk-through example of how to use this feature.

[welcome[bot]]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively. You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! :wave:
Welcome to the Jupyter community! :tada:

[meeseeksmachine]

This issue has been mentioned on Jupyter Community Forum. There might be relevant details there:

https://discourse.jupyter.org/t/how-am-i-supposed-to-use-existingsecret/5097/12

[sunkararp]

JupyterHub helm chart version: 1.3.0 I'm getting below error when I applied suggested solution

Warning  Failed                  2m56s (x12 over 5m4s)  kubelet                  Error: couldn't find key proxy.token in Secret my-jupyterhub/jupyterhub-secret-aad-config

if, I set below its working again

hub:
   config: 
     --REDACTED--
   existingSecret: ''

[consideRatio]

@sunkararp note that helm chart version 1.3.0 doesnt exist, but jupyterhub 1.3.0 does, and if thats your JH version, you are using a too old helm chart and/or a too outdated hub image.

[pebabion]

@qTipTip @consideRatio Hey guys! This seems to be working for me. Not sure why the PR is still open?

[mimizone]

I thought it was not working for me, following all the steps here. I had to actually delete the hub pod manually somehow and it started picking up the secret properly. Before that, it was reporting loading it (and the file was indeed in the /usr/local location). But it was not considered.

[npandeya]

This worked for me. Thank you. I had to just pass the client secret part into existing secret and was successfully able to mount the secret from the SecretManager. Rest of the config I left it on the main values file

[npandeya]

and also I am trying to make a oauth user admin_user based on the role claim received in the token. What would be the best way to achieve that. This will eliminate the hard coding of admin user on the config.

[qTipTip]

Hey! @consideRatio, I just stumbled upon this issue again. Is this still relevant? I haven't followed the development closely over the past year.