JSON Schema Keeps Failing Builds Irrespective of what the Changes Are

[ChrisJBurns]

The current schema dereference script is run in the pipeline for all changes. However even when there are no changes to the Helm chart itself, when the script is run, it generates changes which require a bump in the Helm chart - which shouldn't be necessary.

This is because the dereference script runs during pre-commit hooks and regenerates this file even when nothing in the actual Helm chart has changed. The script pulls from Kubernetes API schemas and expands $ref references, but:

1. Kubernetes API schemas change - Even if the chart doesn't change, the underlying K8s API schemas get updated
2. Non-deterministic ordering - The dereferencing process might reorder fields differently each time
3. Formatting differences - Whitespace, indentation, or JSON serialisation differences

This creates "fake" schema changes that force unnecessary Helm chart version bumps.

We should evaluate whether there is a better way of writing the script so that it doesn't raise changes when nothing in the Chart has changed or even whether it adds the additional value that is worth the upkeep.

Potential fixes to improve the process:

• The dereference script should only update the schema file when there are actual semantic changes to the chart's values.schema.tmpl.json or when explicitly requested, not on every pre-commit run. (most desirable?)
• Remove the dereference script (most undesirable)
• Create a job that runs the dereference script every night at a specific time that write the changes back to source control to avoid them coming up in a PR. This would however still require helm chart bumps (not as desirable)

[rm3l]

On the Kubernetes API schema change note, as another possible approach, how about pinning the $ref URLs to a specific version of the K8s API instead?
I noticed that the current schema template uses master at lot (like here) from https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master, but perhaps it would be safer to use a dedicated folder version instead (like https://github.com/yannh/kubernetes-json-schema/tree/master/v1.33.4 ).. I would have preferred a branch or tag, but it looks like https://github.com/yannh/kubernetes-json-schema has a single master branch in which all the versions are stored.

In other places like here, we are pointing to a pinned version (https://kubernetesjsonschema.dev/v1.8.7), which is safer IMO.

That being said, I guess we would still need to fix the non-deterministic ordering behavior anyway.

[ChrisJBurns]

@rm3l Yeah I completely agree, pinning it to a version is definitely a step in the right direction. From that we can see how often the ordering issue happens and go from there.

[rm3l]

I can look into this if you want (but tomorrow, as it's getting late here), unless you are already on it ;)

[ChrisJBurns]

@rm3l Yep go for it. I'm currently busy trying to find a strong enough dual monitor arm for my 2 new monitors, so my night is booked 😆

[rm3l]

ack, I'll assign this to myself then. Good luck with the monitors setup 💪🖥️😆

[rm3l]

ah, I cannot self-assign this. Please assign it to me if possible. No problem otherwise - I'll try not to forget to do it tomorrow :D

[rm3l]

@ChrisJBurns #277, FYI.