DisaggregatedSet API

Generated API reference documentation for disaggregatedset.x-k8s.io/v1.

Resource Types

DisaggregatedSet

Appears in:

DisaggregatedSet is the Schema for the disaggregatedsets API

FieldDescription
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:

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).

FieldDescription
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.

scaling
RoleScaling

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.

FieldDescription
spec
DisaggregatedSetRoleScalerSpec

spec defines the desired state of DisaggregatedSetRoleScaler

status
DisaggregatedSetRoleScalerStatus

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.

FieldDescription
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.

FieldDescription
replicas
int32

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.

selector
string

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.

observedGeneration
int64

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.

FieldDescription
scaleUpDuringRollout
RolloutScalingPolicy

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.

scaleDownDuringRollout
RolloutScalingPolicy

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.

subRoleScaleDelaySeconds
int32

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.

FieldDescription
roles [Required]
[]DisaggregatedRoleSpec

Roles defines the list of roles (at least 1 required). Each role has a unique name and its own configuration.

slices
int32

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.

scalingPolicy
DisaggregatedSetScalingPolicy

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.

placementPolicy
PlacementPolicy

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.

FieldDescription
observedGeneration
int64

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:

  • "Available": the resource is fully functional
  • "Progressing": the resource is being created or updated

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.

FieldDescription
name [Required]
string

Name is unique within the parent role.

replicas
int32

Replicas counts groups (Static default: 1); omit it for External scaling.

scaling
RoleScaling

Scaling selects this pool's replica source.

maxSurge
k8s.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.

maxUnavailable
k8s.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.

FieldDescription
type
PlacementType

Type selects the placement guarantee. Defaults to None.

topology
string

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.

FieldDescription
mode
RoleScalingMode

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.

FieldDescription
name [Required]
string

Name is the parent role name.

desiredReplicas
int32

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.

minAvailableReplicas
int32

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.

replicas
int32

Replicas is the total number of replicas for this role.

readyReplicas
int32

ReadyReplicas is the number of ready replicas for this role. Sub-role readiness requires a coherent assignment across the whole group.

availableReplicas
int32

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.

updatedReplicas
int32

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.

FieldDescription
name [Required]
string

Name is the sub-role name, without the parent prefix.

desiredReplicas
int32

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.

minAvailableReplicas
int32

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.

replicas
int32

Replicas is the number of replica groups assigned to this sub-role.

readyReplicas
int32

ReadyReplicas counts Ready groups with a coherent whole-group assignment.

availableReplicas
int32

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.

updatedReplicas
int32

UpdatedReplicas counts groups belonging to the latest revision.

Feedback

Was this page helpful?