DistributedScaledObject API reference

The central controller owns distributed desired replicas and writes to registered member targets. Member connectivity, credentials and permissions are prerequisites. Rebalancing and failure behavior must be evaluated against workload placement requirements.

API details

Group: keda.kedify.io. Kind: DistributedScaledObject. Scope: Namespaced.

Defaults below are schema defaults only. “Not specified” does not imply a controller default of zero or false. Required fields are required within their containing object. Runtime behavior can impose additional conditions described in the capability guide.

v1alpha1 fields

Served: true; storage: true.

spec

Field	Type	Required	Schema default	Meaning and validation
`spec`	object	No	Not specified	DistributedScaledObjectSpec defines the desired state of DistributedScaledObject
`spec.memberClusters`	array	No	Not specified	MemberClusters is the list of member clusters where the ScaledObject should trigger scaling of the target workloads if empty, use all available member clusters
`spec.memberClusters[]`	object	No	Not specified	DistributedScaledObjectMemberCluster represents a member cluster where the DistributedScaledObject should be applied.
`spec.memberClusters[].name`	string	Yes	Not specified	Name is the name of the member cluster.
`spec.memberClusters[].targetNamespace`	string	No	Not specified	TargetNamespace is the namespace in the member cluster where the scaling should be applied. Defaults to the namespace of the owning distributed resource if not specified.
`spec.memberClusters[].weight`	integer	Yes	`1`	Weight is the weight of the member cluster for scaling distribution.
`spec.rebalancingPolicy`	object	Yes	`{"gracePeriod":"1m","maxRebalancePercentage":50}`	RebalancingPolicy controls how the controller should behave when clusters fail
`spec.rebalancingPolicy.gracePeriod`	string	Yes	`"1m"`	FailureGracePeriod is the duration to wait before rebalancing the replicas when a member cluster becomes unhealthy
`spec.rebalancingPolicy.maxRebalancePercentage`	integer	Yes	`50`	MaxRebalancePercentage is the maximum percentage of replicas that can be rebalanced at once
`spec.scaledObjectSpec`	object	Yes	Not specified	ScaledObjectSpec is the specification of the KEDA ScaledObject x-kubernetes-validations: [{“message”:“minReplicaCount must be less than or equal to maxReplicaCount”,“rule”:“!has(self.minReplicaCount) \|\| self.minReplicaCount <= (has(self.maxReplicaCount) ? self.maxReplicaCount : 100)”}]
`spec.scaledObjectSpec.advanced`	object	No	Not specified	AdvancedConfig specifies advance scaling options
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig`	object	No	Not specified	HorizontalPodAutoscalerConfig specifies horizontal scale config
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior`	object	No	Not specified	HorizontalPodAutoscalerBehavior configures the scaling behavior of the target in both Up and Down directions (scaleUp and scaleDown fields respectively).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown`	object	No	Not specified	scaleDown is scaling policy for scaling Down. If not set, the default value is to allow to scale down to minReplicas pods, with a 300 second stabilization window (i.e., the highest recommendation for the last 300sec is used).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.policies`	array	No	Not specified	policies is a list of potential scaling polices which can be used during scaling. If not set, use the default values: - For scale up: allow doubling the number of pods, or an absolute change of 4 pods in a 15s window. - For scale down: allow all pods to be removed in a 15s window.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.policies[]`	object	No	Not specified	HPAScalingPolicy is a single policy which must hold true for a specified past interval.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.policies[].periodSeconds`	integer	Yes	Not specified	periodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.policies[].type`	string	Yes	Not specified	type is used to specify the scaling policy.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.policies[].value`	integer	Yes	Not specified	value contains the amount of change which is permitted by the policy. It must be greater than zero
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.selectPolicy`	string	No	Not specified	selectPolicy is used to specify which policy should be used. If not set, the default value Max is used.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.stabilizationWindowSeconds`	integer	No	Not specified	stabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleDown.tolerance`	integer or string	No	Not specified	tolerance is the tolerance on the ratio between the current and desired metric value under which no updates are made to the desired number of replicas (e.g. 0.01 for 1%). Must be greater than or equal to zero. If not set, the default cluster-wide tolerance is applied (by default 10%). For example, if autoscaling is configured with a memory consumption target of 100Mi, and scale-down and scale-up tolerances of 5% and 1% respectively, scaling will be triggered when the actual consumption falls below 95Mi or exceeds 101Mi. This is an beta field and requires the HPAConfigurableTolerance feature gate to be enabled. pattern: ”^(\+\|-)?(([0-9]+(\.[0-9])?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9])?)\|(\.[0-9]+))))?$”
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp`	object	No	Not specified	scaleUp is scaling policy for scaling Up. If not set, the default value is the higher of: * increase no more than 4 pods per 60 seconds * double the number of pods per 60 seconds No stabilization is used.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.policies`	array	No	Not specified	policies is a list of potential scaling polices which can be used during scaling. If not set, use the default values: - For scale up: allow doubling the number of pods, or an absolute change of 4 pods in a 15s window. - For scale down: allow all pods to be removed in a 15s window.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.policies[]`	object	No	Not specified	HPAScalingPolicy is a single policy which must hold true for a specified past interval.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.policies[].periodSeconds`	integer	Yes	Not specified	periodSeconds specifies the window of time for which the policy should hold true. PeriodSeconds must be greater than zero and less than or equal to 1800 (30 min).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.policies[].type`	string	Yes	Not specified	type is used to specify the scaling policy.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.policies[].value`	integer	Yes	Not specified	value contains the amount of change which is permitted by the policy. It must be greater than zero
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.selectPolicy`	string	No	Not specified	selectPolicy is used to specify which policy should be used. If not set, the default value Max is used.
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.stabilizationWindowSeconds`	integer	No	Not specified	stabilizationWindowSeconds is the number of seconds for which past recommendations should be considered while scaling up or scaling down. StabilizationWindowSeconds must be greater than or equal to zero and less than or equal to 3600 (one hour). If not set, use the default values: - For scale up: 0 (i.e. no stabilization is done). - For scale down: 300 (i.e. the stabilization window is 300 seconds long).
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.behavior.scaleUp.tolerance`	integer or string	No	Not specified	tolerance is the tolerance on the ratio between the current and desired metric value under which no updates are made to the desired number of replicas (e.g. 0.01 for 1%). Must be greater than or equal to zero. If not set, the default cluster-wide tolerance is applied (by default 10%). For example, if autoscaling is configured with a memory consumption target of 100Mi, and scale-down and scale-up tolerances of 5% and 1% respectively, scaling will be triggered when the actual consumption falls below 95Mi or exceeds 101Mi. This is an beta field and requires the HPAConfigurableTolerance feature gate to be enabled. pattern: ”^(\+\|-)?(([0-9]+(\.[0-9])?)\|(\.[0-9]+))(([KMGTPE]i)\|[numkMGTPE]\|([eE](\+\|-)?(([0-9]+(\.[0-9])?)\|(\.[0-9]+))))?$”
`spec.scaledObjectSpec.advanced.horizontalPodAutoscalerConfig.name`	string	No	Not specified
`spec.scaledObjectSpec.advanced.restoreToOriginalReplicaCount`	boolean	No	Not specified
`spec.scaledObjectSpec.advanced.scalingModifiers`	object	No	Not specified	ScalingModifiers describes advanced scaling logic options like formula
`spec.scaledObjectSpec.advanced.scalingModifiers.activationTarget`	string	No	Not specified
`spec.scaledObjectSpec.advanced.scalingModifiers.formula`	string	No	Not specified
`spec.scaledObjectSpec.advanced.scalingModifiers.metricType`	string	No	Not specified	MetricTargetType specifies the type of metric being targeted, and should be either “Value”, “AverageValue”, or “Utilization” enum: [“AverageValue”,“Value”]
`spec.scaledObjectSpec.advanced.scalingModifiers.target`	string	No	Not specified
`spec.scaledObjectSpec.cooldownPeriod`	integer	No	Not specified	minimum: 0
`spec.scaledObjectSpec.fallback`	object	No	Not specified	Fallback is the spec for fallback options
`spec.scaledObjectSpec.fallback.behavior`	string	No	`"static"`	enum: [“static”,“currentReplicas”,“currentReplicasIfHigher”,“currentReplicasIfLower”,“scalingModifiers”]
`spec.scaledObjectSpec.fallback.failureThreshold`	integer	Yes	Not specified	minimum: 0
`spec.scaledObjectSpec.fallback.replicas`	integer	Yes	Not specified	minimum: 0
`spec.scaledObjectSpec.idleReplicaCount`	integer	No	Not specified	minimum: 0
`spec.scaledObjectSpec.initialCooldownPeriod`	integer	No	Not specified	minimum: 0
`spec.scaledObjectSpec.maxReplicaCount`	integer	No	Not specified	minimum: 1
`spec.scaledObjectSpec.minReplicaCount`	integer	No	Not specified	minimum: 0
`spec.scaledObjectSpec.pollingInterval`	integer	No	Not specified	minimum: 1
`spec.scaledObjectSpec.scaleTargetRef`	object	Yes	Not specified	ScaleTarget holds the reference to the scale target Object
`spec.scaledObjectSpec.scaleTargetRef.apiVersion`	string	No	Not specified
`spec.scaledObjectSpec.scaleTargetRef.envSourceContainerName`	string	No	Not specified
`spec.scaledObjectSpec.scaleTargetRef.kind`	string	No	Not specified
`spec.scaledObjectSpec.scaleTargetRef.name`	string	Yes	Not specified	minLength: 1
`spec.scaledObjectSpec.triggers`	array	Yes	Not specified	minItems: 1
`spec.scaledObjectSpec.triggers[]`	object	No	Not specified	ScaleTriggers reference the scaler that will be used
`spec.scaledObjectSpec.triggers[].authenticationRef`	object	No	Not specified	AuthenticationRef points to the TriggerAuthentication or ClusterTriggerAuthentication object that is used to authenticate the scaler with the environment
`spec.scaledObjectSpec.triggers[].authenticationRef.kind`	string	No	Not specified	Kind of the resource being referred to. Defaults to TriggerAuthentication. enum: [“TriggerAuthentication”,“ClusterTriggerAuthentication”]
`spec.scaledObjectSpec.triggers[].authenticationRef.name`	string	Yes	Not specified
`spec.scaledObjectSpec.triggers[].metadata`	object	Yes	Not specified
`spec.scaledObjectSpec.triggers[].metadata.*`	string	No	Not specified
`spec.scaledObjectSpec.triggers[].metricType`	string	No	Not specified	MetricTargetType specifies the type of metric being targeted, and should be either “Value”, “AverageValue”, or “Utilization”
`spec.scaledObjectSpec.triggers[].name`	string	No	Not specified
`spec.scaledObjectSpec.triggers[].type`	string	Yes	Not specified	minLength: 1
`spec.scaledObjectSpec.triggers[].useCachedMetrics`	boolean	No	Not specified
`spec.totalTargetReplicas`	integer	No	`0`	TotalTargetReplicas is the desired number of replicas

status

Field	Type	Required	Schema default	Meaning and validation
`status`	object	No	Not specified	DistributedScaledObjectStatus defines the observed state of DistributedScaledObject
`status.conditions`	array	No	Not specified
`status.conditions[]`	object	No	Not specified	Condition contains details for one aspect of the current state of this API Resource.
`status.conditions[].lastTransitionTime`	string	Yes	Not specified	lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
`status.conditions[].message`	string	Yes	Not specified	message is a human readable message indicating details about the transition. This may be an empty string. maxLength: 32768
`status.conditions[].observedGeneration`	integer	No	Not specified	observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. minimum: 0
`status.conditions[].reason`	string	Yes	Not specified	reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. minLength: 1; maxLength: 1024; pattern: ”^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$”
`status.conditions[].status`	string	Yes	Not specified	status of the condition, one of True, False, Unknown. enum: [“True”,“False”,“Unknown”]
`status.conditions[].type`	string	Yes	Not specified	type of condition in CamelCase or in foo.example.com/CamelCase. maxLength: 316; pattern: ”^([a-z0-9]([-a-z0-9][a-z0-9])?(\.[a-z0-9]([-a-z0-9][a-z0-9])?)/)?(([A-Za-z0-9][-A-Za-z0-9_.])?[A-Za-z0-9])$”
`status.memberClusterStatuses`	object	No	Not specified	MemberClusterStatuses represents the status of each member cluster
`status.memberClusterStatuses.*`	object	No	Not specified	DistributedScaledObjectMemberClusterStatus represents a member cluster status for DistributedScaledObject.
`status.memberClusterStatuses.*.currentReplicas`	integer	Yes	Not specified	CurrentReplicas is the current number of replicas in the member cluster
`status.memberClusterStatuses.*.description`	string	Yes	Not specified	Description provides additional information about the member cluster status
`status.memberClusterStatuses.*.desiredReplicas`	integer	Yes	Not specified	DesiredReplicas is the desired number of replicas in the member cluster
`status.memberClusterStatuses.*.excluded`	boolean	No	Not specified	Excluded indicates whether the member cluster is excluded from scaling for example, due to being unhealthy for longer than the grace period
`status.memberClusterStatuses.*.id`	string	Yes	Not specified	ID is the identification of the member cluster for multicluster-controller
`status.memberClusterStatuses.*.lastScalingProgressTime`	string	No	Not specified	LastScalingProgressTime is the last time the scaling made progress This is used to determine how long the member cluster has been making slow progress for rebalancing purposes
`status.memberClusterStatuses.*.lastStatusChangeTime`	string	No	Not specified	LastStatusChangeTime is the last time the status changed This is used to determine how long the member cluster has been unhealthy for rebalancing purposes
`status.memberClusterStatuses.*.provider`	string	No	Not specified	Provider is the cluster provider type (for example file, kubeconfig)
`status.memberClusterStatuses.*.state`	string	Yes	Not specified	State is the state of the member cluster (e.g., Ready, NotReady)
`status.membersHealthyCount`	integer	No	Not specified	MembersHealthyCount is the number of healthy member clusters
`status.membersTotalCount`	integer	No	Not specified	MembersTotalCount is the total number of member clusters
`status.print`	object	No	Not specified	Print is used for custom printing of DistributedScaledObject status
`status.print.membersCount`	string	No	Not specified	MembersCountStatus is the status of member clusters
`status.print.totalReplicas`	string	No	Not specified	TotalReplicas represents the status of replicas across member clusters
`status.selector`	string	Yes	Not specified	Selector is the selector for HPA
`status.totalCurrentReplicas`	integer	Yes	Not specified	TotalCurrentReplicas is the current number of replicas

Inspect the installed contract

kubectl get crd distributedscaledobjects.keda.kedify.io -o yaml
kubectl explain distributedscaledobject.spec --recursive

Compare served/storage versions and schema before applying configuration. Inspect the resource’s status and events after changing its owning source; schema acceptance alone does not prove successful reconciliation.

Use, verify and diagnose

DistributedScaledObject Specification

apiVersion: keda.kedify.io/v1alpha1
kind: DistributedScaledObject
metadata:
  name: nginx
spec:
  memberClusters: # optional list of member clusters to use, if omitted all registered member clusters will be used
    - name: member-cluster-1
      weight: 4 # weight determines the proportion of replicas to be allocated to this cluster
    - name: member-cluster-2
      weight: 6
  rebalancingPolicy: # optional parameters for rebalancing replicas across member clusters in case of outage or issues
    gracePeriod: 1m # when a member cluster becomes unreachable, wait for this duration before rebalancing replicas to other clusters
  scaledObjectSpec: # standard ScaledObject spec
    scaleTargetRef:
      kind: Deployment
      name: nginx
    minReplicaCount: 1
    maxReplicaCount: 10
    triggers:
      - type: kubernetes-resource
        metadata:
          resourceKind: ConfigMap
          resourceName: mock-metric
          key: metric-value
          targetValue: "5"

In this example, the DistributedScaledObject named nginx is configured to scale a Deployment named nginx across two member clusters. The memberClusters field whitelists the member clusters to be used along with their respective weights, which determine how many replicas should be allocated to each cluster. This section is optional; if omitted, all registered member clusters will be used with equal weights.

The workloads of type Deployment are expected to be present in relevant member clusters in a matching namespace as the DistributedScaledObject.

The rebalancingPolicy field allows you to specify how to handle situations where a member cluster becomes unreachable. In this case, after the specified gracePeriod, the replicas that were allocated to the unreachable cluster will be redistributed among the remaining healthy clusters. Once the unreachable cluster becomes healthy again, the replicas will be rebalanced back according to the defined weights.

Status of the DistributedScaledObject provides insights into the scaling state across member clusters:

status:
  memberClusterStatuses:
    member-cluster-1:
      currentReplicas: 2
      description: Cluster is healthy
      desiredReplicas: 2
      id: /etc/mc/kubeconfigs/member-cluster-1.kubeconfig+kedify-agent@member-cluster-1
      lastStatusChangeTime: "2025-11-05T16:46:39Z"
      state: Ready
    member-cluster-2:
      currentReplicas: 3
      description: Cluster is healthy
      desiredReplicas: 3
      id: /etc/mc/kubeconfigs/member-cluster-2.kubeconfig+kedify-agent@member-cluster-2
      lastStatusChangeTime: "2025-11-05T15:45:44Z"
      state: Ready
  membersHealthyCount: 2
  membersTotalCount: 2
  selector: kedify-agent-distributedscaledobject=nginx
  totalCurrentReplicas: 5