How kubernetes-sigs/lws works
This repository implements Kubernetes APIs and controllers for LeaderWorkerSet (LWS) and DisaggregatedSet (DS). Users submit workload resources; admission webhooks validate and default them, then controllers reconcile grouped pods or coordinate role-specific LWS resources, rollouts, scaling, and status. The README documents capabilities beyond the sampled excerpts, including topology-aware placement, gang scheduling, and failure handling; those feature branches are shown without implying unsampled call paths. Edges reflect excerpted relationships or README statements; unsampled implementation details are omitted.
Main entry points: leaderworkerset_types.go LeaderWorkerSet API · disaggregatedset_controller.go DS coordination · kubernetes_provider.go Scheduling providers · leaderworkerset_controller.go LWS reconciliation
Components 22
Workload APIs
- LeaderWorkerSet API
api/leaderworkerset/v1/leaderworkerset_types.go - DisaggregatedSet API
api/disaggregatedset/v1/disaggregatedset_types.go - Role scaler API
api/disaggregatedset/v1/disaggregatedsetrolescaler_types.go - Configuration API
api/config/v1alpha1/zz_generated.conversion.go
Admission
- LWS admission
pkg/webhooks/leaderworkerset_webhook.go - DS admission
pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go - Pod admission
pkg/webhooks/pod_webhook.go
LWS Runtime
- LWS reconciliation
pkg/controllers/leaderworkerset_controller.go - Pod lifecycle
pkg/controllers/pod_controller.go - Revision handling
pkg/controllers/leaderworkerset_hash.go - Scheduling providers
pkg/schedulerprovider/kubernetes_provider.go - TPU support
pkg/utils/accelerators/tpu.go
Disaggregated Runtime
- DS coordination
pkg/controllers/disaggregatedset/disaggregatedset_controller.go - Child LWS manager
pkg/controllers/disaggregatedset/lws_manager.go - Role scaling
pkg/controllers/disaggregatedset/scaler_manager.go - Rollout planner
pkg/controllers/disaggregatedset/planner.go
Go Client
- Typed clientset
client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go - LWS informer
client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go - LWS lister
client-go/listers/leaderworkerset/v1/leaderworkerset.go - Apply configuration
client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go
Other components
- Kubernetes user
- Kubernetes API
Connections 26
- Kubernetes user → LeaderWorkerSet API: submits workload
README.md - Kubernetes user → DisaggregatedSet API: submits roles
README.md - Kubernetes user → Role scaler API: sets replicas
- LeaderWorkerSet API → Kubernetes API: persists resource
README.md - DisaggregatedSet API → Kubernetes API: persists resource
README.md - LWS admission → Scheduling providers: validates scheduling
pkg/webhooks/leaderworkerset_webhook.go - DS admission → LWS admission: reuses validation
pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go - Pod admission → TPU support: injects TPU settings
pkg/webhooks/pod_webhook.go - Pod admission → Scheduling providers: uses provider
pkg/webhooks/pod_webhook.go - LWS reconciliation → Scheduling providers: selects scheduling
pkg/controllers/leaderworkerset_controller.go - LWS reconciliation → Revision handling: uses revisions
pkg/controllers/leaderworkerset_hash.go - Pod lifecycle → Scheduling providers: uses scheduling
pkg/controllers/pod_controller.go - Pod lifecycle → TPU support: uses accelerator helpers
pkg/controllers/pod_controller.go - DS coordination → Child LWS manager: reconciles child sets
pkg/controllers/disaggregatedset/disaggregatedset_controller.go - DS coordination → DisaggregatedSet API: reads and updates
pkg/controllers/disaggregatedset/disaggregatedset_controller.go - Child LWS manager → LeaderWorkerSet API: creates and scales
pkg/controllers/disaggregatedset/lws_manager.go - DS coordination → Rollout planner: plans rollouts
- Role scaling → Role scaler API: handles scaling resource
- Kubernetes user → Typed clientset: uses Go client
README.md - Typed clientset → LeaderWorkerSet API: operates on
client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go - LWS informer → Typed clientset: fetches resources
client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go - LWS informer → LWS lister: provides cached objects
client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go - Apply configuration → LeaderWorkerSet API: builds apply fields
client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go - LWS reconciliation → Kubernetes API: reconciles resources
README.md - Pod lifecycle → Kubernetes API: manages pod groups
README.md - DS coordination → Kubernetes API: coordinates role rollouts
README.md