---
# System prepended metadata

title: Version validation for Minimum and/or Maximum version for CAPI objects

---

<!-- NOTE: ⚠️ For larger proposals, we follow the CAEP process as outlined in https://sigs.k8s.io/cluster-api/CONTRIBUTING.md. -->
# Version validation for Minimum and/or Maximum version for CAPI objects

**User Story**

As a operator I would like to ensure that a user is not able to create/update a Cluster/KubeadmControlPlane/MachineDeployment/MachineSet/Machine in/to a Kubernetes Version which is not supported by the version of Cluster API currently in use for ensuring compatibility.

**Detailed Description**

The Cluster API project currently maintains a documentation which maps the version of Cluster API core providers to a list of Kubernetes Versions which are supported for workload clusters [per component](https://cluster-api.sigs.k8s.io/reference/versions.html#release-components).

This issue proposes adding additional validation for the objects Cluster, KubeadmControlPlane, MachineDeployment, MachinePool, MachineSet and Machine to reject objects which violate the minimum and/or maximum supported version.

It may make sense to also add an annotation to implicitly skip/ignore this validation by a user similar to the annotation `unsafe.topology.cluster.x-k8s.io/disable-update-class-name-check`.
E.g.: `unsafe.cluster.x-k8s.io/disable-minmax-version-check`.

**Anything else you would like to add:**

There is already a validation for the supported [minimum](https://github.com/kubernetes-sigs/cluster-api/blob/2ae18814b7923030e38454befb494bec0cd30841/version/version.go#L32) management cluster version in CAPI.

/kind feature

# Version validation according Kubernetes Version Skew Policy

**User Story**

As a operator I would like to ensure that creating/updating a Cluster/KubeadmControlPlane/MachineDeployment/MachineSet/Machine does not violate the [Kubernetes Version Skew Policy] for staying in supported upgrade paths and not break running applications.

**Detailed Description**

This issue proposes to add additional validation against the [Kubernetes Version Skew Policy].

Assuming version v1.X is the desired kubernetes version:

* For a KubeadmControlPlane or a ControlPlane Machine:
    * > [...] the newest and oldest `kube-apiserver` instances must be within one minor version.
* For a MachineDeployment, MachineSet or workload Machine
    * > [...] must not be newer than `kube-apiserver`, and may be up to two minor versions older.

To-be-discussed:

* Should the Kubernetes Version Skew Policy validations only get implemented for ClusterClass based Clusters / Validation on `Cluster.spec.topology.version`?
    * An arguments for that is: on ClusterClass based Clusters the topology and relations are well-defined with a top-down approach.


**Anything else you would like to add:**

* There is already version validation at the ClusterClass based clusters (via `.spec.topology.version`). [xref](https://github.com/kubernetes-sigs/cluster-api/blob/a087b0214b77fff36428c7ac513f4d02272f1f4f/internal/webhooks/cluster.go#L309)
    * The current implementation does not allow to downgrade patch versions, which would be allowed from the Kubernetes Version Skew policy side.

* Kubeadm also does [validation against the Kubernetes Version Skew Policy](https://github.com/kubernetes/kubernetes/blob/e234917e0a3e4bb384ef14c198742643a7e170fd/cmd/kubeadm/app/phases/upgrade/policy.go), but this may not map to the current documentation at [Kubernetes Version Skew Policy].

/kind feature
