Skip to content
SHC Docs

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.

home01
$ shc label ls
LABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS
cloud=learn derived 4 4 no 0 0
control-plane system 3 3 no 0 0
location=learn derived 4 4 no 0 0
location=learn/far derived 1 1 no 0 0
location=learn/home derived 3 3 no 0 0
tier=core operator 1 1 no 0 0
tier=edge operator 1 1 no 0 0
warning: control-plane has no spare, fewer than four nodes
$ shc label ls --key location -v
LABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS GRANTED MEMBERS BACKUP-REPO DESCRIPTION CREATED
location=learn derived 4 4 no 0 0 - far01,home01,home02,home03 - - 2026-11-06 17:06:36
location=learn/far derived 1 1 no 0 0 - far01 - - 2026-11-06 17:10:48
location=learn/home derived 3 3 no 0 0 - home01,home02,home03 - - 2026-11-06 17:06:36

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

home01
$ shc label set location=learn/far --description 'the far site'
LABEL location=learn/far
source derived
description the far site
reserved no
granted to -
backup repo -
created 2026-11-06 17:10:48
NODES
NODE CONDITION AVAILABILITY SOURCE
far01 ready active derived
CONSTRAINTS
none
DEPLOYMENTS
none
$ shc label show location=learn/far
LABEL location=learn/far
source derived
description the far site
reserved no
granted to -
backup repo -
created 2026-11-06 17:10:48
NODES
NODE CONDITION AVAILABILITY SOURCE
far01 ready active derived
CONSTRAINTS
none
DEPLOYMENTS
none

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

home01
$ shc node label far01
arch=amd64
cloud=learn
endpoint=public
location=learn,learn/far
node=far01
runtime=docker
storage=node:node-5e52a5a4986d
tier=edge
$ shc node label home03 tier=core rack=r1 --dry-run
home03; dry run, nothing changed
+ tier=core
+ rack=r1
$ shc node label home03 tier=core rack=r1
home03
+ tier=core
+ rack=r1
$ shc node label home02 rack=r2
home02
+ rack=r2
$ shc node label home02 rack!
home02
- rack=r2

A selector picks nodes by their labels: key=value, key!=value, &, |, parentheses, and @<location> for a location at any level.

home01
$ shc node ls --where tier=core
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTER
home01 healthy ready active learn learn/home ok 0.1.47 voter yes yes
home03 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 VOTER
home01 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 VOTER
far01 healthy ready active learn learn/far ok 0.1.47 replica no no
home03 healthy ready active learn learn/home ok 0.1.47 voter no yes

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

home01
$ shc label set tier=edge --reserved --description 'edge nodes take only what names them'
LABEL tier=edge
source operator
description edge nodes take only what names them
reserved yes
granted to any tenant
backup repo -
created 2026-11-06 17:10:49
NODES
NODE CONDITION AVAILABILITY SOURCE
far01 ready active join
CONSTRAINTS
none
DEPLOYMENTS
none
$ shc label ls --source operator -v
LABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS GRANTED MEMBERS BACKUP-REPO DESCRIPTION CREATED
rack=r1 operator 1 1 no 0 0 - home03 - - 2026-11-06 17:23:28
tier=core operator 2 2 no 0 0 - home01,home03 - - 2026-11-06 17:06:39
tier=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 --all
LABEL SOURCE NODES READY RESERVED CONSTRAINTS DEPLOYMENTS
cloud=learn derived 4 4 no 0 0
endpoint=public derived 4 4 no 0 0
location=learn derived 4 4 no 0 0
location=learn/far derived 1 1 no 0 0
node=far01 derived 1 1 no 0 0
storage=node=node-5e52a5a4986d derived 1 1 no 0 0
tier=edge operator 1 1 yes 0 0

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

explained, not walked: the group verb alone prints its usage
$ shc label

Next: Placement rules.