Skip to content

✨ Add types and hook for GenerateUpgradePlan #12823

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+368 −0
Open

✨ Add types and hook for GenerateUpgradePlan #12823

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
110 changes: 110 additions & 0 deletions api/runtime/hooks/v1alpha1/upgrade_plan_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
/*
Copyright 2025 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package v1alpha1

import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

clusterv1beta1 "sigs.k8s.io/cluster-api/api/core/v1beta1"
runtimecatalog "sigs.k8s.io/cluster-api/exp/runtime/catalog"
)

// GenerateUpgradePlanRequest is the request of the GenerateUpgradePlan hook.
// +kubebuilder:object:root=true
type GenerateUpgradePlanRequest struct {
metav1.TypeMeta `json:",inline"`

// CommonRequest contains fields common to all request types.
CommonRequest `json:",inline"`

// cluster is the cluster ofject the lifecycle hook correspods to.
// +required
Cluster clusterv1beta1.Cluster `json:"cluster,omitempty,omitzero"`
Comment on lines +34 to +36
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// cluster is the cluster ofject the lifecycle hook correspods to.
// +required
Cluster clusterv1beta1.Cluster `json:"cluster,omitempty,omitzero"`
// cluster is the cluster object the GenerateUpgradePlan request corresponds to.
// +required
Cluster clusterv1.Cluster `json:"cluster,omitempty,omitzero"`

Let's go with v1beta2. I know the proposal says v1beta1, but we already decided for the in-place implementation to just directly go with v1beta2 to avoid conversion issues. I would do the same here

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 on using v1beta2 (sorry I forgot to update the comment with implementation details for this PR 😅)


// fromControlPlaneKubernetesVersion is the current Kubernetes version of the control plane.
// +required
// +kubebuilder:validation:MinLength=1
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure about all the kubebuilder:validation: + listType markers. None of these are used anywhere as these are not CRDs so nobody implements the corresponding validation.
I would probably remove them (but let's definitely keep optional + required, this seems like useful info in general)

@fabriziopandini WDYT?

Copy link
Member

@fabriziopandini fabriziopandini Oct 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the request I think it is ok to have both +required and MinLength, because CAPI will always send a value for the fields that are currently marked as required (and the field that is marked optional will have lenght > 1 when set)

For the response I think it makes sense to keep markers only what we are going enforcing when we are validating the response in

cluster-api/exp/topology/desiredstate/upgrade_plan.go

Line 133 in 9db4c78

func DefaultAndValidateUpgradePlans(desiredVersion string, controlPlaneVersion string, minWorkersVersion string, controlPlaneUpgradePlan []string, workersUpgradePlan []string) ([]string, error) {
.
Accordingly, let's drop both listType and Min/MaxItems for both arrays.

FromControlPlaneKubernetesVersion string `json:"fromControlPlaneKubernetesVersion,omitempty"`

// fromWorkersKubernetesVersion is the current Kubernetes version of the workers.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// fromWorkersKubernetesVersion is the current Kubernetes version of the workers.
// fromWorkersKubernetesVersion is the min Kubernetes version of the workers (MachineDeployments and MachinePools).

// +optional
// +kubebuilder:validation:MinLength=1
FromWorkersKubernetesVersion string `json:"fromWorkersKubernetesVersion,omitempty"`

// toKubernetesVersion is the target Kubernetes version for the upgrade.
// +required
// +kubebuilder:validation:MinLength=1
ToKubernetesVersion string `json:"toKubernetesVersion,omitempty"`
}

var _ ResponseObject = &GenerateUpgradePlanResponse{}

// GenerateUpgradePlanResponse is the response of the GenerateUpgradePlan hook.
// +kubebuilder:object:root=true
type GenerateUpgradePlanResponse struct {
metav1.TypeMeta `json:",inline"`

// CommonResponse contains Status and Message fields common to all response types.
CommonResponse `json:",inline"`

// controlPlaneUpgrades is the list of version upgrade steps for the control plane.
// Each entry represents an intermediate version that must be applied in sequence.
Comment on lines +64 to +65
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add some more details on the rules that applies to the upgrade plan

Suggested change
// controlPlaneUpgrades is the list of version upgrade steps for the control plane.
// Each entry represents an intermediate version that must be applied in sequence.
// controlPlaneUpgrades is the list of version upgrade steps for the control plane.
// Each entry represents an intermediate version that must be applied in sequence.
// The following rules apply:
// - there should be at least one version for every minor between fromControlPlaneKubernetesVersion (excluded) and ToKubernetesVersion (included).
// - each version must be:
// - greater than fromControlPlaneKubernetesVersion (or with a different build number)
// - greater than the previous version in the list (or with a different build number)
// - less or equal to ToKubernetesVersion (or with a different build number)
// - the last version in the plan must be equal to ToKubernetesVersion

// +optional
// +listType=atomic
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:MaxItems=1000
ControlPlaneUpgrades []UpgradeStep `json:"controlPlaneUpgrades,omitempty"`

// workersUpgrades is the list of version upgrade steps for the workers.
// Each entry represents an intermediate version that must be applied in sequence.
Comment on lines +72 to +73
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// workersUpgrades is the list of version upgrade steps for the workers.
// Each entry represents an intermediate version that must be applied in sequence.
// workersUpgrades is the list of version upgrade steps for the workers.
// Each entry represents an intermediate version that must be applied in sequence.
//
// In case the upgrade plan for workers will be left to empty, the system will automatically
// determine the minimal number of workers upgrade steps, thus minimizing impact on workloads and reducing
// the overall upgrade time.
//
// If instead for any reason a custom upgrade path for workers is required, the following rules apply:
// - each version must be:
// - equal to FromControlPlaneKubernetesVersion or to one of the versions in the control plane upgrade plan.
// - greater than FromWorkersKubernetesVersion (or with a different build number)
// - greater than the previous version in the list (or with a different build number)
// - less or equal to the ToKubernetesVersion (or with a different build number)
// - in case of versions with the same major/minor/patch version but different build number, also the order
// of those versions must be the same for control plane and worker upgrade plan.
// - the last version in the plan must be equal to ToKubernetesVersion
// - the upgrade plane must have all the intermediate version which workers must go through to avoid breaking rules
// defining the max version skew between control plane and workers.

// +optional
// +listType=atomic
// +kubebuilder:validation:MinItems=1
// +kubebuilder:validation:MaxItems=1000
WorkersUpgrades []UpgradeStep `json:"workersUpgrades,omitempty"`
}

// UpgradeStep represents a single version upgrade step.
type UpgradeStep struct {
// version is the Kubernetes version for this upgrade step.
// +required
// +kubebuilder:validation:MinLength=1
Version string `json:"version,omitempty"`
}

// GenerateUpgradePlan is the hook that will be called to generate an upgrade plan
// for a cluster. This hook allows runtime extensions to specify intermediate
// Kubernetes versions that must be applied during an upgrade from the current
// version to the target version.
func GenerateUpgradePlan(*GenerateUpgradePlanRequest, *GenerateUpgradePlanResponse) {}

func init() {
catalogBuilder.RegisterHook(GenerateUpgradePlan, &runtimecatalog.HookMeta{
Tags: []string{"Chained Upgrade Hook"},
Summary: "Cluster API Runtime will call this hook to generate an upgrade plan for a cluster",
Description: "Cluster API Runtime will call this hook to generate an upgrade plan for a cluster. " +
"Runtime Extension implementers can use this hook to specify intermediate Kubernetes versions " +
"that must be applied during an upgrade from the current version to the target version.\n" +
"\n" +
"For example, if upgrading from v1.29.0 to v1.33.0 requires intermediate versions v1.30.0, " +
"v1.31.0, and v1.32.0, the hook should return these intermediate versions in the response.\n" +
"\n" +
"Notes:\n" +
"- The response may include separate upgrade paths for control plane and workers\n" +
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"- The response may include separate upgrade paths for control plane and workers\n" +
"- The response may include separate upgrade paths for control plane and workers\n" +
"- The upgrade plan for workers is optional; if missing the system will automatically\n\"" +
" determine the minimal number of workers upgrade steps according to Kubernetes version skew rules.\n" +

"- Each upgrade step represents a version that must be applied in sequence",
})
}
76 changes: 76 additions & 0 deletions api/runtime/hooks/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

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

Loading