Evictor Configuration

Reference for every user-configurable Evictor setting: Helm values, defaults, and where to configure them.

Evictor covers how bin-packing works and when Evictor evicts pods or restarts them. This page is the reference for every Evictor setting: what it does, its default value, and where you can configure it.

Configuration layers

Evictor settings live in three places:

  • Helm values: bootstrap defaults for the castai-evictor chart. Helm is the only configuration surface for self-managed installations.
  • Console: on clusters managed by Cast AI, the Bin-packing page under Automation configures Evictor interactively.
  • Terraform: the Cast AI Terraform provider's castai_evictor and castai_evictor_advanced_config resources configure the same platform-side policy declaratively.

Cast AI syncs console and Terraform settings to the cluster and overrides the matching Helm values.

Internally, Cast AI writes the synced configuration to a cluster-scoped EvictorConfig resource, which the Evictor applies without a restart.

📘

Managed mode overrides Helm values

When Cast AI manages the installation, it syncs your console and Terraform settings on an ongoing basis. This overwrites manual changes to the matching settings. See Managed by Cast AI vs. self-managed configuration.

Settings reference

Each section describes one setting. The table shows the Helm value, its type and default, and the matching console control where one exists. A dash in the Console column means there is no dedicated console control for the setting. Configure such settings through Helm; on installations managed by Cast AI, the platform may derive or override their values.

Each YAML snippet shows the complete values path, so you can paste it into your values file and apply it as-is. The snippets show the standard-cluster form. Where the settings live in the values tree depends on how you install Cast AI:

Settings go under the castai-evictor key inside the autoscaler section of the umbrella chart's values:

autoscaler:
  castai-evictor:
    dryRun: false

Operating modes

dryRun

Runs Evictor in simulation mode. Evictor logs every decision but evicts no pods, cordons no nodes, applies no taints, and deletes no Karpenter NodeClaims. Use dry run to preview bin-packing actions before allowing evictions.

Helm valueTypeDefaultConsole
dryRunbooleanfalse-
autoscaler:
  castai-evictor:
    dryRun: false

aggressiveMode

Targets every eligible pod and node regardless of replica count, including single-replica deployments and Jobs. See Aggressive mode for what the mode does and does not target.

Helm valueTypeDefaultConsole
aggressiveModebooleanfalseAggressive mode
autoscaler:
  castai-evictor:
    aggressiveMode: false

scopedMode

Restricts Evictor to nodes created by Cast AI. Evictor considers only nodes carrying the provisioner.cast.ai/managed-by=cast.ai label. See Scoped mode.

Helm valueTypeDefaultConsole
scopedModebooleanfalseScoped mode
autoscaler:
  castai-evictor:
    scopedMode: false

Cycle and targeting

nodeGracePeriodMinutes

The number of minutes a node must exist before Evictor considers it for eviction. The default of 5 suits most workloads. Increase it when pods need longer to become ready, for example JVM services or workloads that pull large images.

Helm valueTypeDefaultConsole
nodeGracePeriodMinutesinteger5Node grace period
autoscaler:
  castai-evictor:
    nodeGracePeriodMinutes: 5
⚠️

Default grace period may be too short for production

The default value of 5 minutes means Evictor can begin targeting a node 5 minutes after node creation. For most production workloads this is sufficient. If your applications have slow startup times, pods may not be fully ready by then. This applies to JVM-based services, large model servers, and workloads that pull large container images.

If Evictor disrupts workloads shortly after node provisioning, increase nodeGracePeriodMinutes to a value that accounts for your worst-case pod startup time.

cycleInterval

How often Evictor starts a new evaluation and drain cycle, for example 1m. Evictor clamps the value to a minimum of 1s. Shorter intervals optimize more frequently at the cost of higher Kubernetes API load. See Performance tuning for large clusters.

Helm valueTypeDefaultConsole
cycleIntervalduration1mCycle interval
autoscaler:
  castai-evictor:
    cycleInterval: 1m

maxNodesToEvictPerCycle

The upper bound on nodes drained in a single cycle. Higher values increase throughput but generate more parallel Kubernetes API calls.

Helm valueTypeDefaultConsole
maxNodesToEvictPerCycleinteger20Max nodes per cycle
autoscaler:
  castai-evictor:
    maxNodesToEvictPerCycle: 20

minNodesToEvictPerCycle

The lower bound on nodes considered per eviction cycle.

Helm valueTypeDefaultConsole
minNodesToEvictPerCycleinteger5-
autoscaler:
  castai-evictor:
    minNodesToEvictPerCycle: 5

targetNodePercentage

The percentage of eligible nodes to consider per cycle, applied after the per-cycle minimum and maximum bounds.

Helm valueTypeDefaultConsole
targetNodePercentageinteger10-
autoscaler:
  castai-evictor:
    targetNodePercentage: 10

Performance tuning for large clusters

The cycle and targeting defaults suit small and medium clusters. On clusters with many nodes, the defaults can cause kube-apiserver pressure or overlapping drain cycles. Adjust maxNodesToEvictPerCycle and cycleInterval together:

Cluster sizemaxNodesToEvictPerCyclecycleInterval
< 200 nodes20 (default)1m (default)
200-500 nodes105m
500+ nodes510m

Higher node limits generate many simultaneous drain operations that each hold their own context, which can saturate the kube-apiserver. Short cycle intervals start a new cycle before the previous one finishes. Evictor cancels the unfinished cycle's context to make way for the next. See Evictor drain cycles stall with context canceled errors for the related troubleshooting.

Drain behavior

drainTimeout

The maximum time Evictor waits for a node to fully drain before giving up, for example 10m.

Helm valueTypeDefaultConsole
drainTimeoutduration10m-
autoscaler:
  castai-evictor:
    drainTimeout: 10m

drainRollbackTimeout

How long Evictor waits before rolling back the cordon when a drain attempt fails. A drain can stall, for example because a pod is stuck in termination or a PDB blocks the last replica. Evictor uncordons the node after this interval, and the node returns to normal operation instead of staying blocked. Evictor clamps the value to a minimum of 30s.

Helm valueTypeDefaultConsole
drainRollbackTimeoutduration1m-
autoscaler:
  castai-evictor:
    drainRollbackTimeout: 1m

podEvictionFailureBackOff

The wait time before Evictor retries after a pod eviction request fails, for example 5s. Evictor clamps the value to a minimum of 5s.

Helm valueTypeDefaultConsole
podEvictionFailureBackOffduration5s-
autoscaler:
  castai-evictor:
    podEvictionFailureBackOff: 5s

Safety

ignorePodDisruptionBudgets

When enabled, Evictor attempts to evict pods even when the eviction would violate the pod's PodDisruptionBudget. Use with caution: this can break the availability guarantees that PDBs provide for production workloads.

Helm valueTypeDefaultConsole
ignorePodDisruptionBudgetsbooleanfalseIgnore Pod Disruption Budgets
autoscaler:
  castai-evictor:
    ignorePodDisruptionBudgets: false

Events and integrations

emitNodeRelatedPodEvents

Emits Kubernetes events on pods that Evictor evicts as part of a node drain. On installations managed by Cast AI, the platform derives this setting from the Node deletion policy rather than the Helm value.

Helm valueTypeDefaultConsole
emitNodeRelatedPodEventsbooleanfalse-
autoscaler:
  castai-evictor:
    emitNodeRelatedPodEvents: false

liveMigration.enabled

Lets Evictor use Container Live Migration to move workloads that prevent Evictor from draining a node. This applies only to workloads eligible for migration. When disabled, Evictor uses traditional eviction for those workloads.

Helm valueTypeDefaultConsole
liveMigration.enabledbooleantrue-
autoscaler:
  castai-evictor:
    liveMigration:
      enabled: true

woop.enabled

Lets Evictor take Workload Autoscaler recommendations into account during scheduling simulations. When a recommendation changes a pod's requests, Evictor checks that it can still reschedule the pod with the new requests. Evictor detects both features automatically when installed. Disable this only to opt out while keeping the components installed.

Helm valueTypeDefaultConsole
woop.enabledbooleantrue-
autoscaler:
  castai-evictor:
    woop:
      enabled: true

podMutations.enabled

Lets Evictor apply PodMutation resources to pod specs in memory during scheduling simulations. Consolidation decisions then reflect mutations that predate the pod. Requires the castai-pod-mutator component in the cluster.

Helm valueTypeDefaultConsole
podMutations.enabledbooleantrue-
autoscaler:
  castai-evictor:
    podMutations:
      enabled: true

Post-eviction

softTainting.enabled

Requires Evictor Helm chart version castai-evictor-0.33.193 or later.

Changes what happens after Evictor drains a node. Instead of leaving the node cordoned, Evictor applies a PreferNoSchedule taint. The node can then still absorb pods if the cluster needs capacity before deletion. See Soft tainting for the full behavior.

Helm valueTypeDefaultConsole
softTainting.enabledbooleanfalse-
autoscaler:
  castai-evictor:
    softTainting:
      enabled: false

karpenterNodeCleanup.enabled

Requires Evictor Helm chart version castai-evictor-0.33.196 or later.

For clusters running open-source Karpenter without Karpenter Enterprise suite. Evictor deletes the Karpenter NodeClaim of a drained node, so Karpenter's termination controller cleans up the instance sooner. With Karpenter Enterprise suite, Kentroller handles node deletion, so you do not need this setting. See Clean up Karpenter nodes.

Helm valueTypeDefaultConsole
karpenterNodeCleanup.enabledbooleanfalse-
autoscaler:
  castai-evictor:
    karpenterNodeCleanup:
      enabled: false

Detection

windows

Enables eviction of pods and nodes running Windows workloads. On installations managed by Cast AI, the platform derives this setting from the Windows autoscaling configuration rather than the Helm value.

Helm valueTypeDefaultConsole
windowsbooleanfalse-
autoscaler:
  castai-evictor:
    windows: false

arm64Supported

Indicates that arm64 nodes are present, so scheduling simulations include them as valid bin-packing targets.

Helm valueTypeDefaultConsole
arm64Supportedbooleantrue-
autoscaler:
  castai-evictor:
    arm64Supported: true

Component management

evictorEnabled

The top-level switch for the Evictor. When false, Evictor performs no evictions or node drains regardless of other settings.

Helm valueTypeDefaultConsole
evictorEnabledbooleanfalseBin-packing page toggle
autoscaler:
  castai-evictor:
    evictorEnabled: false

managedByCASTAI

Controls whether Cast AI manages the Evictor installation. When true, Cast AI syncs console settings and upgrades. When false, the installation is self-managed and your configuration persists. See Managed by Cast AI vs. self-managed configuration.

Helm valueTypeDefaultConsole
managedByCASTAIbooleantrue-
autoscaler:
  castai-evictor:
    managedByCASTAI: true

customConfig

Advanced eviction rules that target specific pods or nodes. Provide a list of rules, or an object with an evictionRules key. Advanced configuration covers the rules schema, selectors, and examples.

Helm valueTypeDefaultConsole
customConfigobject or list{}Advanced configurations
autoscaler:
  castai-evictor:
    customConfig:
      evictionRules:
        - nodeSelector:
            labelSelector:
              matchLabels:
                node-type: workflow-runner
          settings:
            removalDisabled:
              enabled: true

Applying configuration

Helm

The following values block lists every setting on this page with its default. It is a reference, not a template to apply as-is: set only the values you intend to change. In particular, applying evictorEnabled: false disables bin-packing, and applying managedByCASTAI: true switches a self-managed installation to managed mode.

autoscaler:
  castai-evictor:
    evictorEnabled: false
    dryRun: false
    aggressiveMode: false
    scopedMode: false
    nodeGracePeriodMinutes: 5
    cycleInterval: 1m
    maxNodesToEvictPerCycle: 20
    minNodesToEvictPerCycle: 5
    targetNodePercentage: 10
    drainTimeout: 10m
    drainRollbackTimeout: 1m
    podEvictionFailureBackOff: 5s
    ignorePodDisruptionBudgets: false
    emitNodeRelatedPodEvents: false
    softTainting:
      enabled: false
    karpenterNodeCleanup:
      enabled: false
    liveMigration:
      enabled: true
    woop:
      enabled: true
    podMutations:
      enabled: true
    windows: false
    arm64Supported: true
    managedByCASTAI: true

Apply one or more values with helm upgrade:

📘

The Helm commands on this page use the umbrella chart (castai-helm/castai). To confirm your install method, list the Helm releases in the castai-agent namespace:

helm list -n castai-agent

A single release named castai means the umbrella chart, and the commands work as written. Separate releases, such as castai-workload-autoscaler, mean individual charts: replace the release name and chart reference with the component-specific ones and remove the autoscaler.<component>. value prefix. To upgrade all components at once while preserving your configuration, use castctl.

📘

Configuration-only changes

These commands upgrade all components in the umbrella chart, not just Evictor. To change configuration without upgrading component versions, pin the current chart version:

helm list -n castai-agent

The CHART column shows the running version, for example castai-1.22.1. Add --version <that-version> to the upgrade command.

helm upgrade castai castai-helm/castai -n castai-agent \
  --reset-then-reuse-values \
  --set autoscaler.castai-evictor.dryRun=true

Console

If Cast AI manages your cluster, configure Evictor on the Bin-packing page under Automation in the Cast AI console:

  1. Enable bin-packing with the toggle next to the page title.
  2. Set the aggressive and scoped modes and the PDB override. Then set the node grace period, the per-cycle node limit, and the cycle interval.
  3. Select Save changes to apply the settings to the cluster.

Eviction rules live under Advanced configurations, in a builder or as YAML:

  1. Select Add rule.
  2. Pair a rule type with a workload match: a namespace, a workload kind, a minimum replica count, and labels.
  3. Select Save changes to apply the rules to the cluster.
Cast AI console Bin-packing page with optimization profiles, the six bin-packing settings, and an advanced configuration rule in the builder

The Bin-packing page with an advanced configuration rule started in the builder.

Cast AI syncs console settings to the cluster and overrides the matching Helm values.

Terraform

The Terraform provider manages the platform-side Evictor configuration through two resources:

  • castai_evictor configures the Evictor policy: the operating modes, the PDB override, soft tainting, and node grace period. It also covers cycle and drain timing and per-cycle node limits. It also exposes the capability disable switches.
  • castai_evictor_advanced_config manages the advanced eviction rules.

Cast AI syncs settings applied through Terraform to the cluster in managed mode. See the resource documentation for the full argument reference. Some fields are forward-compatibility placeholders that take effect as backend support rolls out.

See also


Did this page help you?