Locations and labels
Every node carries labels. SHC derives most of them: node, location at
every level of its path, cloud, runtime, control-plane. The operator
adds the rest. A label describes a node; the placement page turns labels
into rules.
$ shc label lsLABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTScloud=learn derived 4 4 no 0 0control-plane system 3 3 no 0 0location=learn derived 4 4 no 0 0location=learn/far derived 1 1 no 0 0location=learn/home derived 3 3 no 0 0tier=core operator 1 1 no 0 0tier=edge operator 1 1 no 0 0warning: control-plane has no spare, fewer than four nodes$ shc label ls --key location -vLABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS GRANTED MEMBERS BACKUP-REPO DESCRIPTION CREATEDlocation=learn derived 4 4 no 0 0 - far01,home01,home02,home03 - - 2026-11-06 17:06:36location=learn/far derived 1 1 no 0 0 - far01 - - 2026-11-06 17:10:48location=learn/home derived 3 3 no 0 0 - home01,home02,home03 - - 2026-11-06 17:06:36A location is a path. learn holds both sites, and learn/far is one of
them. A label value has properties of its own: a description, a reservation
and, for a location, its off-site backup repository. Setting one never adds
the label to a node.
$ shc label set location=learn/far --description 'the far site'LABEL location=learn/farsource deriveddescription the far sitereserved nogranted to -backup repo -created 2026-11-06 17:10:48
NODESNODE CONDITION AVAILABILITY SOURCEfar01 ready active derived
CONSTRAINTS none
DEPLOYMENTS none$ shc label show location=learn/farLABEL location=learn/farsource deriveddescription the far sitereserved nogranted to -backup repo -created 2026-11-06 17:10:48
NODESNODE CONDITION AVAILABILITY SOURCEfar01 ready active derived
CONSTRAINTS none
DEPLOYMENTS noneA node’s own labels come from shc node label. key=value sets one value
per key and key! removes it. --dry-run says what would change.
$ shc node label far01arch=amd64cloud=learnendpoint=publiclocation=learn,learn/farnode=far01runtime=dockerstorage=node:node-5e52a5a4986dtier=edge$ shc node label home03 tier=core rack=r1 --dry-runhome03; dry run, nothing changed + tier=core + rack=r1$ shc node label home03 tier=core rack=r1home03 + tier=core + rack=r1$ shc node label home02 rack=r2home02 + rack=r2$ shc node label home02 rack!home02 - rack=r2A selector picks nodes by their labels: key=value, key!=value, &, |,
parentheses, and @<location> for a location at any level.
$ shc node ls --where tier=coreNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTERhome01 healthy ready active learn learn/home ok 0.1.47 voter yes yeshome03 healthy ready active learn learn/home ok 0.1.47 voter no yes$ shc node ls --where 'tier=core&rack!=r1'NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTERhome01 healthy ready active learn learn/home ok 0.1.47 voter yes yes$ shc node ls --where '@learn/far|rack=r1'NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTERfar01 healthy ready active learn learn/far ok 0.1.47 replica no nohome03 healthy ready active learn learn/home ok 0.1.47 voter no yesA reserved label value keeps work off its nodes unless a rule names the
value. A service’s own where, such as --where web:tier=edge, lets in only
that service. Reserve tier=edge, so nothing lands on far01 by accident.
$ shc label set tier=edge --reserved --description 'edge nodes take only what names them'LABEL tier=edgesource operatordescription edge nodes take only what names themreserved yesgranted to any tenantbackup repo -created 2026-11-06 17:10:49
NODESNODE CONDITION AVAILABILITY SOURCEfar01 ready active join
CONSTRAINTS none
DEPLOYMENTS none$ shc label ls --source operator -vLABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS GRANTED MEMBERS BACKUP-REPO DESCRIPTION CREATEDrack=r1 operator 1 1 no 0 0 - home03 - - 2026-11-06 17:23:28tier=core operator 2 2 no 0 0 - home01,home03 - - 2026-11-06 17:06:39tier=edge operator 1 1 yes 0 0 any tenant far01 - edge nodes take only what names them 2026-11-06 17:10:49$ shc label ls --node far01 --allLABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTScloud=learn derived 4 4 no 0 0endpoint=public derived 4 4 no 0 0location=learn derived 4 4 no 0 0location=learn/far derived 1 1 no 0 0node=far01 derived 1 1 no 0 0storage=node=node-5e52a5a4986d derived 1 1 no 0 0tier=edge operator 1 1 yes 0 0Bare --reserved leaves the value open to any tenant that writes a rule
naming it. Name the tenants, as in --reserved acme,beta, and only they can.
A rule from any other tenant is refused, and one that reached the store
anyway counts for nothing, which shc constraint explain says. A tenant name
that doesn’t exist is refused, and so is a grant while a deployment outside it
names the value. --reserved alone opens it back up to any tenant.
Keep tier=core, rack=r1 and the reservation on tier=edge for the next
page.
shc label alone prints its usage.
$ shc labelNext: Placement rules.