Annotations reference

optimization

string

• Yes

Enable vertical scaling ("on"/"off").

If using the vertical configuration option, this field becomes required.

applyType

string

No

"immediate"

Allows configuring the autoscaler operating mode to apply the recommendations. Use immediate to apply recommendations as soon as the thresholds are passed.

• Note*: immediate mode can cause pod restarts. Use deferred to apply recommendations only on natural pod restarts.

considerAntiAffinity

boolean

• Yes

false

When true, workload autoscaler will respect pod anti-affinity rules on hostname or host port and, as a result, issue recommendations for these pods in a deferred manner. When false (default), recommendations for pods containing one of the constraints above will be applied immediately instead.

• If using the vertical.antiAffinity configuration option, this field becomes required.

startup

object

No

Configuration for handling workload startup behavior.

See Startup metrics.

period

duration

• Yes

"2m"

Duration to ignore resource usage metrics after workload startup. Useful for applications with high initial resource usage spikes. Set to 0s to disable startup metrics ignore period completely.

Valid values range from 0s (disabled) to 60m.

• If using the vertical.startup configuration option, this field becomes required.

required

bool

• Yes

When set to:

• true: The workload will require confidence metrics before optimization, even when directly enabled via annotations. This prevents immediate optimization of workloads with highly variable load patterns until sufficient historical data is available.

• false: When enabled via annotations, the workload will be optimized immediately, bypassing the confidence check.

  • *Note: **This option is not recommended.\
    *If using the vertical.confidence configuration option, at least one confidence field is required.

threshold

float

• Yes

0.9

Minimum confidence score required to apply recommendations (0.0-1.0). Higher values require more data points for recommendations.

• If using the vertical.confidence configuration option, at least one confidence field is required.

target

string

No

"p80"

Resource usage target:

• max - Use maximum observed usage
• p{0-99.9} - Use percentile (e.g., p80 for 80th percentile).

lookBackPeriod

duration

No

"24h"

Historical resource usage data window to consider for recommendations (3h-168h).

See Look-back Period.

applyThreshold

float

No

0.1

The relative difference required between current and recommended resource values to apply a change immediately:

• for upscaling, the difference is calculated relative to current resource requests;
• for downscaling, it's calculated relative to the new recommended value. For example, with a threshold of 0.1 (10%), an upscale from 100m to 120m CPU would be applied immediately (20% increase relative to current 100m), while an upscale from 110m to 120m would not be applied immediately (8% increase relative to new 120m).Value range: 0.01-2.5.

type

string

• Yes

"defaultAdaptive"

The type of threshold strategy to use:

• defaultAdaptive - Automatically adjusts thresholds based on workload size.
• percentage - Uses a fixed percentage threshold.
• customAdaptive - Allows custom configuration of the adaptive threshold formula. Recommended for power users only. It works in the same way as the Default Adaptive Threshold, but it allows tweaking the parameters of the adaptive threshold formula.The defaultAdaptive threshold option uses the following values: numerator = 0.5 denominator = 1 exponent = 1 (same effect as not used, i.e., no influence on the calculation)*Required when using applyThresholdStrategy

percentage

float

• Yes

The fixed percentage threshold to use. Value range: 0.01-2.5.

• Required when type is percentage

numerator

float

• Yes

0.5

Affects the vertical stretch of the threshold function. Lower values create smaller thresholds.

• Required when type is customAdaptive

denominator

float

• Yes

1

Affects threshold sensitivity for small workloads. Values close to 0 result in larger thresholds for small workloads. For example, when numerator is 1, exponent is 1 and denominator is 0 the threshold for 0.5 req. CPU will be 200%.

• Required when type is customAdaptive

exponent

float

• Yes

1

Controls how quickly the threshold decreases for larger workloads. Lower values prevent extremely small thresholds for large resources.

• Required when type is customAdaptive

overhead

float

No

0.1

Additional resource buffer when applying recommendations (0.0-2.5, e.g., 0.1 = 10%).

If a 10% buffer is configured, the issued recommendation will have +10% added to it, so that the workload can handle further increased resource demand.

limit

object

No

Configuration for container CPU limit scaling.

Default behaviour when not specified:

• If spec.containers[].resources.limits.cpu is not defined on the workload, no limit is set by the workload autoscaler.
• If spec.containers[].resources.limits.cpu is defined on the workload, it is removed by Workload Autoscaler.

type

string

*Yes

Type of CPU limit scaling to apply:

• noLimit - Remove the resource limit from the workload definition entirely.

• multiplier - Set limit as a multiple of requests using the following formula: resources.requests.cpu * {multiplier}. The behavior can be further controlled with optional flags onlyIfOriginalExist and onlyIfOriginalLower.

• keepLimits - Preserve the existing limits as defined in the workload manifest without modification.

*If using the vertical.cpu.limit configuration option, this field becomes required.

multiplier

float

*Yes

Value to multiply the requests by to set the limit. The calculation is: resources.requests.cpu * {multiplier}. The value must be greater than or equal to 1.

*Required when type is set to multiplier.

onlyIfOriginalExist

boolean

No

false

When set to true, CPU limits will only be set if the workload originally had CPU limits defined in its manifest. If the original workload has no CPU limits specified, no limits will be added.

This flag allows conditional limit management based on the original workload configuration.

Only applicable when the type is set to multiplier.

onlyIfOriginalLower

boolean

No

false

When set to true, CPU limits will only be updated if the original limits are lower than the calculated value (requests × multiplier). If the original limits are already higher than the calculated value, they remain unchanged.

This flag prevents reducing existing limits and ensures limits only increase when beneficial.

Only applicable when the type is set to multiplier.

optimization

string

no

This configuration option can be used to disable CPU management for workloads that benefit from memory management only. The workload will then use CPU requests/limits configured in the template.

• The only allowed option is off. If not set, the resource will inherit the workload management option as normal. Minimum required workload-autoscaler component version to use this feature is v0.23.1.

target

string

No

"max"

Resource usage target:

• max - Use maximum observed usage.
• p{0-99.9} - Use percentile (e.g., p80 for 80th percentile).

lookBackPeriod

duration

No

"24h"

Historical resource usage data window to consider for recommendations (3h-168h).

See Look-back Period.

applyThreshold

float

No

0.1

The relative difference required between current and recommended resource values to apply a change immediately:

• for upscaling, the difference is calculated relative to current resource requests;
• for downscaling, it's calculated relative to the new recommended value. For example, with a threshold of 0.1 (10%), an upscale from 100MiB to 120MiB of memory would be applied immediately (20% increase relative to current 100MiB), while an upscale from 110MiB to 120MiB would not be applied immediately (8% increase relative to new 120MiB). Value range: 0.01-2.5.

type

string

• Yes

"defaultAdaptive"

The type of threshold strategy to use:

• defaultAdaptive - Automatically adjusts thresholds based on workload size.
• percentage - Uses a fixed percentage threshold.
• customAdaptive - Allows custom configuration of the adaptive threshold formula. Recommended for power users only. It works in the same way as the Default Adaptive Threshold, but it allows tweaking the parameters of the adaptive threshold formula. The defaultAdaptive threshold option uses the following values: numerator = 0.5 denominator = 1 exponent = 1 (same effect as not used, i.e., no influence on the calculation)*Required when using applyThresholdStrategy

percentage

float

• Yes

The fixed percentage threshold to use. Value range: 0.01-2.5.

• Required when type is percentage

numerator

float

• Yes

0.5

Affects the vertical stretch of the threshold function. Lower values create smaller thresholds.

• Required when type is customAdaptive

denominator

float

• Yes

1

Affects threshold sensitivity for small workloads. Values close to 0 result in larger thresholds for small workloads. For example, when numerator is 1, exponent is 1 and denominator is 0 the threshold for 0.5 req. Memory will be 200%.

• Required when type is customAdaptive

exponent

float

• Yes

1

Controls how quickly the threshold decreases for larger workloads. Lower values prevent extremely small thresholds for large resources.

• Required when type is customAdaptive

overhead

float

No

0.1

Additional resource buffer when applying recommendations (0.0-2.5, e.g., 0.1 = 10%).

If a 10% buffer is configured, the issued recommendation will have +10% added to it so that the workload can handle further increased resource demand.

limit

object

No

Configuration for container memory limit scaling.

The default behavior when not specified:

• If spec.containers[].resources.limits.memory is not defined on the workload, no limit is set by Workload Autoscaler.

• If spec.containers[].resources.limits.memory is defined on the workload, Workload Autoscaler calculates the limit using the following formula: max(max(resources.requests.memory * 1.5, 128MiB), current.resources.limit) (it will only increase the limit, but never lower it, and will enforce a minimum of 128MiB).

type

string

*Yes

Type of limit scaling to apply:

• noLimit - Remove the resource limit from the workload definition entirely.

• multiplier - Set limit as a multiple of requests using the following formula: resources.requests.memory * {multiplier}.

• keepLimits - Preserve the existing limits as defined in the workload manifest without modification.

*If using the vertical.memory.limit configuration option, this field (type) becomes required.

multiplier

float

• Yes

Value to multiply the requests by to set the limit on the workload. The calculation is: max(resources.requests.memory * {multiplier}, 128MiB). The value must be greater than or equal to 1. Note that the recommended limit will never be less than 128MiB.

*Required when type is set to multiplier.

optimization

string

no

This configuration option can be used to disable memory management for workloads that benefit from CPU management only (e.g., Java workloads with a fixed heap size). The workload will then use memory requests/limits configured in the template.

• The only allowed option is off. If not set, the resource will inherit the workload management option as normal. Minimum required workload-autoscaler component version to use this feature is v0.23.1.

enabled

boolean

No

false

Enable predictive scaling for CPU resources. When enabled, the system forecasts CPU usage based on historical patterns and generates proactive recommendations. Requires vertical.optimization to be set to on.

Predictive scaling can be enabled on any workload via annotations, even if it is not currently eligible for scaling in this manner. The system will automatically activate predictive scaling once the workload becomes predictable and will seamlessly revert to standard scaling if the patterns are lost. This allows preemptive enablement without monitoring for eligibility.

See Predictive workload scaling for more information.

applyType

string

No

Default is taken from the vertical scaling policy controlling the workload.

Override application mode:

• immediate - Apply changes immediately
• deferred - Apply during natural restarts

applyType

string

• Yes

Default is taken from the vertical scaling policy controlling the workload.

Override application mode for memory-related events (OOM kills, pressure):

• immediate - Apply changes immediately
• deferred - Apply during natural restarts*If using the vertical.memoryEvent configuration option, this field becomes required.

type

string

• Yes

Controls how recommendation updates are rolled out:

• NoDisruption Ensures zero-downtime updates for single-replica workloads by temporarily scaling to two replicas during updates. This prevents service interruptions when applying new resource recommendations.
  
  *If using the rolloutBehavior configuration option, this field becomes required.
  
  Note: Requires workload-autoscaler component version v0.35.3 or higher. This setting is incompatible with the deferred apply type - if you change policy to deferred, you must remove the rolloutBehavior setting. This setting is applicable only to Deployment resources with a single replica, whose rollout strategy allows for downtime.

preferOneByOne

boolean

No

false

When true, enables a one-by-one pod restart strategy for immediate mode recommendations. This applies recommendations sequentially, waiting for each pod to become healthy before proceeding to the next. This reduces disruption for workloads without Pod Disruption Budgets or with aggressive rollout strategies.

Note: Requires workload-autoscaler component version v0.57.0 or higher. This setting applies only to immediate mode and has no effect when using the deferred apply type. Supported for replicated workloads (Deployments, StatefulSets, ReplicaSets, ArgoCD Rollouts).

See Pod restart strategy for more information.

optimization

string

Yes*

Enable horizontal scaling ("on"/"off").

• If using the horizontal configuration option, this field becomes required.

stabilizationWindow

duration

• Yes

"5m"

Cooldown period between scale-downs.

• If using the horizontal.scaleDown configuration option, this field becomes required.

type

string

No

Explicitly sets whether the custom workload should be treated as job-like or continuous:

• jobLike– Treats the workload as a job with sporadic execution patterns. For confidence, it requires only 3 runs per configured look-back period and keeps recommendations in the cluster even when no pods are running.
• continuous– Treats the workload as a long-running application. It requires more metric density for confidence.Note: This configuration is only applicable to custom workloads (those with the workloads.cast.ai/custom-workload label). It does not affect native Kubernetes Jobs or other standard workload types.