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)
`disaggregatedset.x-k8s.io/initial-replicas`	Initial replica count captured when a DisaggregatedSet rollout starts.	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
`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)

If you want to use more environment variables, they are available in the labels or annotations but not listed in the Environment Variables section. We can obtain the index by using the Downward API to pass the Pod’s label as an environment variable to the container.

Reference on LeaderWorkerSet & DisaggregatedSet

LeaderWorkerSet API

Resource Types