# kubernetes-sigs/lws architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/lws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/lws
- Repository: https://github.com/kubernetes-sigs/lws

## Overview

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: [`api/leaderworkerset/v1/leaderworkerset_types.go`](https://github.com/kubernetes-sigs/lws/blob/main/api/leaderworkerset/v1/leaderworkerset_types.go) (LeaderWorkerSet API), [`pkg/controllers/disaggregatedset/disaggregatedset_controller.go`](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/disaggregatedset_controller.go) (DS coordination), [`pkg/schedulerprovider/kubernetes_provider.go`](https://github.com/kubernetes-sigs/lws/blob/main/pkg/schedulerprovider/kubernetes_provider.go) (Scheduling providers), [`pkg/controllers/leaderworkerset_controller.go`](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/leaderworkerset_controller.go) (LWS reconciliation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Workload APIs"]
  node_lws_api["LeaderWorkerSet API"]
  node_ds_api["DisaggregatedSet API"]
  node_scaler_api["Role scaler API"]
  node_config_api["Configuration API"]
end

subgraph group_admission["Admission"]
  node_lws_admit["LWS admission"]
  node_ds_admit["DS admission"]
  node_pod_admit["Pod admission<br/>[pod_webhook.go]"]
end

subgraph group_lws["LWS Runtime"]
  node_lws_reconcile["LWS reconciliation"]
  node_pod_reconcile["Pod lifecycle<br/>[pod_controller.go]"]
  node_revision_hash["Revision handling"]
  node_scheduler["Scheduling providers"]
  node_tpu["TPU support<br/>[tpu.go]"]
end

subgraph group_ds["Disaggregated Runtime"]
  node_ds_reconcile["DS coordination"]
  node_lws_manager["Child LWS manager<br/>[lws_manager.go]"]
  node_ds_scaler["Role scaling<br/>[scaler_manager.go]"]
  node_planner["Rollout planner<br/>[planner.go]"]
end

subgraph group_client["Go Client"]
  node_clientset["Typed clientset<br/>[leaderworkerset.go]"]
  node_informer["LWS informer<br/>[leaderworkerset.go]"]
  node_lister["LWS lister<br/>[leaderworkerset.go]"]
  node_apply["Apply configuration"]
end

node_user(("Kubernetes user"))
node_kube[("Kubernetes API")]

node_user -->|"submits workload"| node_lws_api
node_user -->|"submits roles"| node_ds_api
node_user -->|"sets replicas"| node_scaler_api
node_lws_api -->|"persists resource"| node_kube
node_ds_api -->|"persists resource"| node_kube
node_lws_admit -->|"validates scheduling"| node_scheduler
node_ds_admit -->|"reuses validation"| node_lws_admit
node_pod_admit -->|"injects TPU settings"| node_tpu
node_pod_admit -->|"uses provider"| node_scheduler
node_lws_reconcile -->|"selects scheduling"| node_scheduler
node_lws_reconcile -->|"uses revisions"| node_revision_hash
node_pod_reconcile -->|"uses scheduling"| node_scheduler
node_pod_reconcile -->|"uses accelerator helpers"| node_tpu
node_ds_reconcile -->|"reconciles child sets"| node_lws_manager
node_ds_reconcile -->|"reads and updates"| node_ds_api
node_lws_manager -->|"creates and scales"| node_lws_api
node_ds_reconcile -.->|"plans rollouts"| node_planner
node_ds_scaler -.->|"handles scaling resource"| node_scaler_api
node_user -->|"uses Go client"| node_clientset
node_clientset -->|"operates on"| node_lws_api
node_informer -->|"fetches resources"| node_clientset
node_informer -->|"provides cached objects"| node_lister
node_apply -->|"builds apply fields"| node_lws_api
node_lws_reconcile -->|"reconciles resources"| node_kube
node_pod_reconcile -->|"manages pod groups"| node_kube
node_ds_reconcile -->|"coordinates role rollouts"| node_kube

click node_lws_api "https://github.com/kubernetes-sigs/lws/blob/main/api/leaderworkerset/v1/leaderworkerset_types.go"
click node_ds_api "https://github.com/kubernetes-sigs/lws/blob/main/api/disaggregatedset/v1/disaggregatedset_types.go"
click node_scaler_api "https://github.com/kubernetes-sigs/lws/blob/main/api/disaggregatedset/v1/disaggregatedsetrolescaler_types.go"
click node_config_api "https://github.com/kubernetes-sigs/lws/blob/main/api/config/v1alpha1/zz_generated.conversion.go"
click node_lws_admit "https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/leaderworkerset_webhook.go"
click node_ds_admit "https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go"
click node_pod_admit "https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/pod_webhook.go"
click node_lws_reconcile "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/leaderworkerset_controller.go"
click node_pod_reconcile "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/pod_controller.go"
click node_revision_hash "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/leaderworkerset_hash.go"
click node_scheduler "https://github.com/kubernetes-sigs/lws/blob/main/pkg/schedulerprovider/kubernetes_provider.go"
click node_tpu "https://github.com/kubernetes-sigs/lws/blob/main/pkg/utils/accelerators/tpu.go"
click node_ds_reconcile "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/disaggregatedset_controller.go"
click node_lws_manager "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/lws_manager.go"
click node_ds_scaler "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/scaler_manager.go"
click node_planner "https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/planner.go"
click node_clientset "https://github.com/kubernetes-sigs/lws/blob/main/client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go"
click node_informer "https://github.com/kubernetes-sigs/lws/blob/main/client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go"
click node_lister "https://github.com/kubernetes-sigs/lws/blob/main/client-go/listers/leaderworkerset/v1/leaderworkerset.go"
click node_apply "https://github.com/kubernetes-sigs/lws/blob/main/client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lws_api,node_ds_api,node_scaler_api,node_config_api,node_user toneBlue
class node_lws_admit,node_ds_admit,node_pod_admit,node_kube toneAmber
class node_lws_reconcile,node_pod_reconcile,node_revision_hash,node_scheduler,node_tpu toneMint
class node_ds_reconcile,node_lws_manager,node_ds_scaler,node_planner toneRose
class node_clientset,node_informer,node_lister,node_apply toneIndigo
```

## Components

### Workload APIs

- [LeaderWorkerSet API](https://github.com/kubernetes-sigs/lws/blob/main/api/leaderworkerset/v1/leaderworkerset_types.go): `api/leaderworkerset/v1/leaderworkerset_types.go`
- [DisaggregatedSet API](https://github.com/kubernetes-sigs/lws/blob/main/api/disaggregatedset/v1/disaggregatedset_types.go): `api/disaggregatedset/v1/disaggregatedset_types.go`
- [Role scaler API](https://github.com/kubernetes-sigs/lws/blob/main/api/disaggregatedset/v1/disaggregatedsetrolescaler_types.go): `api/disaggregatedset/v1/disaggregatedsetrolescaler_types.go`
- [Configuration API](https://github.com/kubernetes-sigs/lws/blob/main/api/config/v1alpha1/zz_generated.conversion.go): `api/config/v1alpha1/zz_generated.conversion.go`

### Admission

- [LWS admission](https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/leaderworkerset_webhook.go): `pkg/webhooks/leaderworkerset_webhook.go`
- [DS admission](https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go): `pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go`
- [Pod admission](https://github.com/kubernetes-sigs/lws/blob/main/pkg/webhooks/pod_webhook.go): `pkg/webhooks/pod_webhook.go`

### LWS Runtime

- [LWS reconciliation](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/leaderworkerset_controller.go): `pkg/controllers/leaderworkerset_controller.go`
- [Pod lifecycle](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/pod_controller.go): `pkg/controllers/pod_controller.go`
- [Revision handling](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/leaderworkerset_hash.go): `pkg/controllers/leaderworkerset_hash.go`
- [Scheduling providers](https://github.com/kubernetes-sigs/lws/blob/main/pkg/schedulerprovider/kubernetes_provider.go): `pkg/schedulerprovider/kubernetes_provider.go`
- [TPU support](https://github.com/kubernetes-sigs/lws/blob/main/pkg/utils/accelerators/tpu.go): `pkg/utils/accelerators/tpu.go`

### Disaggregated Runtime

- [DS coordination](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/disaggregatedset_controller.go): `pkg/controllers/disaggregatedset/disaggregatedset_controller.go`
- [Child LWS manager](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/lws_manager.go): `pkg/controllers/disaggregatedset/lws_manager.go`
- [Role scaling](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/scaler_manager.go): `pkg/controllers/disaggregatedset/scaler_manager.go`
- [Rollout planner](https://github.com/kubernetes-sigs/lws/blob/main/pkg/controllers/disaggregatedset/planner.go): `pkg/controllers/disaggregatedset/planner.go`

### Go Client

- [Typed clientset](https://github.com/kubernetes-sigs/lws/blob/main/client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go): `client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go`
- [LWS informer](https://github.com/kubernetes-sigs/lws/blob/main/client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go): `client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go`
- [LWS lister](https://github.com/kubernetes-sigs/lws/blob/main/client-go/listers/leaderworkerset/v1/leaderworkerset.go): `client-go/listers/leaderworkerset/v1/leaderworkerset.go`
- [Apply configuration](https://github.com/kubernetes-sigs/lws/blob/main/client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go): `client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go`

### Other components

- **Kubernetes user**
- **Kubernetes API**

## Connections

- Kubernetes user → LeaderWorkerSet API: submits workload (evidence: `README.md`)
- Kubernetes user → DisaggregatedSet API: submits roles (evidence: `README.md`)
- Kubernetes user → Role scaler API: sets replicas
- LeaderWorkerSet API → Kubernetes API: persists resource (evidence: `README.md`)
- DisaggregatedSet API → Kubernetes API: persists resource (evidence: `README.md`)
- LWS admission → Scheduling providers: validates scheduling (evidence: `pkg/webhooks/leaderworkerset_webhook.go`)
- DS admission → LWS admission: reuses validation (evidence: `pkg/webhooks/disaggregatedset/disaggregatedset_webhook.go`)
- Pod admission → TPU support: injects TPU settings (evidence: `pkg/webhooks/pod_webhook.go`)
- Pod admission → Scheduling providers: uses provider (evidence: `pkg/webhooks/pod_webhook.go`)
- LWS reconciliation → Scheduling providers: selects scheduling (evidence: `pkg/controllers/leaderworkerset_controller.go`)
- LWS reconciliation → Revision handling: uses revisions (evidence: `pkg/controllers/leaderworkerset_hash.go`)
- Pod lifecycle → Scheduling providers: uses scheduling (evidence: `pkg/controllers/pod_controller.go`)
- Pod lifecycle → TPU support: uses accelerator helpers (evidence: `pkg/controllers/pod_controller.go`)
- DS coordination → Child LWS manager: reconciles child sets (evidence: `pkg/controllers/disaggregatedset/disaggregatedset_controller.go`)
- DS coordination → DisaggregatedSet API: reads and updates (evidence: `pkg/controllers/disaggregatedset/disaggregatedset_controller.go`)
- Child LWS manager → LeaderWorkerSet API: creates and scales (evidence: `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 (evidence: `README.md`)
- Typed clientset → LeaderWorkerSet API: operates on (evidence: `client-go/clientset/versioned/typed/leaderworkerset/v1/leaderworkerset.go`)
- LWS informer → Typed clientset: fetches resources (evidence: `client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go`)
- LWS informer → LWS lister: provides cached objects (evidence: `client-go/informers/externalversions/leaderworkerset/v1/leaderworkerset.go`)
- Apply configuration → LeaderWorkerSet API: builds apply fields (evidence: `client-go/applyconfiguration/leaderworkerset/v1/leaderworkersetspec.go`)
- LWS reconciliation → Kubernetes API: reconciles resources (evidence: `README.md`)
- Pod lifecycle → Kubernetes API: manages pod groups (evidence: `README.md`)
- DS coordination → Kubernetes API: coordinates role rollouts (evidence: `README.md`)
