|
| 1 | += SDD 0033 - Commodore Component Instance Versioning |
| 2 | + |
| 3 | +:sdd_author: Aline Abler |
| 4 | +:sdd_owner: |
| 5 | +:sdd_reviewers: SIG |
| 6 | +:sdd_date: 2025-01-08 |
| 7 | +:sdd_status: draft |
| 8 | +include::partial$meta-info-table.adoc[] |
| 9 | + |
| 10 | +[NOTE] |
| 11 | +.Summary |
| 12 | +==== |
| 13 | +This SDD describes possible options to allow specifying different versions for each instance of the same Commodore component. |
| 14 | +It additionally details the options we chose to implement. |
| 15 | +==== |
| 16 | + |
| 17 | +== Motivation |
| 18 | + |
| 19 | +With xref:0025-commodore-component-instantiation.adoc[SDD 0025], Commodore can instantiate a component multiple times per cluster if multiple aliases are specified. |
| 20 | +However, all aliases currently use version information from the base component. |
| 21 | +Commodore does not currently support specifying different component versions for each alias. |
| 22 | + |
| 23 | +=== Goals |
| 24 | + |
| 25 | +* Define how different versions for each component instance can be specified and generated. |
| 26 | + |
| 27 | +=== Non-Goals |
| 28 | + |
| 29 | + |
| 30 | + |
| 31 | +== Design Proposal |
| 32 | + |
| 33 | +Commodore will leverage the existing configuration options in `.parameters.components` to retrieve version information for specific instances. |
| 34 | +Instance versions can be specified in `.parameters.components.<instance-name>` and override the value specified in `.parameters.components.<component-name>`. |
| 35 | +Even if all instances provide their own version, a version for the base component (`.parameters.components.<component-name>`) must still be specified. |
| 36 | + |
| 37 | +Component authors must explicitly declare that their component supports multi-versioning. |
| 38 | +In a valid catalog, all used versions of the same component must advertise this support. |
| 39 | + |
| 40 | +Components with multi-versioning support must ensure they create no file conflicts when downloading dependencies. |
| 41 | +In practice, this means components must use the parameter `${_base_directory}` in their compile configuration (`parameters.kapitan.dependencies` and `parameters.kapitan.compile`). |
| 42 | + |
| 43 | +Support for providing different versions of Jsonnet dependencies is currently not implemented. |
| 44 | +Jsonnet dependencies are always provided from the main (non-instantiated) version of the component. |
| 45 | +If a component is to support multi-versioning, Jsonnet dependencies should therefore be compatible within a reasonable span of versions. |
| 46 | + |
| 47 | +Similarly, if the component includes a Jsonnet library that is made available to other components, the version for the library is taken from the main (non-instantiated) version of the component. |
| 48 | + |
| 49 | +=== Implementation Details/Notes/Constraints |
| 50 | + |
| 51 | +We can clone the repository of the base component and create a separate worktree for each instance to check out the correct version. |
| 52 | + |
| 53 | +If the instance version specifies a different URL from the base component, more work is needed: in this case, we clone the changed repository for the instance and create a worktree from that. |
| 54 | + |
| 55 | +This means that if two instances both override the URL to the same value, this repository is cloned twice, which can impact performance. |
| 56 | +However, since this only affects instances which override the repository URL, the impact is tolerable. |
| 57 | + |
| 58 | +=== Risks and Drawbacks |
| 59 | + |
| 60 | +* Since the JSonnet dependencies and libraries are all provided from a single component version, there is a risk for some combinations of versions not compiling properly due to version compatibility issues. |
| 61 | +** Even if a component's dependencies are sufficiently backwards-compatible at the moment, it's possible for future changes to break compatibility. |
| 62 | +This might force a component author to remove multi-version support in higher component versions, causing a catalog to stop compiling if either component instance is updated. |
| 63 | +* Overriding the repository URL in a component instance always causes a new repository to be cloned - even if the same URL is used in multiple instances. |
| 64 | + |
| 65 | +== Alternatives |
| 66 | + |
| 67 | +=== Automatically detecting multi-version support |
| 68 | + |
| 69 | +It could be possible to automatically determine whether a component supports multi-versioning, by way of checking whether the `${_base_directory}` parameter is used in the component's compile configuration. |
| 70 | +However, automatically declaring components to be "safe for multi-versioning" carries some risk - even if a component is configured accordingly, it is not guaranteed that its provided JSonnet libraries and/or its JSonnet dependencies work if used across versions. |
| 71 | +Therefore, we deem it safer to let component authors decide if multi-versioning is safe to use for their component. |
| 72 | + |
| 73 | +=== Supporting different versions of JSonnet dependencies per instance |
| 74 | + |
| 75 | +We could possibly achieve support for separate Jsonnet dependency versions per instance by reworking how we interface with Kapitan's `compile()` function. |
| 76 | +This would require more extensive reworking of Commodore. |
| 77 | + |
| 78 | +Making this change has no direct impact on the implementation of the multi-versioning feature, so support can still be added at a future time if required. |
| 79 | + |
| 80 | +=== Supporting different versions of a component's provided JSonnet libraries per instance |
| 81 | + |
| 82 | +It might be possible to allow multiple versions of a component's JSonnet libraries to be made available to other components. |
| 83 | +Other components would have to refer to the libraries using a specific instance's name. |
| 84 | +This would change how components refer to libraries, and would cause components to be somewhat aware of the context in which they are used in order to refer to the correct instances. |
| 85 | +Since components should be modular and reusable, introducing this sort of coupling goes against the design principles of Project Syn. |
| 86 | + |
| 87 | +== References |
| 88 | + |
| 89 | +* xref:0025-commodore-component-instantiation.adoc[0025 - Commodore Component Instantiation] |
| 90 | +* https://github.com/projectsyn/commodore/issues/563[projectsyn/commodore#563] |
| 91 | +* https://github.com/projectsyn/commodore/pull/559[projectsyn/commodore#559] |
0 commit comments