DisaggregatedSet API
Resource Types
DisaggregatedSet
Appears in:
DisaggregatedSet is the Schema for the disaggregatedsets API
| Field | Description |
|---|---|
apiVersionstring | disaggregatedset.x-k8s.io/v1 |
kindstring | DisaggregatedSet |
spec [Required]DisaggregatedSetSpec | spec defines the desired state of DisaggregatedSet |
statusDisaggregatedSetStatus | status defines the observed state of DisaggregatedSet |
DisaggregatedRoleSpec
Appears in:
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. |
subRoles[]DisaggregatedSubRoleSpec | SubRoles partitions one LWS into pools sharing its templates. Child targets sum to parent replicas; omit parent scaling. Parent spec.replicas is ignored. |
scalingRoleScaling | Scaling configures how replicas are determined. Omit for inline Static scaling (default). When set to External, the DisaggregatedSet controller auto-creates a DisaggregatedSetRoleScaler and reads its spec.replicas. |
LeaderWorkerSetTemplateSpec [Required]LeaderWorkerSetTemplateSpec | (Members of LeaderWorkerSetTemplateSpec are embedded into this type.)LeaderWorkerSetTemplateSpec defines the LWS template for this role. Note: Spec.RolloutStrategy.Type must be RollingUpdate (or empty) and Spec.RolloutStrategy.RollingUpdateConfiguration.Partition must not be set. DisaggregatedSet handles rollouts across roles. |
DisaggregatedSetRoleScaler
Appears in:
DisaggregatedSetRoleScaler exposes the /scale subresource for a single role of a DisaggregatedSet. Instances are auto-created by the DisaggregatedSet controller for every role with scaling.mode: External and are named "-". External autoscalers (HPA, KEDA, or any /scale-aware controller) write spec.replicas; the DisaggregatedSet controller reads it and drives the role's LeaderWorkerSet.
| Field | Description |
|---|---|
specDisaggregatedSetRoleScalerSpec | spec defines the desired state of DisaggregatedSetRoleScaler |
statusDisaggregatedSetRoleScalerStatus | status defines the observed state of DisaggregatedSetRoleScaler |
DisaggregatedSetRoleScalerSpec
Appears in:
DisaggregatedSetRoleScalerSpec is the desired state written by an external autoscaler via the /scale subresource. The (DS, role) association is derived from the scaler's controller ownerReference and its role label.
| Field | Description |
|---|---|
replicas [Required]int32 | Replicas is the desired replica count for the role. The controller seeds this at scaler creation — 1 for a fresh role (0 would deadlock vanilla HPA in ScalingDisabled), or the LWS's current replica count for a Static→External flip so the role does not silently drain to zero. External autoscalers overwrite it on their first tick. Non-pointer with a default because kube-apiserver's CRD /scale handler extracts .spec.replicas at read time and errors ("the spec replicas field does not exist") when the JSONPath resolves to nothing. HPA reads /scale before its first write; a missing field would deadlock the loop. |
DisaggregatedSetRoleScalerStatus
Appears in:
DisaggregatedSetRoleScalerStatus is the observed state written back by the DisaggregatedSet controller.
| Field | Description |
|---|---|
replicasint32 | Replicas is the observed replica count for this role — LWS groups (== leader pods), aggregated across all revisions currently present. Read by HPA as the "current" count for its ratio math. |
selectorstring | Selector is a label selector (in string form) matching one pod per LWS group (the leader), across all revisions: disaggregatedset.x-k8s.io/name=,disaggregatedset.x-k8s.io/role=,leaderworkerset.sigs.k8s.io/worker-index=0 Leader-only so HPA's per-pod-metric averaging divides by group count (matching spec.replicas that HPA writes), keeping the ratio math consistent for leaderWorkerTemplate.size > 1. Aggregate across revisions so HPA observes the serving fleet during a rolling update. |
observedGenerationint64 | ObservedGeneration is the .metadata.generation the status reflects. |
conditions[]k8s.io/apimachinery/pkg/apis/meta/v1.Condition | Conditions expose scaler-level state (Ready). |
DisaggregatedSetScalingPolicy
Appears in:
DisaggregatedSetScalingPolicy configures how replica target changes interact with DisaggregatedSet reconciliation.
| Field | Description |
|---|---|
scaleUpDuringRolloutRolloutScalingPolicy | ScaleUpDuringRollout controls target growth while old revisions remain. Deferred preserves readiness-paced growth, without waiting for the entire rollout to finish. Immediate also tops up target replicas to desired minus replicas requested from all old revisions of the same role. Loading groups count, so readiness loss alone does not trigger extra growth. Old-revision retirement checks are unchanged. Renamed-role replacement limits still apply. |
scaleDownDuringRolloutRolloutScalingPolicy | ScaleDownDuringRollout controls demand-driven target replica reductions. Deferred waits until old revisions finish draining. Immediate considers reductions during the rollout, preferring safe old-revision drains. Both policies allow scale-up and old-revision drains within rollout bounds. Deferred uses max(initial old replicas, effective desired) + maxSurge as the surge ceiling. External roles retain at least the target's current Spec as effective desired while old replicas of that role remain. Immediate uses desired + maxSurge as the surge ceiling and may shrink target replicas when old revisions must remain. Under both policies, reductions of roles still present preserve max(0, effective desired - maxUnavailable) Ready replicas, or avoid worsening an existing shortfall. Renamed-role surplus recovery uses the same availability and scheduled-startup protection as other target reductions. These safeguards may delay reductions: Immediate does not mean instant deletion. |
subRoleScaleDelaySecondsint32 | SubRoleScaleDelaySeconds batches scale updates within a fixed window for LWS pools with multiple sub-roles and at least one External scaler. Defaults to 2 seconds (range 0 to 60); zero disables it. Scaling from zero and rollouts bypass the delay. Controller restarts reset the window. |
DisaggregatedSetSpec
Appears in:
DisaggregatedSetSpec defines the desired state of DisaggregatedSet.
The all-or-nothing replicas rule (either every role has replicas > 0, or every role has replicas == 0) applies only to non-External, unpartitioned roles. External targets come from scalers; sub-roles may independently scale to zero without pausing sibling routing pools.
| Field | Description |
|---|---|
roles [Required][]DisaggregatedRoleSpec | Roles defines the list of roles (at least 1 required). Each role has a unique name and its own configuration. |
slicesint32 | Slices is the number of independent copies of the whole role topology. Each slice is a complete set of all roles that rolls out independently. Changing Slices scales copies up or down and does not trigger a rollout. |
scalingPolicyDisaggregatedSetScalingPolicy | ScalingPolicy controls scale-up and scale-down during rolling updates. Omit it to use Deferred for both directions: readiness-paced growth and target reductions after old revisions drain. |
placementPolicyPlacementPolicy | PlacementPolicy controls how a slice's roles are co-located and how the DisaggregatedSet's slices are spread across topology domains. When set, the controller injects pod affinity and anti-affinity into the managed LeaderWorkerSet pod templates. Placement is applied when a LeaderWorkerSet is created, so changing it takes effect on the next rollout. |
DisaggregatedSetStatus
Appears in:
DisaggregatedSetStatus defines the observed state of DisaggregatedSet.
| Field | Description |
|---|---|
observedGenerationint64 | observedGeneration is the most recent generation observed for this DisaggregatedSet. |
roleStatuses[]RoleStatus | RoleStatuses lists current parent roles in spec order, with nested sub-role statuses. Parent counts include historical layouts and may exceed the visible child sum. Removed roles are omitted even while their groups drain. |
conditions[]k8s.io/apimachinery/pkg/apis/meta/v1.Condition | conditions represent the current state of the DisaggregatedSet resource. Each condition has a unique type and reflects the status of a specific aspect of the resource. Standard condition types include:
The status of each condition is one of True, False, or Unknown. |
DisaggregatedSubRoleSpec
Appears in:
DisaggregatedSubRoleSpec defines a scaling and routing pool sharing its parent's templates.
| Field | Description |
|---|---|
name [Required]string | Name is unique within the parent role. |
replicasint32 | Replicas counts groups (Static default: 1); omit it for External scaling. |
scalingRoleScaling | Scaling selects this pool's replica source. |
maxSurgek8s.io/apimachinery/pkg/util/intstr.IntOrString | MaxSurge overrides the parent's rollout surge budget for this sub-role. Accepts a non-negative integer or a percentage up to 100%, rounded up against this sub-role's replica target. Omitted values inherit the parent; with no parent rollout configuration, the default is 0. |
maxUnavailablek8s.io/apimachinery/pkg/util/intstr.IntOrString | MaxUnavailable overrides the parent's rollout unavailability budget for this sub-role. Accepts a non-negative integer or a percentage up to 100%, rounded down against this sub-role's replica target. Omitted values inherit the parent; with no parent rollout configuration, the default is 1. Zero is explicit. |
PlacementPolicy
Appears in:
PlacementPolicy controls topology placement of a DisaggregatedSet's slices.
| Field | Description |
|---|---|
typePlacementType | Type selects the placement guarantee. Defaults to None. |
topologystring | Topology is the node-label key that defines a domain, used as the affinity topologyKey. Required when Type is not None. |
PlacementType
(Alias of string)
Appears in:
PlacementType selects the DisaggregatedSet placement guarantee.
RoleScaling
Appears in:
RoleScaling configures how replicas are determined for a role. Sub-struct (not a bare enum) so future per-role scaling policies can be added without a v2 API bump.
| Field | Description |
|---|---|
modeRoleScalingMode | Mode controls the source of the replica count. Static (default) uses inline spec.replicas; External uses the auto-created scaler CR. |
RoleScalingMode
(Alias of string)
Appears in:
RoleScalingMode controls the source of the replica count for a role.
RoleStatus
Appears in:
RoleStatus defines the observed state of a single parent role.
| Field | Description |
|---|---|
name [Required]string | Name is the parent role name. |
desiredReplicasint32 | DesiredReplicas is the number of replicas the controller is driving this role toward, totalled across slices: its replicas, or the target of its DisaggregatedSetRoleScaler when its scaling mode is External. A partitioned role reports the sum of its sub-role targets. It is unset while any of those targets is unknown, for example before the scaler exists, so it is never mistaken for a requested zero. The Available condition is judged against it. |
minAvailableReplicasint32 | MinAvailableReplicas is the availability floor of this role, totalled across slices: in each slice, desiredReplicas minus its resolved maxUnavailable, and never below zero. A partitioned role reports the sum of its sub-role floors. It is unset while any of those targets is unknown. The MinimumReplicasAvailable condition is judged against it. During a Deferred rollout the controller may protect more Ready replicas than this. |
replicasint32 | Replicas is the total number of replicas for this role. |
readyReplicasint32 | ReadyReplicas is the number of ready replicas for this role. Sub-role readiness requires a coherent assignment across the whole group. |
availableReplicasint32 | AvailableReplicas counts the Ready replicas that can serve requests: those in a revision of a slice in which every role that revision requires has at least one Ready replica. A Ready Prefill cannot serve without a Ready Decode of the same revision and slice. It never exceeds ReadyReplicas. |
updatedReplicasint32 | UpdatedReplicas is the number of replicas updated to the latest revision. |
subRoleStatuses[]SubRoleStatus | SubRoleStatuses lists the current sub-roles in spec order. Removed sub-roles are omitted, but their groups remain in the parent counts while draining. Do not add child counts to their parent aggregate. |
RolloutScalingPolicy
(Alias of string)
Appears in:
RolloutScalingPolicy controls when a replica target change is applied during a rolling update. The scale-up and scale-down fields select it independently.
SubRoleStatus
Appears in:
SubRoleStatus defines the observed state of a sub-role within its parent.
| Field | Description |
|---|---|
name [Required]string | Name is the sub-role name, without the parent prefix. |
desiredReplicasint32 | DesiredReplicas is the number of replica groups the controller is driving this sub-role toward, totalled across slices: its replicas, or the target of its DisaggregatedSetRoleScaler when its scaling mode is External. It is unset while that target is unknown. |
minAvailableReplicasint32 | MinAvailableReplicas is the availability floor of this sub-role, totalled across slices: in each slice, desiredReplicas minus its resolved maxUnavailable, and never below zero. It is unset while desiredReplicas is unknown. The MinimumReplicasAvailable condition is judged against it. |
replicasint32 | Replicas is the number of replica groups assigned to this sub-role. |
readyReplicasint32 | ReadyReplicas counts Ready groups with a coherent whole-group assignment. |
availableReplicasint32 | AvailableReplicas counts the Ready groups that can serve requests: those in a revision of a slice in which every role that revision requires has at least one Ready group. It never exceeds ReadyReplicas. |
updatedReplicasint32 | UpdatedReplicas counts groups belonging to the latest revision. |
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.