LeaderWorkerSet API

spec defines the desired behavior of LeaderWorkerSet.

status represents the current status of LeaderWorkerSet.

schedulingPolicy defines scheduling for the leader PodGroup.

schedulingConstraints defines placement constraints for the leader PodGroup.

disruptionMode defines how leader pods may be disrupted.

resourceClaims lists dynamic resource claims shared by leader pods.

schedulingPolicy defines scheduling for a leader and its workers.

schedulingConstraints defines placement constraints for a replica.

disruptionMode defines how the leader and worker groups may be disrupted.

leader defines scheduling for the leader PodGroup.

worker defines scheduling for the worker PodGroup.

schedulingPolicy defines scheduling for all replicas.

schedulingConstraints defines placement constraints for all replicas.

disruptionMode defines how replica groups may be disrupted.

replica defines scheduling for each replica.

replicas is the number of leader-workers groups. A scale subresource is available to enable HPA. The selector for HPA will be that of the leader pod, and so practically HPA will be looking up the leader pod metrics. Note that the leader pod could aggregate metrics from the rest of the group and expose them as a summary custom metric representing the whole group. On scale down, the leader pod as well as the workers statefulset will be deleted. Default to 1.

leaderWorkerTemplate defines the template for leader/worker pods

rolloutStrategy defines the strategy that will be applied to update replicas when a revision is made to the leaderWorkerTemplate.

startupPolicy determines the startup policy for the worker statefulset.

networkConfig defines the network configuration of the group

scheduling defines Workload-Aware Scheduling for this LeaderWorkerSet. This field is immutable.

groupIdentity determines how group identities are assigned. Ordinal (default) manages leaders through a StatefulSet: groups are named -0..-N-1 and scale down always removes the highest ordinal. Hash manages leaders through a Deployment: group names are hash-suffixed, scale down prefers unscheduled and not-ready groups over healthy ones, and rollouts are paced by a group readiness gate on the leader pods. This field is immutable.

groupReplacementPolicy controls when a replacement group may start scheduling after a group is deleted, whether by the restart policy recreating a failed group, by a rolling update or by a scale down that races a scale up. PostTermination (default) admits a replacement only once a previously deleted group has been fully removed, so the new group lands on the capacity the old one released instead of preempting other workloads. This matches the StatefulSet semantics of groupIdentity Ordinal, where a leader pod cannot be recreated until its predecessor is gone, and is the only supported value in that mode. Immediate admits replacement groups as soon as the leader Deployment creates them, overlapping with the teardown of the old group. Only supported with groupIdentity Hash.

conditions track the condition of the leaderworkerset.

readyReplicas track the number of groups that are in ready state (updated or not).

updatedReplicas track the number of groups that have been updated (ready or not).

replicas track the total number of groups that have been created (updated or not, ready or not)

hpaPodSelector for pods that belong to the LeaderWorkerSet object, this is needed for HPA to know what pods belong to the LeaderWorkerSet object. Here we only select the leader pods.

observedGeneration is the most recent generation observed for this LeaderWorkerSet.

schedulingPolicy defines scheduling for the worker PodGroup.

schedulingConstraints defines placement constraints for the worker PodGroup.

disruptionMode defines how worker pods may be disrupted.

resourceClaims lists dynamic resource claims shared by worker pods.

leaderTemplate defines the pod template for leader pods.

workerTemplate defines the pod template for worker pods.

size is the number of pods to create. It is the total number of pods in each group. The minimum is 1 which represent the leader. When set to 1, the leader pod is created for each group as well as a 0-replica StatefulSet for the workers. Default to 1.

restartPolicy defines the restart policy when pod failures happen. The former named Default policy is deprecated, will be removed in the future, replace with None policy for the same behavior.

maxGroupRestarts bounds how many times the controller can recreate a group under RecreateGroupOnPodRestart or RecreateGroupAfterStart. Once exhausted, the controller terminates the group, retains Pod API objects that can still receive finalizers, and stops automatic group recreation. Setting leaderworkerset.sigs.k8s.io/recover=true on the retained leader Pod resets that revision/group's budget and allows recovery. Changing this value does not resume an exhausted group. It is opt-in: when unset (nil), group recreation is unlimited. Budget exhaustion handling requires Kubernetes 1.27 or later because it relies on deleted Pods reaching a terminal phase while finalizers retain their API objects.

subGroupPolicy describes the policy that will be applied when creating subgroups in each replica.

volumeClaimTemplates is a list of claims that pods are allowed to reference. Every claim in this list must have at least one matching (by name) volumeMount in one container in the template. A claim in this list takes precedence over any volumes in the template, with the same name.

persistentVolumeClaimRetentionPolicy describes the policy used for PVCs created from the VolumeClaimTemplates.

subdomainPolicy determines the policy that will be used when creating the headless service, defaults to shared

partition indicates the ordinal at which the lws should be partitioned for updates. During a rolling update, all the groups from ordinal Partition to Replicas-1 will be updated. The groups from 0 to Partition-1 will not be updated. This is helpful in incremental rollout strategies like canary deployments or interactive rollout strategies for multiple replicas like xPyD deployments. Once partition field and maxSurge field both set, the bursted replicas will keep remaining until the rolling update is completely done and the partition field is reset to 0. This is as expected to reduce the reconciling complexity. The default value is 0.

maxUnavailable is the maximum number of replicas that can be unavailable during the update. Value can be an absolute number (ex: 5) or a percentage of total replicas at the start of update (ex: 10%). Absolute number is calculated from percentage by rounding down. This can not be 0 if MaxSurge is 0. By default, a fixed value of 1 is used. Example: when this is set to 30%, the old replicas can be scaled down by 30% immediately when the rolling update starts. Once new replicas are ready, old replicas can be scaled down further, followed by scaling up the new replicas, ensuring that at least 70% of original number of replicas are available at all times during the update.

maxSurge is the maximum number of replicas that can be scheduled above the original number of replicas. Value can be an absolute number (ex: 5) or a percentage of total replicas at the start of the update (ex: 10%). Absolute number is calculated from percentage by rounding up. By default, a value of 0 is used. Example: when this is set to 30%, the new replicas can be scaled up by 30% immediately when the rolling update starts. Once old replicas have been deleted, new replicas can be scaled up further, ensuring that total number of replicas running at any time during the update is at most 130% of original replicas. When rolling update completes, replicas will fall back to the original replicas.

type defines the rollout strategy, it can only be “RollingUpdate” for now.

rollingUpdateConfiguration defines the parameters to be used when type is RollingUpdateStrategyType.

subGroupPolicyType defines what type of Subgroups to create. Defaults to LeaderWorker

subGroupSize is the number of pods per subgroup. This value is immutable, and must not be greater than LeaderWorkerSet.Spec.Size. Size must be divisible by subGroupSize in which case the subgroups will be of equal size. Or size - 1 is divisible by subGroupSize, in which case the leader is considered as the extra pod, and will be part of the first subgroup.