All Workload Autoscaler settings are available by adding annotations to the workload controller. When the workloads.cast.ai/configuration annotation is detected on a workload, it will be considered as configured by annotations. This allows for flexible configuration, combining annotations and scaling policies.
Changes to the settings via the API/UI are no longer permitted for workloads with annotations. The default or scaling policy value is used when a workload does not have an annotation for a specific setting.
Annotation values take precedence over what is defined in a scaling policy. This means that if a scaling policy is defined in the workload configuration under annotations, all of the individual configuration options defined under the annotation will override the respective policy values. Those that are not defined under the annotation will use system defaults or what is defined in the scaling policy.
Below is a configuration structure reference for setting up a workload to be controlled by annotations.
📘
Note
workloads.cast.ai/configuration has to be a valid YAML string. In cases where the annotation contains an invalid YAML string, the entire configuration will be ignored.
scalingPolicyName
If not set, the system assigns the workload to system default policies based on workload type: resiliency for StatefulSets and balanced for all other workloads.
Field
Type
Required
Default
Description
scalingPolicyName
string
No
System default (see below)
Specifies the scaling policy name to use. When set, this annotation allows the workload to be managed by both annotations and the specified scaling policy.
scalingPolicyName: custom-policy
Fallback for invalid policy names
If the scalingPolicyName value does not match any existing scaling policy, the workload falls back to system default policies:
StatefulSets: resiliency
All other workloads: balanced
When this fallback occurs, the Cast AI Console displays a warning status on the workload in the Optimization page, such as: Could not find scaling policy by name '<policy-name>'. To resolve this, update the annotation to reference a valid scaling policy name.
If using the vertical configuration option, this field becomes required.
vertical:
optimization: on
vertical.applyType
Field
Type
Required
Default
Description
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.
vertical:
applyType: immediate
vertical.antiAffinity
Field
Type
Required
Default
Description
antiAffinity
object
No
-
Configuration for handling pod anti-affinity scheduling constraints.
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.
Duration to ignore resource usage metrics after workload startup. Useful for applications with high initial resource usage spikes. Set to 0s to disable the startup metrics ignore period completely.
Valid values for the ignoring range from 2m to 60m. Set to 0s to disable the feature.
If using the vertical.startup configuration option, this field becomes required.
vertical:
startup:
period: 5m # Example: ignore first 5 minutes of metrics
vertical:
startup:
period: 0s # Disable startup metrics ignore period
vertical.confidence
Field
Type
Required
Default
Description
confidence
object
No
-
Configuration for recommendation confidence thresholds.
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.
vertical:
confidence:
required: true
vertical.confidence.threshold
Field
Type
Required
Default
Description
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.
vertical:
confidence:
threshold: 0.5
vertical.anomalyDetection
Field
Type
Required
Default
Description
anomalyDetection
object
No
-
Configuration for anomaly detection features, like CPU pressure-based stall detection.
The CPU stall percentage that triggers resource increases. When workloads can't get CPU time and stall exceeds this threshold, they'll be scaled up to reduce contention. Measured over a 5-minute window. Value range: 1.0–100.0.
The percentage of pods that must exceed the stall threshold before scaling triggers. This prevents scaling the entire workload when only a single pod or small subset is experiencing pressure. Value range: 1.0–100.0.
percentageOfOriginal requires the workload to have defined resource requests. Not supported for custom workloads or injected containers. If requests are not defined, the constraint is treated as having no limit set.
vertical.cpu.applyThreshold
🚧
Deprecation Notice
The applyThreshold configuration option is deprecated but still supported for backward compatibility. We strongly recommend migrating to the new applyThresholdStrategy configuration format for future compatibility and access to the latest features. See applyThresholdStrategy.
Field
Type
Required
Default
Description
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.
vertical:
cpu:
applyThreshold: 0.1
vertical.cpu.applyThresholdStrategy
🚧
Warning
applyThreshold and applyThresholdStrategy cannot be used simultaneously in a configuration as that will result in an error. applyThresholdStrategy is the latest and recommended configuration option.
Field
Type
Required
Default
Description
applyThresholdStrategy
object
No
-
Configuration for the strategy used to determine when recommendations should be applied. The strategy determines how the threshold percentage is calculated based on current resource requests.
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
vertical:
cpu:
applyThresholdStrategy:
type: defaultAdaptive # Using default adaptive threshold
vertical.cpu.applyThresholdStrategy.percentage
Field
Type
Required
Default
Description
percentage
float
Yes
The fixed percentage threshold to use. Value range: 0.01-2.5.
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%.
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.
vertical:
cpu:
overhead: 0.1
vertical.cpu.limit
Field
Type
Required
Default
Description
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.cpuis defined on the workload, it is removed by Workload Autoscaler.
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.
maintainRatio - Scale limits proportionally with recommended requests, preserving the original limit-to-request ratio from the workload manifest. If the original limit is 2× the request, the updated limit stays 2× the new recommended request. If no CPU limit exists on the workload, falls back to the default behavior (limits are removed).
*If using the vertical.cpu.limit configuration option, this field becomes required.
vertical:
cpu:
limit:
type: keepLimits
vertical.cpu.limit.multiplier
Field
Type
Required
Default
Description
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.
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.
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.
When both onlyIfOriginalExist and onlyIfOriginalLower are set to true, the behavior matches Memory's Automatic mode: limits are only set when the workload originally had limits defined AND only when those original limits are lower than the calculated value.
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.
Defines minimum and maximum memory bounds for the autoscaler. Two formats are supported:
constraints object (required when using percentageOfOriginal): specifies a typed constraint with type and value fields.
Legacy flat format (min/max as strings): still supported for constant values and not planned for deprecation.
Field
Type
Required
Default
Description
constraints
object
No
-
Container for min and max memory constraint objects. Required when using percentageOfOriginal.
vertical.memory.constraints.min
Field
Type
Required
Description
type
string
Yes
constant for an absolute value; percentageOfOriginal for a percentage of the workload's original request.
value
string | number
Yes
For constant: Kubernetes memory notation (e.g., "128Mi", "2Gi"). For percentageOfOriginal: a number (e.g., 90 = 90%). To control memory limits, see vertical.memory.limit.
vertical.memory.constraints.max
Same fields as vertical.memory.constraints.min. Note: This does not cap the memory limit directly. To control memory limits, see vertical.memory.limit.
percentageOfOriginal requires the workload to have defined resource requests. Not supported for custom workloads or injected containers. If requests are not defined, the constraint is treated as having no limit set.
vertical.memory.applyThreshold
🚧
Deprecation Notice
The applyThreshold configuration option is deprecated but still supported for backward compatibility. We strongly recommend migrating to the new applyThresholdStrategy configuration format for future compatibility and access to the latest features. See applyThresholdStrategy.
Field
Type
Required
Default
Description
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.
vertical:
memory:
applyThreshold: 0.1
vertical.memory.applyThresholdStrategy
🚧
Warning
applyThreshold and applyThresholdStrategy cannot be used simultaneously in a configuration as that will result in an error. applyThresholdStrategy is the latest and recommended configuration option.
Field
Type
Required
Default
Description
applyThresholdStrategy
object
No
-
Configuration for the strategy used to determine when recommendations should be applied. The strategy determines how the threshold percentage is calculated based on current resource requests.
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
vertical:
memory:
applyThresholdStrategy:
type: defaultAdaptive # Using default adaptive threshold
vertical.memory.applyThresholdStrategy.percentage
Field
Type
Required
Default
Description
percentage
float
Yes
The fixed percentage threshold to use. Value range: 0.01-2.5.
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%.
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.
vertical:
memory:
overhead: 0.1
vertical.memory.limit
Field
Type
Required
Default
Description
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.memoryis 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).
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.
maintainRatio - Scale limits proportionally with recommended requests, preserving the original limit-to-request ratio from the workload manifest. If the original limit is 2× the request, the updated limit stays 2× the new recommended request. If the workload has no existing memory limit, a default 1.5× multiplier is applied to the recommended request. The 128MiB minimum memory limit applies.
*If using the vertical.memory.limit configuration option, this field (type) becomes required.
vertical:
memory:
limit:
type: keepLimits
vertical.memory.limit.multiplier
Field
Type
Required
Default
Description
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.
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.
vertical:
memory:
optimization: off
vertical.excludedContainers
Specifies container names to exclude from vertical autoscaling optimization. Excluded containers retain their current resource settings and are not scaled by the Workload Autoscaler. Recommendations are still generated and visible in event logs and the workload detail view.
Field
Type
Required
Default
Description
excludedContainers
array
No
-
List of container names to exclude from optimization. Names must match exactly as defined in the pod specification. Regex or glob patterns are not supported.
Dynamically injected sidecar containers are already excluded from automatic optimization by default. Use excludedContainers for application containers or native sidecar containers explicitly defined in your pod spec that you want to prevent from being scaled.
vertical.predictiveScaling
Field
Type
Required
Default
Description
predictiveScaling
object
No
-
Predictive scaling configuration for CPU.
vertical:
predictiveScaling:
cpu:
enabled: true
vertical.predictiveScaling.cpu
Field
Type
Required
Default
Description
cpu
object
No
-
CPU-specific predictive scaling settings.
vertical:
predictiveScaling:
cpu:
enabled: true
vertical.predictiveScaling.cpu.enabled
Field
Type
Required
Default
Description
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.
Default is taken from the vertical scaling policy controlling the workload.
Override application mode:
immediate - Apply changes immediately
deferred - Apply during natural restarts
vertical:
downscaling:
applyType: immediate
vertical.memoryEvent
Field
Type
Required
Default
Description
memoryEvent
object
No
-
Memory event behavior override.
vertical:
memoryEvent:
applyType: immediate
vertical.memoryEvent.applyType
This configuration option is fully compatible with other applyType options and is meant to be used in combination with them. This allows for fine-grained control over both upscaling and downscaling. Here's how they interact:
If both configuration options are set to the same value (both immediate or both deferred), the behavior remains unchanged.
If vertical.downscaling.applyType is set to deferred and vertical.memoryEvent.applyType is set to immediate:
Upscaling operations will be applied immediately.
Downscaling operations will be deferred to natural pod restarts.
If vertical.downscaling.applyType is set to immediate and vertical.memoryEvent.applyType is set to deferred:
Upscaling operations will be deferred to natural pod restarts.
Downscaling operations will be applied immediately.
Field
Type
Required
Default
Description
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.
vertical:
memoryEvent:
applyType: immediate
vertical.containers
Configuration object that contains container-specific settings.
Field
Type
Required
Default
Description
containers
object
No
-
Container configuration mapping.
vertical:
containers:
vertical.containers.{container_name}
Configuration object that contains resource constraints for a specific container. Replace {container_name} with the name of your container.
Field
Type
Required
Default
Description
{container_name}
object
No
-
Container resource configuration object. Has to be the name of the container for which resources are being configured.
vertical:
containers:
{container_name}:
📘
Note
Container constraints apply to application containers (spec.containers[]) and native sidecar containers (spec.initContainers[] with restartPolicy: Always). Traditional initContainers that run during pod startup are not optimized by Workload Autoscaler.
vertical.containers.{container_name}.cpu
Container CPU constraints. Set minimum and maximum CPU limits for a specific container to define the workload autoscaler's scaling range. The percentageOfOriginal type is not yet supported at container level — only constant is. The constraints.min and constraints.max blocks are optional, but if specified, both type and value are required.
Field
Type
Required
Default
Description
constraints.min.type
string
Yes
-
Must be constant.
constraints.min.value
string
Yes
-
Kubernetes CPU notation (e.g., "10m", "1"). Min cannot be greater than max.
constraints.max.type
string
Yes
-
Must be constant.
constraints.max.value
string
Yes
-
Kubernetes CPU notation (e.g., "1000m", "2"). Recommendations won't exceed this value.
Container memory request constraints. Set minimum and maximum memory requests for a specific container to define the workload autoscaler's scaling range. These values control requests only; memory limits are managed separately via vertical.memory.limit. The percentageOfOriginal type is not yet supported at container level — only constant is. The constraints.min and constraints.max blocks are optional, but if specified, both type and value are required.
Field
Type
Required
Default
Description
constraints.min.type
string
Yes
-
Must be constant.
constraints.min.value
string
Yes
-
Kubernetes memory notation (e.g., "10Mi", "2Gi"). Recommendations will not go below this value.
constraints.max.type
string
Yes
-
Must be constant.
constraints.max.value
string
Yes
-
Kubernetes memory notation (e.g., "2048Mi", "4Gi"). Recommendations will not exceed this value.
Specifies container names to exclude from vertical autoscaling. Excluded containers retain their current resource settings and are not scaled by the Workload Autoscaler. Recommendations are still generated and visible, but not applied.
Field
Type
Required
Default
Description
excludedContainers
array
No
-
List of container names to exclude from optimization. Names must match exactly as defined in the pod specification.
Dynamically injected sidecar containers are already excluded from automatic optimization by default. Use excludedContainers for application containers or native sidecar containers explicitly defined in your pod spec that you want to prevent from being scaled.
rolloutBehavior
Field
Type
Required
Default
Description
rolloutBehavior
object
No
-
Configuration for controlling how recommendations are rolled out.
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.
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.
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).
Number of seconds to delay between pod restarts when applying recommendations. Accepted range: 0–3600.
rolloutBehavior:
delaySeconds: 120
horizontal
Field
Type
Required
Default
Description
horizontal
object
No
-
Horizontal autoscaling configuration.
When horizontal autoscaling is configured via annotations, Cast AI creates and manages a native Kubernetes HorizontalPodAutoscaler (autoscaling/v2) resource in the cluster. For concepts, supported workload types, and compatibility details, see Horizontal autoscaling.
Controls whether Cast AI actively manages horizontal scaling for this workload. Set to true for managed scaling or false for read-only mode (Cast AI monitors but does not scale).
*Required when the horizontal configuration block is present.
horizontal:
optimization: true
horizontal.useNative
Field
Type
Required
Default
Description
useNative
boolean
Yes*
false
Enables native Kubernetes HPA mode. When true, Cast AI creates and manages a native HorizontalPodAutoscaler resource in the cluster.
*Required to enable horizontal autoscaling.
horizontal:
useNative: true
horizontal.takeOwnership
Field
Type
Required
Default
Description
takeOwnership
boolean
No
false
When true, Cast AI takes ownership of an existing native HPA on the workload and replaces its configuration with Cast AI-managed settings. The existing HPA must not be managed by a third party such as KEDA. Only HPAs with CPU or memory utilization triggers are currently eligible for ownership.
horizontal:
takeOwnership: true
horizontal.minReplicas
Field
Type
Required
Default
Description
minReplicas
integer
Yes*
-
Minimum number of pod replicas. Must be greater than 0.
horizontal:
minReplicas: 2
horizontal.maxReplicas
Field
Type
Required
Default
Description
maxReplicas
integer
Yes*
-
Maximum number of pod replicas. Must be greater than 0 and ≥ minReplicas.
horizontal:
maxReplicas: 10
horizontal.metrics
Field
Type
Required
Default
Description
metrics
array
Yes*
-
Array of metric objects that define scaling triggers. At least one metric is required. Only resource metric type (CPU or memory) is supported via annotations.
The metric source type. Only resource is supported via annotations.
metrics[].resource.name
Field
Type
Required
Default
Description
name
string
Yes
-
The resource to monitor: cpu or memory.
metrics[].resource.target.type
Field
Type
Required
Default
Description
type
string
Yes
-
How the target value is interpreted. Accepted values: Utilization (percentage of resource requests averaged across all pods), AverageValue (average raw value across all pods), or Value (raw value).
metrics[].resource.target.averageUtilization
Field
Type
Required
Default
Description
averageUtilization
integer
Conditional
-
Target average utilization percentage across all pods. Required when target.type is Utilization.
The scaleUp and scaleDown objects share the same structure. The following fields apply to both.
behavior.direction.stabilizationWindowSeconds
Field
Type
Required
Default
Description
stabilizationWindowSeconds
integer
No
-
The number of seconds the autoscaler looks back at previous scaling recommendations before acting. This prevents rapid fluctuations in replica count. Valid range: 0–3600.
When multiple scaling policies are defined, determines which one to use. Max selects the policy allowing the most change, Min selects the most conservative, and Disabled prevents scaling in this direction entirely.
behavior.direction.tolerance
Field
Type
Required
Default
Description
tolerance
string
No
-
A non-negative quantity value. Scaling is triggered only when the metric deviation exceeds this tolerance. Must be ≥ 0.
behavior:
scaleUp:
tolerance: "0.1"
behavior.direction.policies
Field
Type
Required
Default
Description
policies
array
No
-
Array of scaling policy rules that control the rate of change.
policies[].type
Field
Type
Required
Default
Description
type
string
Yes
-
The unit for the scaling rate limit: Pods (absolute count) or Percent (percentage of current replicas).
policies[].value
Field
Type
Required
Default
Description
value
integer
Yes
-
Maximum amount of change allowed per period. Must be > 0.
policies[].periodSeconds
Field
Type
Required
Default
Description
periodSeconds
integer
Yes
-
Time window in seconds for the scaling rate limit. Valid range: 1–1800.
The minReplicas and maxReplicas fields work identically to the native HPA configuration documented above. The fields below are specific to legacy mode.
horizontal.optimization (legacy)
Field
Type
Required
Default
Description
optimization
string
Yes*
Enable legacy horizontal scaling. Set to "on" to enable or "off" to disable.
In native HPA mode, this field is a boolean (true/false) instead. See horizontal.optimization.
*Required when the horizontal configuration block is present.
horizontal:
optimization: on
horizontal.scaleDown.stabilizationWindow (legacy)
Field
Type
Required
Default
Description
stabilizationWindow
duration
*Yes
"5m"
Cooldown period between scale-downs. The duration needs to be parsable (e.g., "3m", "10m").
*Required if the horizontal.scaleDown block is present.
horizontal:
scaleDown:
stabilizationWindow: 5m
horizontal.shortAverage (legacy)
Field
Type
Required
Default
Description
shortAverage
duration
No
"3m"
Time period to average CPU metrics over before making scaling decisions. Valid range: 1–10 minutes. Not applicable to native HPA mode — this field is ignored when useNative: true.
horizontal:
shortAverage: 3m
containersGrouping
Field
Type
Required
Default
Description
containersGrouping
array
No
-
Rules for grouping dynamically generated containers with similar naming patterns.
containersGrouping:
- key: name
operator: contains
values: ["data-processor"]
into: data-processor
containersGrouping.[].key
Field
Type
Required
Default
Description
key
string
*Yes
-
The attribute used to match containers. Currently, only supports name which refers to the container name property.
containersGrouping.[].operator
Field
Type
Required
Default
Description
operator
string
*Yes
-
Defines how the key is evaluated against the values list. Currently, only supports contains.
containersGrouping.[].values
Field
Type
Required
Default
Description
values
array
*Yes
-
A list of string values used for matching against the key with the specified operator. Must contain at least one item.
containersGrouping.[].into
Field
Type
Required
Default
Description
into
string
*Yes
-
The target container name into which matching containers should be grouped.
*Required if the parent object is present in the configuration.
schedule
Field
Type
Required
Default
Description
schedule
object
No
-
Controls whether a custom workload is treated as job-like (sporadic execution) or continuous (always running) for optimization purposes.
schedule:
type: jobLike
schedule.type
Field
Type
Required
Default
Description
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.
schedule:
type: jobLike # For sporadic workloads like batch jobs
🚧
Important
The schedule.type configuration only applies to custom job-like workloads identified by the workloads.cast.ai/custom-workload label. Native Kubernetes Jobs with this label are always treated as job-like, and standard workload types (Deployments, StatefulSets, etc.) are always treated as continuous.
🚧
Legacy Annotation Support
For documentation on the legacy annotation format, which is now deprecated, see the Legacy Annotations Reference page .
Migration Guide
📘
Note
The annotations V2 structure cannot be combined with deprecated annotations V1. When the annotation workloads.cast.ai/configuration is detected, the workload is considered to be configured by using that annotation and all other annotations starting with workloads.cast.ai will be ignored.
To migrate from v1 to v2 annotations:
Remove all individual legacy workloads.cast.ai/* annotations
Add the new workloads.cast.ai/configuration annotation
Move all settings into the YAML structure under the new annotation
