Placement rules
A deployment runs where its rules allow. --where is a must: nodes outside
it are removed. --prefer is a should: matching nodes rank first. Rules
also live at a scope, cluster or tenant, and apply to every deployment under
it. This page installs one small app several times, each with a different
rule. Create it on home01.
services: nginx: image: nginx:1.27-alpine expose: - "80"A rule can name a node. --label gives the deployment a label of its own,
which shc ls --where selects by; every hello deployment on this ladder
carries owner=learn.
$ shc install ~/learn/cluster/hello -s a1 --where node=home03 --label owner=learninstalling deployment "a1"[a1] Healthy 1/1✔ nginx healthy✔ installed deployment "a1"far01 carries the reserved tier=edge. A rule that does not name the value
leaves far01 out, so a location rule for learn/far finds no node.
$ shc install ~/learn/cluster/hello -s a2 --where location=learn/far --label owner=learnshc: [X409171FNCEMP] no node can take prod/a2/prod: where location=learn/far at deploy:prod:a2:prod keeps far01; reserved tier:edge keeps none: reserved, and no rule on this deployment names it$ shc install ~/learn/cluster/hello -s a2 --where tier=edge --label owner=learninstalling deployment "a2"[a2] Healthy 1/1✔ nginx healthy✔ installed deployment "a2"An install prints its result and nothing else. shc inspect a1 shows
where placement put it and why: the node, the rule that chose it, and the
scorer’s factors when the scorer ranked the nodes. A factor the node could
not answer reads unmeasured.
A rule can be a whole expression, and a preference ranks the nodes left.
$ shc install ~/learn/cluster/hello -s a3 --where '@learn/home' --prefer rack=r1 --label owner=learninstalling deployment "a3"[a3] Healthy 1/1✔ nginx healthy✔ installed deployment "a3"$ shc install ~/learn/cluster/hello -s a4 --where 'tier=core&rack!=r1' --label owner=learninstalling deployment "a4"[a4] Healthy 1/1✔ nginx healthy✔ installed deployment "a4"$ shc lsSTACK TENANT ENV APP STATUS NODEa1 prod prod /root/learn/cluster/hello running home03a2 prod prod /root/learn/cluster/hello running far01a3 prod prod /root/learn/cluster/hello running home03a4 prod prod /root/learn/cluster/hello running home01One service somewhere else
Section titled “One service somewhere else”Repeat --where to give one service a rule of its own. On a3,
--where location=learn/home --where nginx:node=home01 keeps every service
at home and puts nginx on home01. --where 'nginx!' drops that rule
again, and nginx falls back to location=learn/home. Naming a pod member
places the whole pod, naming a group places every member, and --prefer
takes the same forms. Cluster and tenant constraints still bind every
service.
--scale places replicas by count and location: two in home, one in
far. Naming tier=edge lets the far replica onto far01.
$ shc install ~/learn/cluster/hello -s a5 --scale nginx=2@home,1@far --where 'location=learn/home|tier=edge' --label owner=learninstalling deployment "a5"[a5] Healthy 1/1✔ nginx healthy✔ installed deployment "a5"$ shc ls --where owner=learnSTACK TENANT ENV APP STATUS NODESa1 prod prod /root/learn/cluster/hello running home03a2 prod prod /root/learn/cluster/hello running far01a3 prod prod /root/learn/cluster/hello running home03a4 prod prod /root/learn/cluster/hello running home01a5 prod prod /root/learn/cluster/hello running far01, home02, home03shc constraint explain prints every rule that shaped a deployment and the
nodes it leaves. --what-if-node asks about one node.
$ shc constraint explain -s a3deployment prod/a3/prod docker movability free priority normalrunning on home03status running
CONSTRAINTS deploy:prod:a3:prod where location=learn/home where set on this deployment removes far01; keeps home01 home02 home03 deploy:prod:a3:prod prefer rack=r1 prefer set on this deployment ranks home03; keeps home01 home02 home03
DERIVED CONSTRAINTS limit reserved tier:edge tier=edge is reserved and this deployment does not select it keeps home01 home02 home03 limit condition ready only ready nodes take new work keeps home01 home02 home03 limit architecture images the replica's images must have a manifest for the node's architecture keeps home01 home02 home03 limit fit room the replica needs capacity for its CPU and memory reservations; home01: cpu: past capacity, 3100m committed of 2000m removes home01; keeps home02 home03
eligible home02 home03
RELOCATION home02: possible shc update -s a3 -e prod --where 'node=home02'
failover 1m0s after its node's lease expires: a new assignment inside its eligible set$ shc constraint explain -s a3 --what-if-node far01...$ shc constraint explain -s a3 --where 'node=home01' --prefer 'tier=core'...$ shc constraint explain -s a3 --history 3...$ shc constraint explain -s a5 --service nginx...A rule at a scope binds every deployment under it, so a rule that would
leave one of them without a node is refused: prod kept in learn/home
alone would strand a2. Name the edge too and the rule binds every prod
deployment; explain shows it on each.
$ shc constraint set --where 'location=learn/home' --reason 'prod stays at home'shc: [X409255CNEMPT] where location=learn/home at tenant leaves no node: prod/a2/prod, bound by where location=learn/home at tenant:prod & where tier=edge at deploy:prod:a2:prod$ shc constraint set --where 'location=learn/home|tier=edge' --reason 'prod stays at home or on the edge'...$ shc constraint ls...$ shc constraint ls --label location=learn/home...$ shc constraint explain -s a2...$ shc constraint set --where 'rack=r1' --prefer 'tier=core' --scope deployment -s a4 --reason 'pin a4'...$ shc constraint ls...$ shc constraint clear --where --prefer --scope deployment -s a4...$ shc constraint clear --where...$ shc constraint ls --all...A selector can be stored under a name and used as @name in any rule.
$ shc node selector set core 'tier=core' --scope cluster --reason 'the core nodes'NAME corescope clustertenant -selector tier=coreset-by localupdated 2026-11-06 17:25:46reason the core nodesnodes home01 home03used by -$ shc node selector lsNAME SCOPE TENANT SELECTOR SET-BY UPDATED REASONcore cluster - tier=core local 2026-11-06 17:25:46 the core nodes$ shc node selector ls --all...$ shc node selector show coreNAME corescope clustertenant -selector tier=coreset-by localupdated 2026-11-06 17:25:46reason the core nodesnodes home01 home03used by -$ shc node ls --where '@core&rack=r1'NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTERhome03 healthy ready active learn learn/home ok 0.1.47 voter no yesChanging a deployment’s rule can move it. --plan shows what would move,
--yes does it, and shc ls shows where it went. A rule that is to outlive
the selector spells the labels out.
$ shc update a1 --where 'tier=core&rack!=r1' --planrelocation plan for prod/a1/prod placement: home01 is the only node its rules, condition and capacity leave; every node it may use is full of cpu by the commitment ledger; it asks for its app's own limit, which reserves nothing (SHC-2738), so it binds anyway replicas: nginx r0 moves home03 -> home01 volumes: none durable data: 0 B to carry downtime: about 30s$ shc update a1 --where 'tier=core&rack!=r1' --yesrelocation plan for prod/a1/prod placement: home01 is the only node its rules, condition and capacity leave; every node it may use is full of cpu by the commitment ledger; it asks for its app's own limit, which reserves nothing (SHC-2738), so it binds anyway replicas: nginx r0 moves home03 -> home01 volumes: none durable data: 0 B to carry downtime: about 30s✔ relocated deployment "a1" to home01$ shc ls --where stack=a1STACK TENANT ENV APP STATUS NODEa1 prod prod /root/learn/cluster/hello running home01$ shc node selector rm core --scope cluster -y✔ removed selector core at clusterA lease puts an end date on a deployment: when it runs out the deployment
is uninstalled. prod is protected, so renewing one there takes --force;
clear makes the deployment permanent again.
$ shc lease show a1...$ shc lease renew a1 --ttl 72h --force...$ shc lease show a1...$ shc lease clear a1...shc clone copies a deployment under a new name, placed by the source’s
rules plus a --where or --prefer of its own. The app ladder clones;
this page only names the placement flags.
$ shc clone a1 a7 --where '@learn/home' --prefer rack=r1 --dry-run--scale changes on update too. One replica per location, then remove
a4 and a5; keep a1, a2 and a3 for the next page. Each uninstall takes a
safety backup first, a5’s from the nodes its replicas moved to.
$ shc update a5 --scale nginx=1@home,1@far --yesupdating deployment "a5"[a5] Healthy 1/1✔ nginx healthysource: /root/learn/cluster/hello, replayed from the deployment's persisted source (path)the rollout of prod/a5/prod to v1:sha256:ab8847ced04b6926719804aa753e45970a07746726a75957d832d27a7901106a finished$ shc ls --where stack=a5STACK TENANT ENV APP STATUS NODESa5 prod prod /root/learn/cluster/hello running far01, home02shc exec, shc logs and shc volume ls take the same --where to pick
their deployment by selector instead of by name. Every deployment on this
ladder is named with -s, so the selector form is not typed.
$ shc exec --where stack=a5 -- hostname$ shc logs --where stack=a5 -n 5$ shc volume ls --where stack=a5Remove a4 and a5. uninstall backs a deployment up before it removes it,
and this cluster has no backup repository until Repositories
sets one, so that backup would refuse: --no-backup removes them without one.
$ shc uninstall a4 --no-backup -yuninstalling deployment "a4"[a4] Complete 3/3✔ remove from home01✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "a4"$ shc uninstall a5 --no-backup -y...The group verbs alone print their usage. shc lease is a deployment’s
TTL, set with --ttl on install or update; nothing on this ladder expires.
$ shc constraint$ shc node selector$ shc lease