The resource model on next
New line, in development. This page describes SHC as it is on the
devbranch, not the released product. See The new line.
Four mechanisms use different figures:
- 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.
- Scope caps (
shc quota set) cap what a tenant, environment, stack or deployment may charge in total. Off until an operator sets one. - 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.
- 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.
1. The per-service quota
Section titled “1. The per-service quota”Each service resolves one quota per axis (CPU, memory), highest tier first (modules/app/resource_quota.go resolveQuotaAxis):
| Tier | Source | Status |
|---|---|---|
| 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 |
| 2 | scoped config deploy.cpu_quota / deploy.memory_quota, one figure for every service in scope (logged X200946QTASRC) | built |
| 3 | the 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 refused | built |
| 4 | the app’s deploy.resources.limits.cpus / .memory | built |
| 5 | the app’s deploy.resources.reservations.cpus / .memory (logged X200946QTASRC) | built |
| 6 | nothing: no limit, no reservation, no charge | built |
From the quota (ApplyResourceQuotas):
| What | Rule | Status |
|---|---|---|
| limit | quota x deploy.limit_ratio, default 1.5, never below 1 (defaultLimitRatio; a bad value is clamped to 1.0 and logged X200948QTALRT) | built |
| reservation | kept 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 from | the 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 ratio | admission 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 quota | lowered to the quota, logged X200947QTACLM. An authored reservation at or below the quota stays as written; an authored limit is always rewritten from the quota | built |
| charge | the quota, never the limit or the reservation | built |
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:
| Runtime | limits | reservations | Status |
|---|---|---|---|
| docker | hard: CPU throttles, memory over the limit is OOM-killed | memory is a soft kernel reservation; CPU is ignored by compose | built (measured, resource_reservations.go header) |
| podman | passed to podman-compose | passed to podman-compose | built render path; kernel behaviour not measured here |
| incus | written as limits.cpu.allowance and limits.memory | memory 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 it | built (core/executor/incus/translate.go reservedMemory, translate_keys.go) |
| apple | VM 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 VM | not applied by the executor | built (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.
2. Scope caps
Section titled “2. Scope caps”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 key | Charged when | Refusal | Status |
|---|---|---|---|
quota.cpu | each 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) | X403001CPUEXC | built |
quota.memory | same | X403002MEMEXC | built |
quota.disk | an 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 skipped | X403003DSKEXC | built |
quota.max_apps | install, +1 at tenant scope (shc daemon/wiring/quota_limits.go appQuotaEnforcer.Enforce) | X403006APPEXC | built |
quota.max_deployments | install of a deployment, +1 at tenant scope | X403004DEPEXC | built |
quota.max_vdeployments | install of a vapp instance, +1 at tenant scope | X403007VDPEXC | built |
quota.max_environments | install of the first deployment into an environment the tenant doesn’t occupy; existing environments are never refused | X403005ENVEXC | built |
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.
3. Disk
Section titled “3. Disk”| What | How | Status |
|---|---|---|
| a named volume on a node’s own disk | a directory under the deployment (<deployment dir>/mounts/<name>), no size limit | built (no limit) |
| local per-volume limits with zfs, xfs project quotas or btrfs qgroups | handlers exist (modules/storage/quotas/quotas.go), chosen by filesystem in modules/storage/providers/local/provider.go Detect; nothing calls SetQuota | not built |
| ext4, apfs or anything else locally | no limit, no handler | not 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 |
| CephFS | ceph.quota.max_bytes per folder (modules/storage/providers/cephfs/provider.go SetQuota), not reached from the install path | not built |
| NFS | no size limit | not built |
| tenant disk usage | an 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.
4. Node capacity
Section titled “4. Node capacity”| What | How | Status |
|---|---|---|
| what a node reports | Logical 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 node | asked 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 weighed | partly built |
| fabric addresses per node | read 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 node | the 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 check | a 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 fits | the 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 reserves | the 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 SHC | each 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 counts | every 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 shows | shc 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 machine | it 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 reserve | what 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 move | failover 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 setting | none for placement; overcommit of limits is deploy.limit_ratio | not built |
| a service with no quota | reserves nothing, so it fails the fit check only on a node with no memory left (fits) | built |
Other resource keys
Section titled “Other resource keys”x-shc-volumes.access: roxparses; multi-attach depends on the provider.deploy.resources.limits.pidsis honoured by the runtime and not charged.deploy.resources.*.devicesandgeneric_resourcesare 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_limitand 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.