Add design document for "Commodore Component Dependencies"

[simu]

See also projectsyn/commodore#690

Checklist

• Keep pull requests small so they can be easily reviewed.
• Update the documentation.
• Link this PR to related issues.

[haasad]

Suggested change

	Additionally, component compilation make take longer, both because we download more data and also because Commodore needs to do more setup work before the component can be compiled.
	Additionally, component compilation may take longer, both because we download more data and also because Commodore needs to do more setup work before the component can be compiled.

or will

[haasad]

I can't really wrap my head around that; what's the benefit of specifying a minversion if there's no maxversion?

further below you write:

and the minimum required version is the maximum of all specified minimum required versions.

what's the difference to just using the latest default branch?

[simu]

For example, this enables us to use new component library functions safely and with a reasonable error message, compare the following:

Currently: you add a library function in component-espejote and you update component-openshift4-console to use that library function -> you need to manually make sure that component-espejote is updated before (or with) component-openshift4-console. Additionally if component-espejote is pinned in some catalog you'll get a cryptic Jsonnet import error.

With dependency minversion: you add a library function in component-espejote and you update component-openshift4-console to use that library function -> you update minversion for espejote in openshift4-console to the first version that provides the new function. Then Commodore will provide a nice error message for catalogs which try to use the new version of openshift4-console if component-espejote isn't updated yet.

edit: The fallback to the default branch only applies to component compilation (commodore component compile) where we want to automatically fetch dependencies.

For catalog compilation, we determine whether a component has a compatible version by looking at dependency specs and only taking the max of explicit minimum required versions (no fallback to default branch).

[simu]

Additionally, IMO, there's no benefit allowing maxversion (what do you even set maxversion to, unless we start parsing real version bounds?). The only case where maxversion could be helpful is to explicitly fail catalog compilation when a component dependency is updated to a new major version, but I don't think we really want that footgun.

[haasad]

Ok, that makes sense. I think I've fundamentally misunderstood what you're trying to achieve in the first place 🤦‍♂️

Follow-up question: How will the versioning work with https://github.com/projectsyn/jsonnet-libs ?

[simu]

Most components don't even need to know that the lib exists with this proposal. Only component-openshift4-monitoring and component-prometheus need to specify that they depend on the lib in jsonnetfile.jsonnet. Standard Commodore logic will then ensure that jb is called once the jsonnetfile.jsonnet is discovered when either of those components is a dependency of the component that's getting compiled.

[simu]

TODO: Add Lieutenant-less catalog compile as alternative for component compile. Depending on the actual complexity of component compile changes, replacing component compile as a whole with a Lieutenant-less catalog compile might be simpler in the implementation, but probably requires more refactoring in component template and existing components.

There probably are approaches where we can gradually migrate. Lieutenant-less catalog compile is also already sketched out in the Draft PR for local dev environments (#174), cf. section "Local cluster spec in reclass".

By introducing this catalog compile mode, we could eventually remove component compile completely which would reduce the number of code paths in Commodore which are almost identical, but not quite and using the "catalog compilation" flow for component tests would close the gap between component testing and real cluster catalog compilation in general.

Depending on the exact shape of the Lieutenant-less mode (it's not clear right now whether LIeutenant-less mode would still fetch a global defaults or whether that mode would operate only on local files, e.g. a single Git repo checkout -- more like Kapitan), we could also provide a reusable base inventory (e.g. by finally publishing a stripped down version of our global defaults, which could be reused in the Project Syn tutorials).