[Module catalogue improvements] Update ModuleTemplate API version to support fixed module versions

[Tomasz-Smelcerz-SAP]

Description

Note: This issue is just about API change, the change in the controller logic is expected to be implemented here

As described here, ModuleTemplate CR must be extended.

What we essentially want follows the ideas from the community-modules repository.
In general, we want that:

• Every ModuleTemplate describes a single module version
• Every such version may be selected by user(s) for installation
• Every such version may be assigned to a set of channels - possibly empty. Module Team decides about versions-channels mapping.

In addition, to support Deletion modes we need a managedResources list describing the list of Group/Version/Kinds that are defined by the Module's Team as "managed" by the module.
There is a decision record for that. Assuming that list is embedded, no further API changes are required on the ModuleTemplate CR.

The set of ModuleTemplate CRs in the control-plane defines the Module Catalog for the Lifecycle-Manager.

The above requirements can be implemented by releasing a new ModuleTemplate API version with the following changes:

• Deprecate the channel attribute
• Add an optional version attribute. At the moment it is an annotation: "operator.kyma-project.io/module-version": "0.1.2". This attribute will be required in the future
• Add an optional name attribute. At the moment it is a label: "operator.kyma-project.io/module-name": "template-operator". It is not strictly required, it's just to make the API more robust. It will be required in the future.

Reasons

We need that to support features described in #1472

The Data Model

Example: Consider a module: foo.
It will be released in two versions available for user to install: 1.0.0, 2.0.0.
Additionally there is a 2.2.0 version that is only available in the experimental channel.
The 1.0.0 is released in the regular channel, the 2.0.0 version is released in the fast channel

We need five ModuleTemplate CRs to model that:

1. ModuleTemplate for the version 1.0.0

name: "foo"
version: "1.0.0"
descriptor: [ OCM descriptor for version 1.0.0 ]

2. ModuleTemplate for the version 2.0.0

name: "foo"
version: "2.0.0"
descriptor: [ OCM descriptor for version 2.0.0 ]

3. ModuleTemplate for the regular channel

name: "foo"
version: "regular"
descriptor: [ OCM descriptor for version 1.0.0 ]

4. ModuleTemplate for the fast channel

name: "foo"
version: "fast"
descriptor: [ OCM descriptor for version 2.0.0 ]

5. ModuleTemplate for the experimental channel

name: "foo"
version: "experimental"
descriptor: [ OCM descriptor for version 2.2.0 ]

After some time, the team decides to upgrade the module in the regular channel and also make the version 2.2.0 explicitly available for users. In order to do that the module team must:

1. Update the ModuleTemplate for the regular channel:

name: "foo"
version: "regular"
descriptor: [ OCM descriptor for version 2.0.0 ]

2. Create a new ModuleTemplate for the 2.2.0 version:

name: "foo"
version: "2.2.0"
descriptor: [ OCM descriptor for version 2.2.0 ]

In this model, the channel is just another "version" to choose from. The channel doesn't refer to any other ModuleTemplate CR, it only references an OCM artifact - like any other version. It is responsibility of the Team that manages the module to take care that the ModuleTemplate with a channel as a version refers to a proper OCM artifact. In other words the mapping of "channel" to "module version" is implicit here.
Yet, the desired feature of having a channel that is a "label" on a single module version is achieved. For example, a ModuleTemplate for some module that uses regular as a version may refer to the same OCM artifact as a ModuleTemplate for the same module that uses 1.0.0 as a version. It may also refer to the OCM artifact for which there is no explicit "versioned" ModuleTemplate, yet it is still some version - because it exists as an OCM artifact so it was released.

Single attribute vs two attributes

The same model can be expressed in two ways:

• having a single version attribute that can take values like 1.0.0, 2.0.0, regular, fast etc.
• having a separate channel attribute (regular, fast) and a separate version attribute (1.0.0, 2.0.0) with additional validation that only one of these may be defined - the other one must be empty.

A single attribute solution is simpler, but if this cannot be easily validated (a string that is either semantic version OR arbitrary token), the double-attribute solution is an option.

Summary

We have decided to go with the two-attribute solution described in this comment.

No validation is required for now.

Examples for valid Module Templates

# ModuleTemplate
metadata:
  name: template-operator-2.3.1
spec:
  moduleName: template-operator
  channel: none
  version: 2.3.1
---
# ModuleTemplate
metadata:
  name: template-operator-regular
spec:
  moduleName: template-operator
  channel: regular
  version: 2.3.1
---
# ModuleTemplate
metadata:
  name: template-operator-fast
spec:
  moduleName: template-operator
  channel: fast
  version: 2.3.1

Acceptance Criteria

• Extend the model with an optional version attribute. The value must be a semantic version.
• channel attribute should stay mandatory.
• Add an explicit optional moduleName attribute (currently it is a label).
• Do not introduce new API version
• Create a list of changes to include in a new ModuleTemplate API versions, i.e.,
  • version attribute to become mandatory
  • moduleName attribute to become mandatory

Notes:
In order to support existing ModuleTemplates, the version must be optional. Existing modules will have it empty.
New modules will have the version provided.
The same with the new moduleName attribute.
The implementation must deal with that correctly.

Feature Testing

e2e tests for validation on the new API version.

Testing approach

No response

Attachments

No response

Related issue(s)

#1472