Skip to content
KiCI Docs

Auto-scaler

The auto-scaler dynamically provisions agents in response to workload. It is configured via a scalers.yaml file (or files in a scalers.d/ directory) that maps job labels to backend provisioning details. The orchestrator reloads it on SIGHUP.

Quick start

Section titled “Quick start”
  1. Create a scaler config file:
/etc/kici/scalers.yaml
version: 1
globalMaxAgents: 10


scalers:
  - name: container-default
    type: container
    # runtime defaults to 'auto' -- detects Docker or Podman
    maxAgents: 10
    labelSets:
      - labels: ['linux', 'container']
        image: 'ghcr.io/myorg/kici-agent:latest'
  1. Point the orchestrator at it:
KICI_SCALER_CONFIG_PATH=/etc/kici/scalers.yaml

For multi-file configurations, also set KICI_SCALER_CONFIG_DIR=/etc/kici/scalers.d/.

  1. Restart the orchestrator. It now auto-provisions container agents when jobs arrive with runsOn: ['linux', 'container'].

Which backend?

Section titled “Which backend?”
BackendProvisionsChoose it for
containerDocker / Podman containersLinux CI on shared infrastructure — the common deployment.
bare-metalHost child processesmacOS, Windows, GPU, or specialized hardware workloads.
firecrackerKVM microVMsUntrusted / multi-tenant workloads needing hardware isolation.
eventCloud instances, through your own provisioning workflowCloud autoscaling without a built-in cloud SDK.

Caps in a cluster

Section titled “Caps in a cluster”

maxAgents means different things on a local backend and on the event backend, and the difference matters as soon as you run more than one orchestrator against one shared database.

CapCountedBounds
maxAgents on an event scalerAcross the clusterThe number of cloud instances that scaler runs
maxAgents on container / bare-metal / firecrackerPer orchestratorThe agents that one host runs
globalMaxAgentsPer orchestratorThe agents that one host runs, across its scalers

A local backend runs its compute on the orchestrator’s own machine, so its cap is a statement about that machine’s CPU, memory, and disk. Counting it across the cluster would let one busy host take the whole budget and exhaust itself. Two orchestrators that each set maxAgents: 10 on a container scaler therefore run up to 10 containers each, and 20 together.

An event scaler runs no local compute. It asks a provisioning workflow to boot a cloud instance, and any coordinator can ask. Its cap is a statement about the cloud bill, so it is counted and claimed cluster-wide, inside one database transaction. Two coordinators that each set maxAgents: 10 on the same event scaler run 10 instances in total. See Event scaler high availability.

Reference

Section titled “Reference”
PageCovers
Common configurationFields shared across all backends: top-level schema, label sets, resource caps, warm pool, roles, mandatory/exclude labels, env forwarding, network policy, backpressure.
OperationsRunning and observing: label matching, multi-scaler layout, deployment topology, SIGHUP reload, monitoring, troubleshooting, multi-backend examples.
Container backendContainer-specific fields, runtime auto-detection, lifecycle, registry auth, the container-socket security warning.
Bare-metal backendHost child processes, cgroup enforcement, network access, remote macOS / Windows orchestrator setup.
Firecracker backendVM networking, jailer fields, rootfs, DB migration, the MMDS credential model, helper scripts.
Event backendCloud autoscaling driven by your own provisioning workflow: event fields, claim codes, cluster-wide caps, the teardown reaper.

See also

Section titled “See also”