WorkloadScaler CRD

The WorkloadScaler CRD connects a Kubernetes workload to EcoScale optimization policy. It identifies the target workload, declares what EcoScale should optimize, defines recommendation cadence, and sets the guardrails that control how resource recommendations are generated and applied.

Use this reference when you need to tune workload-level behavior beyond the default policy.

Basic Shape

apiVersion: escale.dev/v1alpha1
kind: WorkloadScaler
metadata:
  name: catalog-api
  namespace: retail
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: catalog-api
    namespace: retail
  optimize:
    - resource
  resources:
    updatePolicy:
      updateMode: Preview
    resourcePolicy:
      containerPolicies:
        - name: api
          cpu:
            scalingGoal: Balanced
            scalingPolicy: RequestsOnly
          memory:
            scalingGoal: Balanced
            scalingPolicy: RequestsAndLimits

This shape keeps recommendations in preview while defining CPU and memory policy for the api container. When interval is omitted, EcoScale uses the default recommendation interval.

Target Reference

spec.targetRef identifies the Kubernetes workload EcoScale evaluates.

Field	Purpose
`apiVersion`	API version of the target workload, such as `apps/v1`.
`kind`	Target workload kind. Built-in workload kinds such as `Deployment`, `StatefulSet`, `DaemonSet`, `Job`, and `CronJob` are supported, and custom CRD kinds can also be used when EcoScale can identify the pods to optimize.
`name`	Name of the target workload.
`namespace`	Namespace of the target workload.
`podSelector`	Optional selector used mainly to discover pods owned by custom CRDs or custom operators. Use it when owner references are not enough and the workload to pods relationship needs to be expressed through labels.

Always verify the target reference before applying recommendations. This is the first safety check for any resource change.

Optimization Scope

spec.optimize declares what EcoScale should optimize. These docs focus on resource optimization:

optimize:
  - resource

Resource optimization covers CPU and memory requests and limits for workload containers.

Recommendation Interval

spec.interval controls how often recommendations should be generated and, depending on updateMode, how often eligible recommendations may be applied.

interval: 1d

The default interval is 1d. Use shorter intervals only when recommendations need to react more quickly. For stable workloads, a daily interval reduces unnecessary churn.

Defaults

Field	Default
`spec.interval`	`1d`
`cpu.scalingGoal`	`Balanced`
`memory.scalingGoal`	`Balanced`
`cpu.scalingPolicy`	`RequestsOnly`
`memory.scalingPolicy`	`RequestsAndLimits`
`resources.updatePolicy.updateMode`	Set explicitly. Use `Preview` as the recommended starting mode.

Some WorkloadScaler resources are created by a WorkloadScalerRule. In that case, the rule can provide fleet-level defaults for fields such as resources.updatePolicy.minReplicas, wildcard CPU and memory policy, and replica bounds. Rule defaults are only applied when the corresponding WorkloadScaler field is absent; explicit workload policy wins.

If a target workload should be discovered but should not inherit rule defaults, annotate either the target workload or the WorkloadScaler:

metadata:
  annotations:
    escale.dev/skip-defaults: "true"

This is useful for critical services or workloads whose policy is managed by a separate platform workflow.

Update Policy

spec.resources.updatePolicy controls whether recommendations remain advisory or can move toward application.

Field	Purpose
`updateMode`	Controls resource update behavior. Common modes are `Preview`, `Auto`, `Disabled`, and `InPlaceOrRecreate`.
`evictionRequirements`	Defines conditions that must be true before resource changes that require eviction are allowed.

Use Preview for new workloads, critical services, or teams still validating recommendations. Use Auto only after recommendation quality is trusted and the connected agent has apply-capable permissions.

Container Policies

spec.resources.resourcePolicy.containerPolicies defines CPU and memory behavior per container. Each policy is matched by container name.

scalingGoal describes the intent of the recommendation. See Scaling Goals for the detailed behavior and operational guidance.

scalingPolicy controls what can be changed. See Scaling Policies for the policy defaults and behavior.

Requests And Limits Guardrails

CPU and memory policies can define guardrails for requests and limits.

Field	Purpose
`requests.min`	Minimum request EcoScale should recommend.
`requests.max`	Maximum request EcoScale should recommend.
`requests.metricThresholds.delta`	Minimum absolute change required before a recommendation is worth applying.
`requests.metricThresholds.deltaPercent`	Minimum percentage change required before a recommendation is worth applying.
`limits.min`	Minimum limit EcoScale should recommend.
`limits.max`	Maximum limit EcoScale should recommend.
`limits.limitRequestRatio`	Keeps limits proportional to requests.
`limits.metricThresholds.delta`	Minimum absolute limit change required before applying.
`limits.metricThresholds.deltaPercent`	Minimum percentage limit change required before applying.

Use min and max fields to define safety bounds. Use thresholds to avoid low-value churn. Use limitRequestRatio when limits should stay tied to requests.

Full Resource Policy Example

apiVersion: escale.dev/v1alpha1
kind: WorkloadScaler
metadata:
  name: catalog-api
  namespace: retail
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: catalog-api
    namespace: retail
  optimize:
    - resource
  interval: 1d
  resources:
    updatePolicy:
      updateMode: Auto
      evictionRequirements:
        - changeRequirement: TargetLowerThanRequests
          resources:
            - cpu
            - memory
    resourcePolicy:
      containerPolicies:
        - name: api
          cpu:
            scalingGoal: Balanced
            scalingPolicy: RequestsOnly
            requests:
              min: 100m
              max: "2"
              metricThresholds:
                delta: 50m
                deltaPercent: 10
            limits:
              max: "4"
              limitRequestRatio: "2"
          memory:
            scalingGoal: Balanced
            scalingPolicy: RequestsAndLimits
            requests:
              min: 256Mi
              max: 4Gi
              metricThresholds:
                delta: 128Mi
                deltaPercent: 10
            limits:
              max: 8Gi
              limitRequestRatio: "2"

This example uses Auto, but that should be reserved for workloads where the team trusts the recommendation stream. For most rollout paths, start with Preview, validate recommendations manually, and then promote stable workloads to Auto.

Operational Guidance

Start with Preview and add guardrails before enabling Auto. Set request and limit bounds for critical services, use thresholds to avoid low-value changes, and confirm the cluster agent is installed with apply-capable permissions before expecting EcoScale to patch target workloads.