Zero-to-jupyterhub-k8s: schema.yaml: not all configuration options are documented

[consideRatio]

What is schema.yaml? The configuration reference!

schema.yaml is a JSONSchema specification of the values that the Helm chart accepts, we currently use it to generate documentation as can be seen in Configuration reference section of the guide.

This documentation in schema.yaml should be kept up to date with the values the Helm chart template depends on when they render into valid k8s resources. The default values of the Helm chart, in values.yaml, should also contain a default entry for all of the options and is currently a more complete overview of what is configurable.

Missing schema.yaml entries

If you find more missing entries, comment in this thread so we can add them to this list, and if you document them in schema.yaml, either directly update this list if you have permission to do so or comment so a maintainer can do it for you.

• [ ] singleuser.serviceAccountName
• [ ] singleuser.storage
• [ ] singleuser.defaultUrl
• [ ] hub.concurrentSpawnLimit (reported in #1725)

[NerdSec]

Hi @consideRatio ,

So, I flattened the two yaml in schema.yaml and values.yaml, and took a diff of schema from values. I found around 110 individual values present in values.yaml but not documented in schema.yaml.

I am no expert on JupyterHub and have tried to put together a doc that i felt should be documented. Here is the link.

So, basically, anything that we expect the user should have the rights to edit should be documented in schema.yaml. Apologies if the approach was silly, do let me know what you think!

[NerdSec]

Also, since schema.yaml is used to generate the docs here.

Do you think it makes sense to automate the generation of the at least the values from values.yaml? Maybe add comments to each entry and use that comment as the default docstring? Or something similar along those lines. This will ensure that we don't miss out generating docs as we add new features in the helm chart.

[consideRatio]

Oh nice diff of the files, that can be very useful! Thank you!

@NerdSec I lean towards thinking the best aim is to make schema.yaml into values.schema.yaml, but I'm not sure. We should avoid writing reference documentation at two places at least.

Related: #1316

[NerdSec]

I think we can generate a reference doc easily if have the values.schema.yaml implemented. That should not be a problem. I really like this solution, a lot more elegant!

[NerdSec]

So, I was just reading up on this, and it sounds like the schema.yaml already has the structure required. I guess only the title seems different.

Would it make sense to rename the file and change the title to Values?

But, how do you ensure that any new values in the schema.yaml are added to the values.schema.yaml? Does adding a script to the conf.py to check the diffs of the two yaml make sense? I'd be happy to pick this up. Let me know if I should raise a new PR or add it to #1825?

[consideRatio]

@NerdSec ohhh! Having an automated check that values.yaml entries are represented in values.schema.yaml would be great! Initially we could let that check be allowed to fail in the CI environment, but once we have made it stop breaking we can make it fail hard to force all new features have it! I love this idea, you have already demonstrated its feasible!

Oh I love that idea! This would be useful for ALL helm charts, not just this one, and perhaps in the long run turning into a GitHub action that lets you specify the schema file and the values file and just do the 1:1 check providing output of what doesn't match yet.

Also, we could improve our generation of the docs to include default values taken form values.yaml for example.

---

But, how do you ensure that any new values in the schema.yaml are added to the values.schema.yaml?

I assume you meant values.yaml and values.schema.yaml here btw

[NerdSec]

Some early work for comparing the values.yaml and schema.yaml (which will become values.schema.json in the future).

https://gist.github.com/NerdSec/1fa3993b15bca3cb0104c42f603ddea6

Implementing some sort of whitelist to identify the keys which we don't expect to be user editable, so that it does not crop up in the comparison needs to be done.