Skip to content
SHC Docs

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.

~/learn/cluster/hello/compose.yaml
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.

home01
$ shc install ~/learn/cluster/hello -s a1 --where node=home03 --label owner=learn
installing 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.

home01
$ shc install ~/learn/cluster/hello -s a2 --where location=learn/far --label owner=learn
shc: [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=learn
installing 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.

home01
$ shc install ~/learn/cluster/hello -s a3 --where '@learn/home' --prefer rack=r1 --label owner=learn
installing 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=learn
installing deployment "a4"
[a4] Healthy 1/1
✔ nginx healthy
✔ installed deployment "a4"
$ shc ls
STACK TENANT ENV APP STATUS NODE
a1 prod prod /root/learn/cluster/hello running home03
a2 prod prod /root/learn/cluster/hello running far01
a3 prod prod /root/learn/cluster/hello running home03
a4 prod prod /root/learn/cluster/hello running home01

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.

home01
$ shc install ~/learn/cluster/hello -s a5 --scale nginx=2@home,1@far --where 'location=learn/home|tier=edge' --label owner=learn
installing deployment "a5"
[a5] Healthy 1/1
✔ nginx healthy
✔ installed deployment "a5"
home01
$ shc ls --where owner=learn
STACK TENANT ENV APP STATUS NODES
a1 prod prod /root/learn/cluster/hello running home03
a2 prod prod /root/learn/cluster/hello running far01
a3 prod prod /root/learn/cluster/hello running home03
a4 prod prod /root/learn/cluster/hello running home01
a5 prod prod /root/learn/cluster/hello running far01, home02, home03

shc constraint explain prints every rule that shaped a deployment and the nodes it leaves. --what-if-node asks about one node.

home01
$ shc constraint explain -s a3
deployment prod/a3/prod docker movability free priority normal
running on home03
status 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.

home01
$ 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.

home01
$ shc node selector set core 'tier=core' --scope cluster --reason 'the core nodes'
NAME core
scope cluster
tenant -
selector tier=core
set-by local
updated 2026-11-06 17:25:46
reason the core nodes
nodes home01 home03
used by -
$ shc node selector ls
NAME SCOPE TENANT SELECTOR SET-BY UPDATED REASON
core cluster - tier=core local 2026-11-06 17:25:46 the core nodes
$ shc node selector ls --all
...
$ shc node selector show core
NAME core
scope cluster
tenant -
selector tier=core
set-by local
updated 2026-11-06 17:25:46
reason the core nodes
nodes home01 home03
used by -
$ shc node ls --where '@core&rack=r1'
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTER
home03 healthy ready active learn learn/home ok 0.1.47 voter no yes

Changing 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.

home01
$ shc update a1 --where 'tier=core&rack!=r1' --plan
relocation 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' --yes
relocation 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=a1
STACK TENANT ENV APP STATUS NODE
a1 prod prod /root/learn/cluster/hello running home01
$ shc node selector rm core --scope cluster -y
✔ removed selector core at cluster

A 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.

home01
$ 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.

explained, not walked: the app ladder's clone page types the clone itself
$ 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.

home01
$ shc update a5 --scale nginx=1@home,1@far --yes
updating deployment "a5"
[a5] Healthy 1/1
✔ nginx healthy
source: /root/learn/cluster/hello, replayed from the deployment's persisted source (path)
the rollout of prod/a5/prod to v1:sha256:ab8847ced04b6926719804aa753e45970a07746726a75957d832d27a7901106a finished
home01
$ shc ls --where stack=a5
STACK TENANT ENV APP STATUS NODES
a5 prod prod /root/learn/cluster/hello running far01, home02

shc 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.

explained, not walked: every deployment on this ladder is named with -s
$ shc exec --where stack=a5 -- hostname
$ shc logs --where stack=a5 -n 5
$ shc volume ls --where stack=a5

Remove 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.

home01
$ shc uninstall a4 --no-backup -y
uninstalling 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.

explained, not walked: the group verb alone prints its usage
$ shc constraint
$ shc node selector
$ shc lease

Next: Cordon, drain, undrain, uncordon.