LeaderWorkerSet API

Mon, 01 Jan 0001 00:00:00 +0000

Resource Types

LeaderWorkerSet

`LeaderWorkerSet`

Appears in:

LeaderWorkerSet is the Schema for the leaderworkersets API

Field	Description
`apiVersion` string	`leaderworkerset.x-k8s.io/v1`
`kind` string	`LeaderWorkerSet`
`spec` [Required] `LeaderWorkerSetSpec`	spec defines the desired behavior of LeaderWorkerSet.
`status` [Required] `LeaderWorkerSetStatus`	status represents the current status of LeaderWorkerSet.

`GroupIdentityType`

(Alias of string)

Appears in:

LeaderWorkerSetSpec

GroupIdentityType defines how group identities are assigned.

`GroupReplacementPolicyType`

(Alias of string)

Appears in:

LeaderWorkerSetSpec

GroupReplacementPolicyType defines when a replacement group may start scheduling.

`LeaderWorkerSetLeaderScheduling`

Appears in:

DisaggregatedSet API

Mon, 01 Jan 0001 00:00:00 +0000

Resource Types

DisaggregatedSet

`DisaggregatedSet`

Appears in:

DisaggregatedSet is the Schema for the disaggregatedsets API

Field	Description
`apiVersion` string	`disaggregatedset.x-k8s.io/v1`
`kind` string	`DisaggregatedSet`
`spec` [Required] `DisaggregatedSetSpec`	spec defines the desired state of DisaggregatedSet
`status` `DisaggregatedSetStatus`	status defines the observed state of DisaggregatedSet

`DisaggregatedRoleSpec`

Appears in:

DisaggregatedSetSpec

DisaggregatedRoleSpec defines the configuration for a disaggregated role. This structure embeds LeaderWorkerSetTemplateSpec from sigs.k8s.io/lws, with validation to reject unsupported fields (RolloutStrategy.Type must be RollingUpdate, RolloutStrategy.RollingUpdateConfiguration.Partition must not be set).

Field Description

name [Required]
string

Name is the unique identifier for this role.

Labels, Annotations and Environment Variables

Fri, 14 Mar 2025 00:00:00 +0000

Labels

Key	Description	Example	Applies to
`leaderworkerset.sigs.k8s.io/name`	The name of the LeaderWorkerSet object to which these resources belong.	leaderworkerset-multi-template	Pod, StatefulSet, Service
`leaderworkerset.sigs.k8s.io/template-revision-hash`	Hash used to track the controller revision that matches a LeaderWorkerSet object.	5c5fcdfb44	Pod, StatefulSet
`leaderworkerset.sigs.k8s.io/group-index`	The group to which it belongs.	0	Pod, StatefulSet (only worker)
`leaderworkerset.sigs.k8s.io/group-key`	Unique key identifying the group.	689ce1b5…b07	Pod, StatefulSet (only worker)
`leaderworkerset.sigs.k8s.io/worker-index`	The index or identity of the pod within the group.	0	Pod
`leaderworkerset.sigs.k8s.io/subgroup-index`	Tracks which subgroup the pod is part of.	0	Pod (only if SubGroup is set)
`leaderworkerset.sigs.k8s.io/subgroup-key`	Pods that are part of the same subgroup will have the same unique hash value.	92904e74…801	Pod (only if SubGroup is set)
`disaggregatedset.x-k8s.io/name`	The name of the DisaggregatedSet object to which these resources belong.	disaggregatedset-sample	LeaderWorkerSet, Service, Pod
`disaggregatedset.x-k8s.io/role`	The DisaggregatedSet role for the resource.	prefill	LeaderWorkerSet, Service, Pod
`disaggregatedset.x-k8s.io/slice`	Slice index for the resource within the DisaggregatedSet.	0	LeaderWorkerSet, Service, Pod
`disaggregatedset.x-k8s.io/revision`	Revision hash used to track a DisaggregatedSet rollout.	a1b2c3d4	LeaderWorkerSet, Service, Pod

Annotations

Key	Description	Example	Applies to
`leaderworkerset.sigs.k8s.io/size`	The total number of pods in each group.	4	Pod
`leaderworkerset.sigs.k8s.io/replicas`	Replicas Number of leader-workers groups.	3	StatefulSet (only leader)
`leaderworkerset.sigs.k8s.io/leader-name`	The name of the leader pod.	leaderworkerset-multi-template-0	Pod (only worker)
`leaderworkerset.sigs.k8s.io/exclusive-topology`	Specifies the topology for exclusive 1:1 scheduling.	cloud.google.com/gke-nodepool	LeaderWorkerSet, Pod (only if exclusive-topology is used)
`leaderworkerset.sigs.k8s.io/subdomainPolicy`	Determines what type of domain will be injected.	UniquePerReplica	Pod (only if leader and subdomainPolicy set to UniquePerReplica)
`leaderworkerset.sigs.k8s.io/subgroup-size`	The number of pods per subgroup.	2	Pod (only if SubGroup is set)
`leaderworkerset.sigs.k8s.io/subgroup-exclusive-topology`	Specifies the topology for exclusive 1:1 scheduling within a subgroup.	topologyKey	LeaderWorkerSet, Pod (only if SubGroup is set and subgroup-exclusive-topology is used)
`leaderworkerset.sigs.k8s.io/leader-requests-tpus`	Indicates if the leader pod requests TPU.	true	Pod (only if leader pod requests TPU)
`leaderworkerset.sigs.k8s.io/group-restart-counts`	Stores restart budget consumed by each revision and replica group.	`{"abc123/0":3}`	LeaderWorkerSet (only if maxGroupRestarts is set)
`leaderworkerset.sigs.k8s.io/group-restart-budget-exhausted`	Marks the retained leader after its group exhausts its restart budget.	true	Pod (only leader)
`leaderworkerset.sigs.k8s.io/recover`	Set to `true` on a retained leader to explicitly recover its exhausted group.	true	Pod (only an exhausted leader)
`disaggregatedset.x-k8s.io/initial-replicas`	Replica baseline used by the controller when the DisaggregatedSet revision becomes old.	2	LeaderWorkerSet

Environment Variables

Key	Description	Example	Applies to
`LWS_LEADER_ADDRESS`	The address of the leader via the headless service.	leaderworkerset-multi-template-0.leaderworkerset-multi-template.default	Pod
`LWS_GROUP_SIZE`	Tracks the size of the LWS group.	4	Pod
`LWS_WORKER_INDEX`	The index or identity of the pod within the group.	2	Pod
`DISAGGREGATEDSET_NAME`	The name of the parent DisaggregatedSet.	disaggregatedset-sample	Pod (only if managed by a DisaggregatedSet)
`DISAGGREGATEDSET_ROLE`	The role of the pod within the DisaggregatedSet.	prefill	Pod (only if managed by a DisaggregatedSet)
`DISAGGREGATEDSET_SLICE`	The slice index of the pod within the DisaggregatedSet.	0	Pod (only if managed by a DisaggregatedSet)
`DISAGGREGATEDSET_REVISION`	The revision hash used to identify the DisaggregatedSet rollout.	a1b2c3d4	Pod (only if managed by a DisaggregatedSet)
`TPU_WORKER_HOSTNAMES`	Hostnames of TPU workers only in the same subgroup.	test-sample-1-5.default,test-sample-1-6.default,test-sample-1-7.default,test-sample-1-8.default	Pod (only if TPU enabled)
`TPU_WORKER_ID`	ID of the TPU worker.	0	Pod (only if TPU enabled)
`TPU_NAME`	Name of the TPU.	test-sample-1	Pod (only if TPU enabled)

Other labels and annotations can be exposed to a container with the Downward API.

Reference on LeaderWorkerSet & DisaggregatedSet

LeaderWorkerSet API

Resource Types