Skip to content

Commit 490f76e

Browse files
sivcharisivchari
authored
✨ Add types and hook for GenerateUpgradePlan (#12823)
* Add types and hook for GenerateUpgradePlan Signed-off-by: sivchari <shibuuuu5@gmail.com> * fix review findings Signed-off-by: sivchari <shibuuuu5@gmail.com> * fix review findings Signed-off-by: sivchari <shibuuuu5@gmail.com> --------- Signed-off-by: sivchari <shibuuuu5@gmail.com>
1 parent 2923124 commit 490f76e

File tree

3 files changed

+377
-0
lines changed

3 files changed

+377
-0
lines changed

‎api/runtime/hooks/v1alpha1/upgrade_plan_types.go‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
/*
2+
Copyright 2025 The Kubernetes Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package v1alpha1
18+
19+
import (
20+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
21+
22+
clusterv1 "sigs.k8s.io/cluster-api/api/core/v1beta2"
23+
runtimecatalog "sigs.k8s.io/cluster-api/exp/runtime/catalog"
24+
)
25+
26+
// GenerateUpgradePlanRequest is the request of the GenerateUpgradePlan hook.
27+
// +kubebuilder:object:root=true
28+
type GenerateUpgradePlanRequest struct {
29+
metav1.TypeMeta `json:",inline"`
30+
31+
// CommonRequest contains fields common to all request types.
32+
CommonRequest `json:",inline"`
33+
34+
// cluster is the cluster object the GenerateUpgradePlan request corresponds to.
35+
// +required
36+
Cluster clusterv1.Cluster `json:"cluster,omitempty,omitzero"`
37+
38+
// fromControlPlaneKubernetesVersion is the current Kubernetes version of the control plane.
39+
// +required
40+
// +kubebuilder:validation:MinLength=1
41+
FromControlPlaneKubernetesVersion string `json:"fromControlPlaneKubernetesVersion,omitempty"`
42+
43+
// fromWorkersKubernetesVersion is the min current Kubernetes version of the workers.
44+
// +optional
45+
// +kubebuilder:validation:MinLength=1
46+
FromWorkersKubernetesVersion string `json:"fromWorkersKubernetesVersion,omitempty"`
47+
48+
// toKubernetesVersion is the target Kubernetes version for the upgrade.
49+
// +required
50+
// +kubebuilder:validation:MinLength=1
51+
ToKubernetesVersion string `json:"toKubernetesVersion,omitempty"`
52+
}
53+
54+
var _ ResponseObject = &GenerateUpgradePlanResponse{}
55+
56+
// GenerateUpgradePlanResponse is the response of the GenerateUpgradePlan hook.
57+
// +kubebuilder:object:root=true
58+
type GenerateUpgradePlanResponse struct {
59+
metav1.TypeMeta `json:",inline"`
60+
61+
// CommonResponse contains Status and Message fields common to all response types.
62+
CommonResponse `json:",inline"`
63+
64+
// controlPlaneUpgrades is the list of version upgrade steps for the control plane.
65+
// Each entry represents an intermediate version that must be applied in sequence.
66+
// The following rules apply:
67+
// - there should be at least one version for every minor between fromControlPlaneKubernetesVersion (excluded) and ToKubernetesVersion (included).
68+
// - each version must be:
69+
// - greater than fromControlPlaneKubernetesVersion (or with a different build number)
70+
// - greater than the previous version in the list (or with a different build number)
71+
// - less or equal to ToKubernetesVersion (or with a different build number)
72+
// - the last version in the plan must be equal to ToKubernetesVersion
73+
// +optional
74+
ControlPlaneUpgrades []UpgradeStep `json:"controlPlaneUpgrades,omitempty"`
75+
76+
// workersUpgrades is the list of version upgrade steps for the workers.
77+
// Each entry represents an intermediate version that must be applied in sequence.
78+
//
79+
// In case the upgrade plan for workers will be left to empty, the system will automatically
80+
// determine the minimal number of workers upgrade steps, thus minimizing impact on workloads and reducing
81+
// the overall upgrade time.
82+
//
83+
// If instead for any reason a custom upgrade path for workers is required, the following rules apply:
84+
// - each version must be:
85+
// - equal to FromControlPlaneKubernetesVersion or to one of the versions in the control plane upgrade plan.
86+
// - greater than FromWorkersKubernetesVersion (or with a different build number)
87+
// - greater than the previous version in the list (or with a different build number)
88+
// - less or equal to the ToKubernetesVersion (or with a different build number)
89+
// - in case of versions with the same major/minor/patch version but different build number, also the order
90+
// of those versions must be the same for control plane and worker upgrade plan.
91+
// - the last version in the plan must be equal to ToKubernetesVersion
92+
// - the upgrade plane must have all the intermediate version which workers must go through to avoid breaking rules
93+
// defining the max version skew between control plane and workers.
94+
// +optional
95+
WorkersUpgrades []UpgradeStep `json:"workersUpgrades,omitempty"`
96+
}
97+
98+
// UpgradeStep represents a single version upgrade step.
99+
type UpgradeStep struct {
100+
// version is the Kubernetes version for this upgrade step.
101+
// +required
102+
// +kubebuilder:validation:MinLength=1
103+
Version string `json:"version,omitempty"`
104+
}
105+
106+
// GenerateUpgradePlan is the hook that will be called to generate an upgrade plan
107+
// for a cluster. This hook allows runtime extensions to specify intermediate
108+
// Kubernetes versions that must be applied during an upgrade from the current
109+
// version to the target version.
110+
func GenerateUpgradePlan(*GenerateUpgradePlanRequest, *GenerateUpgradePlanResponse) {}
111+
112+
func init() {
113+
catalogBuilder.RegisterHook(GenerateUpgradePlan, &runtimecatalog.HookMeta{
114+
Tags: []string{"Chained Upgrade Hook"},
115+
Summary: "Cluster API Runtime will call this hook to generate an upgrade plan for a cluster",
116+
Description: "Cluster API Runtime will call this hook to generate an upgrade plan for a cluster. " +
117+
"Runtime Extension implementers can use this hook to specify intermediate Kubernetes versions " +
118+
"that must be applied during an upgrade from the current version to the target version.\n" +
119+
"\n" +
120+
"For example, if upgrading from v1.29.0 to v1.33.0 requires intermediate versions v1.30.0, " +
121+
"v1.31.0, and v1.32.0, the hook should return these intermediate versions in the response.\n" +
122+
"\n" +
123+
"Notes:\n" +
124+
"- The response may include separate upgrade paths for control plane and workers\n" +
125+
"- The upgrade plan for workers is optional; if missing the system will automatically\n\"" +
126+
" determine the minimal number of workers upgrade steps according to Kubernetes version skew rules.\n" +
127+
"- Each upgrade step represents a version that must be applied in sequence",
128+
})
129+
}

‎api/runtime/hooks/v1alpha1/zz_generated.deepcopy.go‎

Lines changed: 76 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)