Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 clarify semantic meaning of the Version fields #11564

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

📖 clarify semantic meaning of the Version fields #11564

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api/v1beta1/machine_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,7 @@ type MachineSpec struct {
// offered by an infrastructure provider.
InfrastructureRef corev1.ObjectReference `json:"infrastructureRef"`

// version defines the desired Kubernetes version.
// version defines the desired Kubernetes distribution version.
// This field is meant to be optionally used by bootstrap providers.
// +optional
Version *string `json:"version,omitempty"`
Expand Down
2 changes: 1 addition & 1 deletion api/v1beta1/zz_generated.openapi.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion config/crd/bases/cluster.x-k8s.io_machinedeployments.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion config/crd/bases/cluster.x-k8s.io_machinepools.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion config/crd/bases/cluster.x-k8s.io_machines.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion config/crd/bases/cluster.x-k8s.io_machinesets.yaml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

60 changes: 33 additions & 27 deletions docs/book/src/developer/providers/contracts/control-plane.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,28 +57,28 @@ repo or add an item to the agenda in the [Cluster API community meeting](https:/

## Rules (contract version v1beta1)

| Rule | Mandatory | Note |
|----------------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------|
| [All resources: scope] | Yes | |
| [All resources: `TypeMeta` and `ObjectMeta`field] | Yes | |
| [All resources: `APIVersion` field value] | Yes | |
| [ControlPlane, ControlPlaneList resource definition] | Yes | |
| [ControlPlane: endpoint] | No | Mandatory if control plane endpoint is not provided by other means. |
| [ControlPlane: replicas] | No | Mandatory if control plane has a notion of number of instances. |
| [ControlPlane: version] | No | Mandatory if control plane allows direct management of the Kubernetes version in use; Mandatory for cluster class support. |
| [ControlPlane: machines] | No | Mandatory if control plane instances are represented with a set of Cluster API Machines. |
| [ControlPlane: initialization completed] | Yes | |
| [ControlPlane: conditions] | No | |
| [ControlPlane: terminal failures] | No | |
| [ControlPlaneTemplate, ControlPlaneTemplateList resource definition] | No | Mandatory for ClusterClasses support |
| [Cluster kubeconfig management] | Yes | |
| [Cluster certificate management] | No | |
| [Machine placement] | No | |
| [Metadata propagation] | No | |
| [MinReadySeconds and UpToDate propagation] | No | |
| [Support for running multiple instances] | No | Mandatory for clusterctl CLI support |
| [Clusterctl support] | No | Mandatory for clusterctl CLI support |
| [ControlPlane: pausing] | No | |
| Rule | Mandatory | Note |
|----------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------|
| [All resources: scope] | Yes | |
| [All resources: `TypeMeta` and `ObjectMeta`field] | Yes | |
| [All resources: `APIVersion` field value] | Yes | |
| [ControlPlane, ControlPlaneList resource definition] | Yes | |
| [ControlPlane: endpoint] | No | Mandatory if control plane endpoint is not provided by other means. |
| [ControlPlane: replicas] | No | Mandatory if control plane has a notion of number of instances. |
| [ControlPlane: version] | No | Mandatory if control plane allows direct management of the Kubernetes distribution version in use; Mandatory for cluster class support. |
| [ControlPlane: machines] | No | Mandatory if control plane instances are represented with a set of Cluster API Machines. |
| [ControlPlane: initialization completed] | Yes | |
| [ControlPlane: conditions] | No | |
| [ControlPlane: terminal failures] | No | |
| [ControlPlaneTemplate, ControlPlaneTemplateList resource definition] | No | Mandatory for ClusterClasses support |
| [Cluster kubeconfig management] | Yes | |
| [Cluster certificate management] | No | |
| [Machine placement] | No | |
| [Metadata propagation] | No | |
| [MinReadySeconds and UpToDate propagation] | No | |
| [Support for running multiple instances] | No | Mandatory for clusterctl CLI support |
| [Clusterctl support] | No | Mandatory for clusterctl CLI support |
| [ControlPlane: pausing] | No | |

### All resources: scope

Expand Down Expand Up @@ -384,7 +384,7 @@ the ControlPlane `spec`.

```go
type FooControlPlaneSpec struct {
// version defines the desired Kubernetes version for the control plane.
// version defines the desired Kubernetes distribution version for the control plane.
// The value must be a valid semantic version; also if the value provided by the user does not start with the v prefix, it
// must be added.
Version string `json:"version"`
Expand All @@ -398,7 +398,7 @@ Following fields MUST be implemented in the ControlPlane `status`.

```go
type FooControlPlaneStatus struct {
// version represents the minimum Kubernetes version for the control plane machines
// version represents the minimum Kubernetes distribution version for the control plane machines
// in the cluster.
// +optional
Version *string `json:"version,omitempty"`
Expand All @@ -408,9 +408,15 @@ type FooControlPlaneStatus struct {
}
```

NOTE: The minimum Kubernetes version, and more specifically the API server version, will be used to determine
when a control plane is fully upgraded (spec.version == status.version) and for enforcing Kubernetes version skew
policies when a Cluster derived from a ClusterClass is managed by the Topology controller.
NOTE: The minimum Kubernetes distribution version, and more specifically the API server version, will be used to determine
when a control plane is fully upgraded (spec.version == status.version) and for enforcing Kubernetes version skew
policies[1](#kubernetes-version-in-skew-policy) when a Cluster derived from a ClusterClass is managed by the Topology controller.

#### Kubernetes version in version skew policies

`controlplane.spec.version` and `machineset/machinedeploment.spec.template.spec.version` represent a Kubernetes distribution version.
However, in the case of the machine preflight for kubernetes version policies, it is coupled with an actual Kubernetes version.
This particular check will not be reliable if Kubernetes distribution version is used.

### ControlPlane: machines

Expand Down
1 change: 1 addition & 0 deletions docs/book/src/tasks/experimental-features/machineset-preflight-checks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ Enabling `MachineSetPreflightChecks` provides safety in such circumstances by ma
* The Cluster uses a ControlPlane provider.
* ControlPlane version is defined (`ControlPlane.spec.version` is set).
* MachineSet version is defined (`MachineSet.spec.template.spec.version` is set).
* Note that in this case, an actual Kubernetes version is needed (as opposed as a Kubernetes distribution version).

### `KubeadmVersionSkew`

Expand Down
Loading