interface: add maxConcurrency for StageConfig in UpdateRun

apis/placement/v1beta1/stageupdate_types.go

@@ -19,6 +19,7 @@ package v1beta1
 import (
 	"k8s.io/apimachinery/pkg/api/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/intstr"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
 	"github.com/kubefleet-dev/kubefleet/apis"
@@ -275,6 +276,17 @@ type StageConfig struct {
 	// +kubebuilder:validation:Optional
 	SortingLabelKey *string `json:"sortingLabelKey,omitempty"`
 
+	// MaxConcurrency specifies the maximum number of clusters that can be updated concurrently within this stage.
+	// Value can be an absolute number (ex: 5) or a percentage of the total clusters in the stage (ex: 50%).
+	// Fractional results are rounded down. A minimum of 1 update is enforced.
+	// If not specified, all clusters in the stage are updated sequentially (effectively maxConcurrency = 1).
+	// Defaults to 1.
+	// +kubebuilder:default=1
+	// +kubebuilder:validation:XIntOrString
+	// +kubebuilder:validation:Pattern="^((100|[0-9]{1,2})%|[0-9]+)$"
+	// +kubebuilder:validation:Optional
+	MaxConcurrency *intstr.IntOrString `json:"maxConcurrency,omitempty"`
+
 	// The collection of tasks that each stage needs to complete successfully before moving to the next stage.
 	// Each task is executed in parallel and there cannot be more than one task of the same type.
 	// +kubebuilder:validation:MaxItems=2

config/crd/bases/placement.kubernetes-fleet.io_clusterstagedupdateruns.yaml

@@ -1871,6 +1871,19 @@ spec:
                               type: object
                           type: object
                           x-kubernetes-map-type: atomic
+                        maxConcurrency:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          default: 1
+                          description: |-
+                            MaxConcurrency specifies the maximum number of clusters that can be updated concurrently within this stage.
+                            Value can be an absolute number (ex: 5) or a percentage of the total clusters in the stage (ex: 50%).
+                            Absolute number is calculated from percentage by rounding up.
+                            If not specified, all clusters in the stage are updated sequentially (effectively maxConcurrency = 1).
+                            Defaults to 1.
+                          pattern: ^((100|[0-9]{1,2})%|[0-9]+)$
+                          x-kubernetes-int-or-string: true
                         name:
                           description: The name of the stage. This MUST be unique
                             within the same StagedUpdateStrategy.

config/crd/bases/placement.kubernetes-fleet.io_clusterstagedupdatestrategies.yaml

@@ -273,6 +273,19 @@ spec:
                           type: object
                       type: object
                       x-kubernetes-map-type: atomic
+                    maxConcurrency:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      default: 1
+                      description: |-
+                        MaxConcurrency specifies the maximum number of clusters that can be updated concurrently within this stage.
+                        Value can be an absolute number (ex: 5) or a percentage of the total clusters in the stage (ex: 50%).
+                        Absolute number is calculated from percentage by rounding up.
+                        If not specified, all clusters in the stage are updated sequentially (effectively maxConcurrency = 1).
+                        Defaults to 1.
+                      pattern: ^((100|[0-9]{1,2})%|[0-9]+)$
+                      x-kubernetes-int-or-string: true
                     name:
                       description: The name of the stage. This MUST be unique within
                         the same StagedUpdateStrategy.

config/crd/bases/placement.kubernetes-fleet.io_stagedupdateruns.yaml

@@ -790,6 +790,19 @@ spec:
                               type: object
                           type: object
                           x-kubernetes-map-type: atomic
+                        maxConcurrency:
+                          anyOf:
+                          - type: integer
+                          - type: string
+                          default: 1
+                          description: |-
+                            MaxConcurrency specifies the maximum number of clusters that can be updated concurrently within this stage.
+                            Value can be an absolute number (ex: 5) or a percentage of the total clusters in the stage (ex: 50%).
+                            Absolute number is calculated from percentage by rounding up.
+                            If not specified, all clusters in the stage are updated sequentially (effectively maxConcurrency = 1).
+                            Defaults to 1.
+                          pattern: ^((100|[0-9]{1,2})%|[0-9]+)$
+                          x-kubernetes-int-or-string: true
                         name:
                           description: The name of the stage. This MUST be unique
                             within the same StagedUpdateStrategy.

config/crd/bases/placement.kubernetes-fleet.io_stagedupdatestrategies.yaml

@@ -135,6 +135,19 @@ spec:
                           type: object
                       type: object
                       x-kubernetes-map-type: atomic
+                    maxConcurrency:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      default: 1
+                      description: |-
+                        MaxConcurrency specifies the maximum number of clusters that can be updated concurrently within this stage.
+                        Value can be an absolute number (ex: 5) or a percentage of the total clusters in the stage (ex: 50%).
+                        Absolute number is calculated from percentage by rounding up.
+                        If not specified, all clusters in the stage are updated sequentially (effectively maxConcurrency = 1).
+                        Defaults to 1.
+                      pattern: ^((100|[0-9]{1,2})%|[0-9]+)$
+                      x-kubernetes-int-or-string: true
                     name:
                       description: The name of the stage. This MUST be unique within
                         the same StagedUpdateStrategy.

pkg/controllers/updaterun/validation_integration_test.go

@@ -29,6 +29,7 @@ import (
 	"k8s.io/apimachinery/pkg/api/meta"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 	"k8s.io/apimachinery/pkg/types"
+	"k8s.io/apimachinery/pkg/util/intstr"
 
 	clusterv1beta1 "github.com/kubefleet-dev/kubefleet/apis/cluster/v1beta1"
 	placementv1beta1 "github.com/kubefleet-dev/kubefleet/apis/placement/v1beta1"
@@ -303,6 +304,10 @@ var _ = Describe("UpdateRun validation tests", func() {
 							"region": "no-exist",
 						},
 					},
+					MaxConcurrency: &intstr.IntOrString{
+						Type:   intstr.Int,
+						IntVal: 1,
+					},
 				})
 				Expect(k8sClient.Status().Update(ctx, updateRun)).Should(Succeed())
 
@@ -316,6 +321,10 @@ var _ = Describe("UpdateRun validation tests", func() {
 							"region": "no-exist",
 						},
 					},
+					MaxConcurrency: &intstr.IntOrString{
+						Type:   intstr.Int,
+						IntVal: 1,
+					},
 				})
 				validateClusterStagedUpdateRunStatus(ctx, updateRun, wantStatus, "the number of stages in the updateRun has changed")
 			})