Skip to content
SHC Docs

The resource model on next

New line, in development. This page describes SHC as it is on the dev branch, not the released product. See The new line.

Four mechanisms use different figures:

  1. The per-service quota derives a limit and reservation when a service declares a quota or scoped config supplies one. With neither, the service reserves nothing.
  2. Scope caps (shc quota set) cap what a tenant, environment, stack or deployment may charge in total. Off until an operator sets one.
  3. Disk has per-volume sizes only for provisioned block volumes. Usage is measured on the leader, and a disk cap refuses an install, a growing update or a scale up once that usage is at or over the cap.
  4. Node capacity is the node’s whole machine less what runs there outside SHC, less what its operator keeps for work outside SHC (shc node update --reserve), less what SHC itself has reserved there.

Checked against shc d1cc800882 and its ce pin 0ca02485c9 on 2026-10-04; section 4 rechecked against ce next 0bbf03901e on 2026-10-10. Paths are ce unless they say shc. Each line is marked built, partly built (what is missing follows) or not built (no install-time enforcement). The older, longer quota model still holds for history and measurements; where it and this page differ, this page is checked against today’s code.

Each service resolves one quota per axis (CPU, memory), highest tier first (modules/app/resource_quota.go resolveQuotaAxis):

TierSourceStatus
1--cpu-quota <service>=<cpus> / --memory-quota <service>=<size> on install or update, stored on the deployment as resource_overrides (deploy_overrides.go ApplyDeployOverrides). A size is compose’s (512M, 4G) or binary (512Mi, 4Gi), written into the render as compose reads it; a value SHC cannot read is refused before anything is written (core/composeunits)built
2scoped config deploy.cpu_quota / deploy.memory_quota, one figure for every service in scope (logged X200946QTASRC)built
3the tier that won before, read back off the x-shc-quota marker SHC writes into a render. Present only when the input is already an SHC render: an authored x-shc-quota is refusedbuilt
4the app’s deploy.resources.limits.cpus / .memorybuilt
5the app’s deploy.resources.reservations.cpus / .memory (logged X200946QTASRC)built
6nothing: no limit, no reservation, no chargebuilt

From the quota (ApplyResourceQuotas):

WhatRuleStatus
limitquota x deploy.limit_ratio, default 1.5, never below 1 (defaultLimitRatio; a bad value is clamped to 1.0 and logged X200948QTALRT)built
reservationkept if the app wrote one; otherwise quota x deploy.reservation_ratio, default 1.0, with per-axis deploy.cpu_reservation_ratio / deploy.memory_reservation_ratio, floored at 10 millicores or 4 MiB, then capped at the quota even when that quota is below the floor (resource_reservations.go defaultReservationRatio, scaleCPUString, scaleMemoryString)built
where a ratio comes fromthe four ratio keys are read deployment > stack > environment > tenant > node > location > global, the most specific row winning: a tenant’s ratio beats a node’s, and a node or location row is no ceiling (Clay, 2026-10-29, review rv_f9578a76e4c4a5f1). A platform admin writes the node and location rows: shc config set deploy.reservation_ratio 0.5 --scope node --node inc01, --scope location --location hetzner/eu-central. A location row covers every node at or below it, the deepest winning. shc config get deploy.reservation_ratio --node inc01 names the tier that answered, and an unset ratio answers its built-in number with source default (core/scope ladder, modules/config/node_scope.go)built
a node’s own ratioadmission and the render’s placement ask each candidate node for the request its own ratio makes, so a quota can fit a node at 0.5 and not one at 1.0; the replica is rendered with the ratio of the node it lands on, its limit too (modules/app/quota_node.go, core/placement ReplicaDemand.On)built
authored reservation above the quotalowered to the quota, logged X200947QTACLM. An authored reservation at or below the quota stays as written; an authored limit is always rewritten from the quotabuilt
chargethe quota, never the limit or the reservationbuilt

Worked example: deploy.resources.limits: {cpus: "1", memory: 512M} and nothing else renders a 1.5 CPU, 768M limit, a 1 CPU, 512M reservation, and charges 1 CPU and 512M. Measured through these functions on ce next; see the worked app.

What each runtime does with the rendered figures:

RuntimelimitsreservationsStatus
dockerhard: CPU throttles, memory over the limit is OOM-killedmemory is a soft kernel reservation; CPU is ignored by composebuilt (measured, resource_reservations.go header)
podmanpassed to podman-composepassed to podman-composebuilt render path; kernel behaviour not measured here
incuswritten as limits.cpu.allowance and limits.memorymemory is lxc.cgroup2.memory.low, the soft floor docker’s MemoryReservation sets; CPU is ignored, as compose ignores it. An instance made before 0.1.41 keeps its form until something else remakes itbuilt (core/executor/incus/translate.go reservedMemory, translate_keys.go)
appleVM CPU rounded up to whole vCPUs; memory passed as --memory, and a limit under 200 MiB passed as 200 MiB, the least the runtime gives a container’s VMnot applied by the executorbuilt (core/executor/apple/project.go translateService)

Not read by the quota: the service-level cpus, cpu_shares, cpu_quota, cpu_period, cpuset, mem_limit, mem_reservation, memswap_limit. Runtime support varies; Incus refuses these keys. SHC’s quota does not read them. Apple’s service-level cpus and mem_limit take precedence over deploy limits.

shc quota set --scope <scope> (base, tenant, environment, stack or deployment) writes one config row per axis under quota. (shc cli/quota_client.go, daemon/wiring/quota_limits.go). With no row, an axis is unlimited and nothing is refused.

Cap keyCharged whenRefusalStatus
quota.cpueach install or update render, the quota x replicas (a count it cannot read, or below 1, counts as 1) summed over the deployment (modules/app/quota_render_charge.go chargeRenderQuotas), checked at the deployment, its environment and its tenant (shc modules/quota/service.go EnforcementWalk)X403001CPUEXCbuilt
quota.memorysameX403002MEMEXCbuilt
quota.diskan install, an update that adds a service or a named volume, or a scale up, when measured disk usage is already at or over the cap at that deployment, its stack, its environment or its tenant (shc modules/quota/disk_admission.go RefuseMeasuredDisk; the install gate is shc daemon/wiring/quota_limits.go Enforce, and a growing render is modules/app/quota_render_charge.go renderAddsFootprint). Uninstall, scale down, stop and backup are admitted. Declared volume sizes are not read; an unmeasured scope is skippedX403003DSKEXCbuilt
quota.max_appsinstall, +1 at tenant scope (shc daemon/wiring/quota_limits.go appQuotaEnforcer.Enforce)X403006APPEXCbuilt
quota.max_deploymentsinstall of a deployment, +1 at tenant scopeX403004DEPEXCbuilt
quota.max_vdeploymentsinstall of a vapp instance, +1 at tenant scopeX403007VDPEXCbuilt
quota.max_environmentsinstall of the first deployment into an environment the tenant doesn’t occupy; existing environments are never refusedX403005ENVEXCbuilt

For CPU and memory the check and the charge are one write (shc modules/quota/enforcement.go UpdateUsageOnScale), so concurrent installs cannot overshoot those caps. The count caps are the same kind of write, taken at admission (shc modules/quota/charge.go AdmitInstall, from appQuotaEnforcer.Enforce): one statement batch asserts the tenant ceiling and records the counter. If the install then fails, that charge is released. RecordCreate does not write these counters. A release is always admitted. An update charges only the difference from what the deployment already holds. The --max-* counters are read at tenant scope only; a row set lower is stored and never consulted.

WhatHowStatus
a named volume on a node’s own diska directory under the deployment (<deployment dir>/mounts/<name>), no size limitbuilt (no limit)
local per-volume limits with zfs, xfs project quotas or btrfs qgroupshandlers exist (modules/storage/quotas/quotas.go), chosen by filesystem in modules/storage/providers/local/provider.go Detect; nothing calls SetQuotanot built
ext4, apfs or anything else locallyno limit, no handlernot built
a provisioned block volume (x-shc-volumes: {<name>: {size}}, or derived for durable volumes when the node has a volume provider)a disk from the provider (hcloud, DigitalOcean, Linode, Vultr, AWS EBS, GCE PD, Azure Disk, Cinder, CloudStack), formatted and mounted on the node. The provider rounds the size to its own steps and minimums (Vultr: up to whole GiB, at least 10 or 40 GiB, modules/storage/providers/vultrvolume/provider.go sizeGB), and the provisioned size is the hard limit. No size means the provider’s default (core/volume/binding.go Binding, ce daemon/volume_binder.go)built
CephFSceph.quota.max_bytes per folder (modules/storage/providers/cephfs/provider.go SetQuota), not reached from the install pathnot built
NFSno size limitnot built
tenant disk usagean hourly leader-only cron walks each deployment’s directory on the leader’s own disk (zfs, xfs or btrfs accounting where present, du otherwise) and writes disk_bytes (shc modules/quota/crons.go scan_all_disk_usage, daemon/wiring/quota_wire.go quotaDiskPaths)partly built: a deployment on another node is not measured where it lives

Quota module still says no composition root wires the disk path resolver. That is out of date: shc daemon/wiring/quota_wire.go wires quota.NewDeploymentPathResolver. Its point about a leader-only walk still holds.

A replica with a durable volume on its node’s own disk is pinned to that node. Placement keeps it inside the volume’s reach, which for a local volume is the node it is bound to (core/placement/place.go volumeHolds, Mount.reach), and when the node is lost it has no move path: it stays assigned and starts when the node returns (core/placement/movability.go mountMovability, “local volume”). Only a volume backup.yaml calls scratch is left behind; with no backup.yaml every volume is held as durable. Built.

WhatHowStatus
what a node reportsLogical CPUs (sysfs, then /proc/cpuinfo, then runtime.NumCPU) and physical memory (/proc/meminfo on Linux, hw.memsize on macOS) (modules/cluster/cpu.go, memory.go), stored on the node row. A node in an Incus or LXC container counts at most what its cgroup allows, its cpuset.cpus.effective and its cpu.max rounded up; a host counts its whole box however its daemon is pinned (SHC-2739)built
disk per nodeasked of every node at admission: the bytes free where its runtime pulls images, and which images it lacks. A node keeps 2 GiB and its disk reserve free after the pull (daemon/image_room.go, core/placement/image_room.go ImageKeep). Volumes are not weighedpartly built
fabric addresses per noderead from the fabric ledger at every placement: how many pins each node can still be given, whatever their tenant. That is the free addresses of its chunks, a pinned, quarantined or unacknowledged one counted as taken, as the allocator counts it, and what the chunks the fabric’s ranges can still hand out would give it, in the genesis block and every block added since. A replica takes one for each member with a network namespace of its own and one for its health watcher on an Incus node. A node short of them is left out with address_room, and when no node has them the install or update is refused X409179PLCPND with each node’s free count, before anything renders (ce modules/fabric/address_room.go AddressRooms, core/placement/address_room.go). A move by failover, drain or a rebalance asks for what each replica it moves took where its record was finished, its watcher included (ce core/pod/record.go Pins)built
what is committed on a nodethe reservation of every replica bound to the node: each replica row (assignment, a pod’s row, so the sum of its members’) is charged to the node it binds, every incarnation counted, so a replica being moved is charged at both ends until the move retires one. A deployment with no replica rows (a document that did not split, one that predates them) is charged as one unit, reservation x desired replicas (0 counts as 1) of every service, to its recorded node and occupancy anchors. A holding replica that reserves nothing (zeroed after a no-fit, or its reservation derived from a limit) charges what one replica of its pod declares, its own service’s row and the deployment’s services with no replica row of their own, never the deployment’s other replicas; with no declaration that axis is unknown (ce modules/app/deployment_node_repo.go setOccupancyAnchor). ce modules/scheduler/commitment.go CommitmentQuery, which shc’s ledger (modules/quota/commitment.go) and the admission fit (scheduler.LedgerCapacities) both read, so a requested reservation is never admitted onto a node with less free than it asks by that figure (SHC-3294)built
the fit checka replica fits when its reservation is at most capacity minus committed; a node with unknown capacity stays a candidate (core/placement/place.go fits). A replica that requests none of a resource, an app’s own limit (which reserves nothing, SHC-2738) or a reservation the render has not resolved yet, fits anywhere, but it prefers the nodes the ledger does not read full of that resource: no memory free, or CPU past capacity. When every node it may use is full it binds anyway and its placement reason says so, so a limit never holds an install pending. A memory limit past a node’s RAM risks the kernel’s OOM killer there, where a CPU limit only slows it (pastCapacity, SHC-3294; capacity fed by shc modules/placement/advisor.go capacityOf, wired in shc daemon/wiring/cluster_placement_ledger.go). Capacity is read as unknown when the node row has none, or when every service on the node reserves nothing (NodeCommitment.CPUKnown)built
no node fitsthe install is refused and nothing is installed: X409179PLCPND, with each node’s reason (insufficient_cpu, insufficient_memory) in shc constraint explain. When an operator’s quota is behind the request, this refusal and X400298FNCFIT, X409947SCHRSV and X409948SCHOUT end with it: postgres asks for its --memory-quota 6G at reservation ratio 1 (modules/fence/admit_quota.go)built
what a replica reservesthe reservation the app wrote, and the one the render derives from an operator’s quota (tier 1 or 2), quota x reservation ratio, summed over the services of its pod (modules/app/replica_projects.go serviceReserve). A reservation derived from the app’s own limit reserves nothing: a limit is a ceiling (SHC-2738)built
anything outside SHCeach node reports, every 30 seconds, the limits or the measured use of containers without SHC’s labels and of Incus instances that are no SHC replica, and the fit takes it off the node’s room. Nothing is evicted when it grows; the node reads over-committed and takes no new replica (modules/scheduler/outside.go roomExpr)built
what an Incus node countsevery running instance in every project that carries no user.label.shc.* key, so a VM started with incus launch is counted with nobody touching SHC. CPU and memory by limits.cpu and limits.memory; a virtual machine with no limit counts 1 core and 1 GiB; a container with no memory limit counts its measured memory, and one with no CPU limit the CPU it used between two readings, rounded up to 0.1 core. Its root disk counts by its size less what it already uses (a virtual machine with no size has 10 GiB), and admission keeps that free on the node on top of the image floor and the reserve. A stopped instance counts nothing (modules/outsideuse/probe.go incusOutside)built
where outside use showsshc node ls -v as OUTSIDE, spelled as a reserve is (cpu=6.5,memory=10Gi,disk=46Gi); shc node info as outside and, on an Incus node, outside instances, each project/name; -o json as outside_cpu_millicores, outside_memory_bytes, outside_disk_bytes and outside_instances. A replica asked of a node that would take it but for that work is refused X409948SCHOUT: “node inc01 has 13.0 GiB memory taken by default/build01 and infra/pfsense outside SHC and 2.3 GiB left for SHC”built
a node that is a virtual machineit sees only itself, so it reads its host through a connection: shc node update shc01 --hypervisor ogden-view. Every 30 seconds it reads, and only reads, the Incus member it runs on, that member’s cores and memory and the other running instances there. When their limits leave the host less than the node’s own size, the difference is added to the node’s outside use with those instances named. shc node info shows hypervisor, host member, host capacity, host instances, a host note when the certificate is restricted to some projects, and a host error when the read failed, in which case the last report stands. See Nodes on a hypervisor (modules/outsideuse/host.go Host)built
a node’s reservewhat an operator keeps on a node for work SHC cannot see or that is not running yet, as kubelet’s system-reserved: shc node update home01 --reserve cpu=1,memory=4Gi,disk=50Gi. Its cpu and memory come off the node’s room in the fit plan, bind and admission share; its disk is kept free on top of the image floor. A replica asked of a node that would take it but for the reserve is refused X409947SCHRSV; one asked of no node goes to a node with room. shc node ls -v shows it as RESERVED, shc node info as reserve (modules/scheduler/reserve.go)built
a movefailover asks the engine for what each row it moves reserves and the fabric addresses it takes, on each node’s capacity and committed figures as admission reads them, and the row keeps its reservation on the node it lands on; a replica that fits nowhere stays pending on its lost node with each node’s reason. A drain leaves out a node short of addresses and places over capacity with a warning (X200036CLSOVC); a rebalance plans with both (shc modules/failover/reschedule.go, daemon/wiring/cluster_drain_placement.go, modules/rebalance/source.go, SHC-3082). Every move weighs disk too: the images each moved replica runs, as its stored spec records them, that the target lacks, against the target’s image store room as admission reads it. Failover and drain leave out a node without that room and make it on the node they land on before the pull, as an install does; failover asks only the ready nodes it may land on. A rebalance counts free bytes alone and never prunes images to make a move fit (ce core/placement/image_room.go WithImageRoom, modules/app/image_room.go ReclaimForMove, SHC-3101). Of the nodes that would end below a rebalance move’s source, it takes the one placement’s scorer ranks first, as an install would, the room each one’s pool keeps included, and shc rebalance --plan names each one’s score and why it was or was not taken (shc modules/rebalance/score.go NewEngine, SHC-3341)built
overcommit settingnone for placement; overcommit of limits is deploy.limit_rationot built
a service with no quotareserves nothing, so it fails the fit check only on a node with no memory left (fits)built
  • x-shc-volumes.access: rox parses; multi-attach depends on the provider.
  • deploy.resources.limits.pids is honoured by the runtime and not charged.
  • deploy.resources.*.devices and generic_resources are refused until a device fence exists.
  • The zfs, xfs and btrfs quota handlers and CephFS quotas (section 3).
  • No per-volume size limit for data on a node’s own disk.
  • Disk usage is measured only on the leader.
  • A replica with a durable local volume cannot move off a lost node.
  • Service-level cpus, mem_limit and friends escape both the quota and the node reservation.
  • Podman’s render path is built, but its kernel enforcement was not measured in this audit.
  • A service with no quota reserves nothing and is held back only by a node with no memory left.
  • A failover or drain move, and the replica of a global service that a joining node takes, keep the request and limits the replica was rendered with until the deployment is next rendered; a node-scoped ratio reaches them then.