Introduce distributionVersion field for improved Kubernetes Distribution version handling

[rccrdpccl]

What would you like to be added (User Story)?

As a user I would like to have a distributionVersion field to better handle versioning of the kubernetes distribution being installed

Detailed Description

Currently, the handling of Kubernetes versions in the version field is problematic when installing or upgrading a distribution of Kubernetes that utilizes its own version scheme and lifecycle. A distribution can include more software components than just Kubernetes, and/or a distinct support lifecycle that includes the release of fixes and other changes on its own timeline. Those characteristics can necessitate the use of an independent version scheme.
The version field, present in multiple resources: ControlPlane, MachineSpec, Cluster Topology, specifically represents the Kubernetes version. In order to control the cluster’s distribution version, we need to specify its value for the ControlPlane and MachineSet/MachineDeployment objects involved. This is problematic when a user wants to deploy a specific version of a kubernetes distribution, they cannot specify the version, but it should be calculated based on the related kubernetes version (which is not always possible in any case).

To address this, we propose introducing a new field, spec.distributionVersion in the following resources:

• ControlPlane (ControlPlane.Spec.Version)
• MachineSpec (Machine.Spec.Version /MachineSet.Spec.Template.Spec.Version/MachineDeploymen.Spec.Template.Spec.Version/MachinePool.Spec.Template.Spec.Version)
• Topology (Cluster.Topology.Version)

The new field and the current spec.version would be mutually exclusive.

This would be an optional field for both the ControlPlane contract and MachineSpec. Its value would be the distribution version (e.g. for OpenShift it should be something like v4.17.0). No version semantics will be imposed on the field.

If distributionVersion is present, the status.version should be populated with the related kubernetes version (e.g. for OpenShift with distributionVersion with value 4.17.0, status.version should be 1.30.4).

All logic that makes a decision based on evaluating the kubernetes version should rely on the status field instead of the spec field.

Related:

#11564

/cc @fabriziopandini @enxebre @sbueringer

Anything else you would like to add?

No response

Label(s) to be applied

/kind feature
/area api

[k8s-ci-robot]

This issue is currently awaiting triage.

If CAPI contributors determine this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[fabriziopandini]

Thanks for filing this issue as a follow up of the discussion on the PR!

Somehow related, we should consider also KEP-4330: Compatibility Versions in Kubernetes which is introducing emulated-versions and min compatibility version as a key info to influence the cluster behaviour (see user stories in the KEP)