Autoscaling & Capacity AI

Deep skill for scaling and resource optimization. Everything scaling lives in one block — spec.defaultOptions.autoscaling (with capacityAI beside it); spec.localOptions[] overrides it per location. The platform keeps the chosen metric near but below target. For workload types, production defaults, and the spec shape, start with the `workload` skill.

Picking a metric

If metric is omitted, serverless defaults to concurrency and stateful to cpu. Standard is the trap: with Capacity AI on (its default) an omitted metric resolves to disabled — min = max, no autoscaling — so always name the metric on a standard workload that must scale. A metric invalid for the workload type is rejected (e.g. concurrency on standard).

The metric constrains the type — decide them together. Type is chosen at creation and is immutable, so a metric-type mismatch is a type problem, not a metric problem. The most common case: concurrency-style scaling on a standard workload — the fix is to create the workload as serverless (concurrency lives only there) or use `rps` on standard (the closest equivalent), not to retry with the same pairing.

The autoscaling block

Set with mcp__cpln__create_workload / mcp__cpln__update_workload, then verify with mcp__cpln__list_deployments. All fields:

spec:
  defaultOptions:
    autoscaling:
      metric: rps
      target: 100             # default 95; integer 1-20000; ≤100 for cpu/memory; ms for latency
      minScale: 2             # default 1; must be ≤ maxScale; 0 = scale-to-zero (rules below)
      maxScale: 10            # default 5; no schema maximum
      scaleToZeroDelay: 300   # 30-3600s, default 300
      maxConcurrency: 0       # serverless only; 0-30000, default 0 = unlimited (excess queues)
      metricPercentile: p99   # latency only: p50 (default) / p75 / p99
    capacityAI: true

• Per-location overrides: spec.localOptions[] (same fields + location) via mcp__cpln__configure_workload_local_options (full profile), the only MCP tool that sets capacityAIUpdateMinutes or multiZone; it replaces the full list. Both also exist on spec.defaultOptions, reachable with cpln apply.
• `scaleToZeroDelay` is dual-purpose: on serverless it is the idle period before scaling to 0; on standard/stateful it sets the scale-down stabilization window (default 300s) — scale-up is immediate.

Multi-metric (standard/stateful)

autoscaling:
  minScale: 2
  maxScale: 10
  multi:
    - metric: cpu
      target: 80
    - metric: memory
      target: 80

Each entry is evaluated independently; the highest replica count wins. Only cpu / memory / rps, each at most once; targets go inside the entries (metric/target at the top level are rejected alongside multi). With multi, Capacity AI defaults to off.

Scale to zero

• Scale to zero by type: serverless freely; standard and stateful only with metric: keda (anything else is rejected); cron never. Serverless reaches zero with concurrency or rps; cpu and memory ride an HPA that never drops to zero. The first request after idle pays a cold start.

KEDA (event-driven, standard/stateful)

1. Enable on the GVC first — mcp__cpln__update_gvc:

spec:
  keda:
    enabled: true                            # default false
    identityLink: //gvc/GVC/identity/NAME    # optional: cloud/network access for the KEDA operator
    secrets: [//secret/NAME]                 # optional: each becomes a TriggerAuthentication named after the secret

2. Set the workload — metric: keda plus raw KEDA trigger specs (passed through as-is):

autoscaling:
  metric: keda          # target is rejected with keda
  minScale: 0           # maps to KEDA minReplicaCount — this is how standard/stateful scale to zero
  maxScale: 10
  keda:
    triggers:
      - type: redis
        metadata:
          address: my-redis.my-gvc.cpln.local:6379
          queueLength: '5'
          passwordFromEnv: REDIS_PASSWORD

• Triggers needing auth reference a GVC-listed secret via authenticationRef.name (the TriggerAuthentication is named after the secret).
• If the trigger source is a Control Plane workload, allow KEDA in the source's firewall: internal.inboundAllowWorkload: [cpln://internal/keda].
• Also supported: keda.advanced.scalingModifiers (custom formulas), fallback, pollingInterval, cooldownPeriod.
• Prometheus trigger — scale on any platform or custom metric: type: prometheus with serverAddress: https://metrics.cpln.io:443/metrics/org/ORG, a query (PromQL), threshold, and customHeaders: Authorization=Bearer SERVICE_ACCOUNT_TOKEN (service account needs readMetrics). Before wiring any trigger, confirm the signal resolves: mcp__cpln__list_metrics for real names/labels, then mcp__cpln__query_metrics to run the PromQL — a never-resolving signal pins the workload at minScale. Custom app metrics come from the container metrics block (see metrics-observability).

Capacity AI

Right-sizes each container's reserved resources (what you're billed for) from usage history, between the minCpu/minMemory floor and the cpu/memory ceiling. Every workload type supports it. Standard, serverless, and cron enable it by default.

spec:
  containers:
    - name: app
      cpu: '1000m'       # ceiling (and the fixed allocation when Capacity AI is off)
      memory: '1Gi'      # ceiling
      minCpu: '100m'     # floor
      minMemory: '256Mi' # floor
  defaultOptions:
    capacityAI: true

• With `metric: cpu`: explicitly enabling Capacity AI is rejected (dynamic CPU allocation fights CPU-based scaling); left unset with cpu or multi, it silently defaults to off.
• GPU containers reject Capacity AI.
• Adjustments land in place on standard and stateful when the cluster supports pod resize (no restart; otherwise a rolling update); serverless rolls a new revision; cron picks up the new reservation on its next execution — a run already in flight is never resized. Throttle frequency with capacityAIUpdateMinutes (min 2 — via localOptions or cpln apply; not on create/update tools).
• Idle floor is 25m CPU, rising with memory at 1 millicore per 3 MiB. A just-changed workload pauses adjustments while history rebuilds — apps that reserve resources at startup may not benefit.

Resource bounds (all types)

• Floors and the memory to CPU ratio: workload skill. minCpu and minMemory never exceed cpu and memory.
• With Capacity AI off: cpu/memory are the fixed allocation and minCpu/minMemory are ignored — except on stateful, where minCpu/minMemory become the static reserved request and cpu/memory stay the burst ceiling.
• Stateful `minCpu`/`minMemory` are bounded whether or not Capacity AI is on: max/min ratio ≤ 4 AND gap ≤ 4000m CPU / 4096Mi memory.
• GPU: nvidia model t4 (quantity up to 4) or a10g (exactly 1); strict per-model CPU/memory minimums — fetch exact numbers with mcp__cpln__get_resource_schema (kind: workload).
• Cost: billing follows reserved resources, so Capacity AI (or stateful minCpu) directly lowers cost.

Troubleshooting