Labels and selectors
New line, in development. This page describes SHC as it is on the
devbranch, not the released product. See The new line.
A label is a key and one or more values on a node, or on a replica. Node selectors and service selectors are expressions over those labels in one grammar, and they are separate kinds. A node selector picks nodes: --where keeps the nodes that match, and --prefer ranks the ones that match and leaves the rest eligible. Named node selectors and constraints store node selectors. A service selector picks replicas of its own deployment and gives them a name.
Setting a node’s labels needs platform:manage (shc.label.set in modules/fence/router.go). Reading them needs it too. The characters inside other flag values are CLI symbols. Moving a deployment after a rule change is Relocating a deployment.
Checked against shc next d1cc800882, which pins ce 0ca02485c9, on 2026-10-04.
Where a node gets its labels
Section titled “Where a node gets its labels”shc node label <node> prints every label the node carries. SHC writes the derived ones. An operator writes the rest with the same command.
TestANodeCarriesTheLabelsSHCDerives (tests/_ce/modules/fence/labels_test.go) is the list the reconcile writes for a node that has a cloud, a location, a public address and a control-plane membership: node, location at every level, cloud, runtime, endpoint and control-plane. storage is the same kind of label when a store’s reach includes the node (Derive in modules/fence/derive.go). volume, lb and ip are reserved names for reach, not labels a node carries (reservedLabelKeys in modules/fence/fenceapi/labels.go).
| Key | Value | Code |
|---|---|---|
node | The node’s name, or its id when it has no name. | nodeLabel |
location | Every level of the location path. | LocationFenceIDs |
cloud | Who runs the node, lowercased. Empty means no cloud label. | Derive |
runtime | The runtime the node’s record names. A node whose runtime cannot be read carries no runtime label, so no runtime selector matches it. | nodeLabels |
arch | The node’s CPU architecture in Go/OCI spelling (amd64, arm64), as its daemon records it. A node that has not recorded one has no arch label. | nodeLabels, NodeFact.Architecture |
gpu | Each GPU kind the node’s runtime can pass to a container: nvidia (an NVIDIA GPU with docker’s NVIDIA container toolkit, a podman CDI spec for nvidia.com/gpu, or incus) and dri (a render node under /dev/dri). Several kinds are several values. A node with no GPU it can pass has no gpu label. | nodeLabels, hostplat.DetectGPUs, hostplat.GPUKinds |
storage | The name of each store whose reach includes the node, or the store’s id when it has no name. Several stores are several values. | Derive |
endpoint | public, and only when the node has a public address. | publicEndpoint |
control-plane | true, for a member of the control-plane fence. | labelOf |
arch and gpu are properties the daemon detects, so an operator cannot write them (X400188LBLKEY). They select like any other label (--where arch=arm64, --prefer gpu=nvidia). An app does not need them to get the right node: requires.architectures in its app.yaml and a GPU its compose asks for (runtime: nvidia, gpus:, a deploy.resources.reservations.devices entry with capabilities: [gpu], a device under /dev/dri) hold every replica to a node that has them, and shc deployment explain names what each other node lacks (ReasonArchitecture, ReasonGPU in core/placement).
A location path is cloud/location when both are set, the location token alone when there is no cloud, and unknown when the node reports no location (placement.LocationPath, LocationFenceOf). The label value is the path after location:. A node whose path is hetzner/hel1 also carries hetzner, so location=hetzner matches it (LocationFenceIDs, and the labels test above).
An operator key is a lowercase letter and then up to 31 of a-z, 0-9 and -. A value starts with a lowercase letter or digit and then up to 62 of a-z, 0-9, . and -. One key holds one value, so setting it replaces the value the node had (customKind and customName in modules/fence/ids.go, parseLabelEdits). control-plane=true adds the node to the control-plane fence, and control-plane! takes it off. The fence keeps at least one member. Leaving one or two members warns control-plane keeps N nodes, fewer than three. Leaving none is refused (controlPlaneEdit). --dry-run prints the change and writes nothing.
shc node label n1shc node label n1 tier=gold rack=r12shc node label n1 tier!The selector
Section titled “The selector”core/selector parses the expression. A term is key=value or key!=value. A value is compared whole. A label can hold several values: key=value matches when one of them is that value, and key!=value matches when none is, including a thing with no such label. & is and, | is or, and parentheses group. Whitespace between the parts is ignored. A bare ! is refused: the parser’s words are there is no not: say it in the term, key!=value.
& binds tighter than |, because parser.or reads & groups (selector.go). cloud!=hetzner & arch=arm64 | arch=amd64 is (cloud!=hetzner & arch=arm64) | arch=amd64. Parentheses are how the or sits inside the and: cloud!=hetzner & (arch=arm64 | arch=amd64).
A key starts with a letter and then holds letters, digits and . _ - /.
Two forms name a place:
| Form | Meaning |
|---|---|
@edge | A term. A location path, or a selector stored under that name. |
node=@(app=pg) | A value. The nodes of the replicas the inner selector matches. node!=@( ) is apart from them. location=@( ) is their locations. |
@( ) with no key in front of it is refused. Other flags have their own place grammar. --scale accepts location names and <n>/<kind>, but not @(selector). --scale postgres=2/location runs two replicas in every location, on different nodes where the location has two or more. A location added later gets its two with no new value. For a published port, @(selector) selects listening nodes; @<name> resolves as a connection or a location, not a stored selector. See Published ports.
The empty selector matches everything. A selector Parse cannot read is X400240SELSYN, naming the byte it stopped at, counted from 0. A place the evaluator cannot answer is X400241SELRES. The limits are 4096 bytes, 32 levels of parentheses and named places, 4096 terms, and 65536 bytes once named places are written out (TestASelectorIsBoundedInLengthAndDepth). The printed form has no whitespace, and parentheses only around an | that sits inside an & (Expr.String).
@( ) matches a replica by tenant, environment, stack and app. A service replica also carries service and ordinal (replicaLabels). The deployment the rule is being read for is not one of those replicas (seenBy). A cluster rule sees every tenant’s replicas. A tenant or deployment rule sees that tenant’s (TestReplicaTenantDoesNotSeeAnother, TestReplicaDoesNotCountItself).
Where and prefer
Section titled “Where and prefer”shc install and shc update take repeatable --where and --prefer flags (ReadServicePlacement). --where keeps the nodes a term matches (placement.FormWhere). --prefer ranks the survivors that match and does not narrow (FormPrefer). Each value has one of four forms:
| Value | Effect |
|---|---|
<selector> | Set the deployment-wide rule for services without their own. '' clears only this default. |
<service>:<selector> | Set that service’s or group’s own rule. |
<service>! | Drop that service’s own rule and fall back to the deployment-wide rule. |
! | Drop every rule of this flag on the deployment. |
Leaving a flag out keeps its rules. A service’s own rule replaces the deployment-wide rule of the same form; a service’s --where doesn’t replace its --prefer. A pod member’s name places the whole pod, and the stored rule names the pod. A group rule binds every member replica.
shc update myblog --where location=hel1 --where db:location=nbg1shc update myblog --where 'db!'The first command keeps services without their own where in hel1 and places db in nbg1. The second drops only db’s where, so it uses the deployment-wide where again.
On update, a where or prefer change that moves the deployment prints a plan and asks, unless --yes. --plan prints the plan and stops. A plan that moves nothing lets the update continue. After a confirmed move, the rest of that update does not send --where or --prefer again (RelocateForRules).
Cluster and tenant constraints still bind every service (Rule.AppliesTo). The app’s own shc.yaml where terms are folded into every where row, including service rows (DeploymentRules.Apply). A stored constraint where that leaves no node is refused when it is set (X409255CNEMPT) and again at admission (X409171FNCEMP).
A reserved label value admits a replica only when a where that binds the replica names the value (engineRules). A service’s own where that names it admits that service alone. Its siblings keep the reserved avoid unless the deployment-wide where they fall back to, or a cluster or tenant where, names it too.
Ambiguous entries are refused: location:hel1 reads as a label typed with a colon (X400244SELCLN), db: lacks a selector (X400245SELEMP), and a:b:location=x names more than one service (X400246SELONE). A malformed <service>:<selector> entry is X400247SELENT. Two bare selectors in one command are X400248SELDUP; join their terms with &. Different selectors for the same service or pod are X400249SELCON. An unknown service or group is X400257SELNAM.
zone=eu:1 stays a deployment-wide selector because the colon is inside its value. db: location=nbg1 is accepted as one quoted argument. Service names may contain -, _ and .. Clone and constraint flags take bare selectors only; service forms there return X400250SELSVC.
A deployfile accepts a string or a list of these strings:
where: - location=hel1 - "db:location=nbg1"prefer: "web:tier=gold"Each entry supports interpolation. The file states the whole set, so leave out an unwanted rule instead of writing ! or db!; removal markers are refused. - db: location=nbg1 is a YAML map and is refused with a reminder to write "db:location=nbg1". On update, the file’s argv starts each form with --where ! or --prefer !, followed by that form’s entries, so omitted rules are removed.
--fence, --avoid, --location, --admit, --colocate and --rules-exact are still registered, hidden, and refused, and so are --rule and --node on a command that doesn’t own a flag by that name. Passing one is X400242SELFLG, and the error names the --where to write instead (RegisterGoneFlags).
shc install nextcloud --where 'location=hetzner/hel1' --prefer 'tier=gold'shc update myblog --where 'location=hetzner/hel1' --planshc update myblog --where ''shc node ls takes the same selector:
shc node ls --where 'location=hetzner/hel1&tier=gold'Named node selectors
Section titled “Named node selectors”shc node selector stores a node selector under a name, at cluster scope or at one tenant. Tenant is the default, and the tenant is the global -t. A tenant sees the cluster’s names and its own, and cannot define a name the other scope already has (modules/fence/named.go). @<name> is that selector wherever a selector is written, including --where and --prefer.
A name is 1 to 63 of a-z, 0-9, ., _ and -, starting with a letter or digit. A location path contains /, so it cannot be a name. An empty selector is refused. A stored selector cannot contain @( ). ls lists the cluster’s names and the current tenant’s. ls --all lists every tenant and needs platform:manage. show prints the selector, the nodes it matches now, and the selectors that name it. rm asks unless -y, and refuses while another selector names it.
shc node selector set edge 'tier=edge&runtime=docker' --scope clustershc node ls --where '@edge&cloud!=hetzner'shc node selector lsshc node selector show edgeshc node selector rm edge --scope cluster -yService selectors
Section titled “Service selectors”A service selector is a name plus a selector over the labels of its own deployment’s replicas, declared in the app under x-shc-service-selectors (shc.yaml service_selectors). Each one is a VIP and a DNS name whose backends are the replicas that match now: postgres: role=primary:1 follows the one replica whose live label says primary. It reads service facts only, service, ordinal, group, member, compose labels and live labels. location and node are node selector terms and are refused there. It’s never written inline: there is no CLI for it and no deployfile key. The grammar, route and scope are in x-shc directives.
An --expose targets a service selector the way it targets a service, for a hostname and for an L4 port: --expose 5432=postgres publishes whichever replica matches now. One over labels other than group has no ports of its own, so the port is the target’s :port or the outside port, and some service of the app must declare it. See Published ports.
The old spellings are refused: x-shc-aliases with a hint naming x-shc-service-selectors, the shc.yaml aliases key, and shc selector with a hint naming shc node selector.
Four cases
Section titled “Four cases”Each is a combination of the primitives on this page. The design and what is still being built are in the placement proposal.
Nodes only runners and tests may use. A reserved value is the taint, and the --where naming it is the toleration.
shc node label ci-01 pool=cishc label set pool=ci --reservedshc install gitlab-runner --where pool=ciSpread everywhere, traffic to the closest location. One replica in each leaf location, and in-cluster names route nearest.
shc install web --scale web=1/locationOne writer, replicas in every location. The app declares the writer and the readers, and the deployment says where they run.
x-shc-service-selectors: postgres: role=primary:1 postgres-ro: role=replicashc install postgres --where pool=db --scale postgres=1/location --expose 5432=postgresPort 5432 reaches the writer from outside, and after a failover it reaches the new one with no update. To keep the writer in one location, pin the members that may be elected with a node selector, --where 'postgres-1:location=hetzner/hel1', never in the service selector.
Full copies in two locations, flip between them. One deployment. The app says which sides exist, the deployment says where each runs, and a var says which side is live.
x-shc-service-selectors: app: side={{ active }}services: web-blue: { labels: { side: blue } } web-green: { labels: { side: green } }shc install app --where 'web-blue:location=home' --where 'web-green:location=hetzner/hel1'shc update app --var active=greenshc install nextcloud stays one command: no where, no prefer, scale 1, any ready node holding no reserved value.
Constraints
Section titled “Constraints”shc constraint stores a where or a prefer at cluster, tenant or deployment scope. Tenant is the default. A deployment scope also takes -s and -e (and the global -t). platform:manage sets a cluster constraint. A tenant’s tenant:manage sets that tenant and its deployments.
set --where replaces that scope’s where. set --prefer replaces its prefer. Both may be given. '' deletes that form, and a form not given is left alone. A where that leaves no node is refused. ls (alias list) lists the active tenant’s tenant and deployment constraints and the cluster’s. clear with neither --where nor --prefer clears both. Clearing a form that is not set is not an error.
shc constraint set --where 'location=hetzner/hel1' --scope cluster --reason 'data residency'shc constraint set --where 'node=hel-01' --prefer 'tier=gold' --scope deployment -s wiki -t acmeshc constraint ls -t acmeshc constraint clear --where --scope deployment -s wiki -t acmeA location and its prefixes
Section titled “A location and its prefixes”@eu, @eu/hel and @eu/hel/dc2 are each a place. A node at eu/hel/dc2 is in all three, because its location label holds every prefix (TestALocationPathIsANamedPlaceAtEveryLevel, selector.Location). @eu/hel/dc2 stands for location=eu/hel/dc2. It matches a node at that path or under it, and it does not match a node that only shares a shorter prefix.
location=@(stack=db) copies the deepest location path of the replicas labelled stack=db, not a prefix above that path (valuesAt, ownLocations). A node under that path still matches, because it carries the path as one of its location values. TestReplicaLocationIsOwnPath puts db on hel1 and the where also leaves hel1/rack1, not a sibling location.
What the commands refuse
Section titled “What the commands refuse”These are summaries of the refusals, not their exact output templates.
Labels
Section titled “Labels”| Code | Refusal |
|---|---|
X400188LBLKEY | The key is one SHC writes, so no operator sets it. |
X400189LBLSYN | The entry is not key=value or key!. |
X400190LBLDUP | The request names one key twice. |
X404154FNCNOD | The node is not in the cluster. |
X409157FNCSTR | The edit would strand running deployments outside their eligible set. Move or drain them first. |
X409192LBLMOV | The node’s labels changed while the request ran. Nothing was written. |
X409177FNCCPE | The edit would empty the control-plane fence. |
X404153FNCNOF | control-plane=true and the control-plane fence is missing. |
X501395ROLCAP | The node cannot join the control plane: its host lacks the voter capability. |
X409136PUBOVR | The edit would put two deployments on the same port and protocol on one node (LabelOverlapGuard). |
Selectors
Section titled “Selectors”| Code | Refusal |
|---|---|
X400240SELSYN | The text is not a selector. The error names the byte. |
X400241SELRES | The selector names a place that cannot be answered. |
X400242SELFLG | A gone placement flag was passed. |
X400260SELNAM | The name is not 1 to 63 of a-z, 0-9, ., _, -, starting with a letter or digit. |
X400261SELSCP | The scope is not cluster or tenant, or it does not fit (a cluster scope takes no tenant, a tenant scope needs one). |
X409262SELLOC | The name is a location a node is in. |
X409263SELSHD | The name is already defined at the other scope. |
X409264SELCON | The name is a connection. |
X400265SELEMP | The named node selector is empty. |
X400266SELGRP | A named node selector cannot use @( ). |
X400267SELVIS | The selector names a place that is not visible here. |
X400268SELCYC | The selector names itself. |
X409269SELUSE | Another node selector names this one. Remove that one first. |
X404260SELNOF | The node selector was not found. |
X409265SELCHG | Named node selectors changed while this one was being written. Nothing was written. |
X403261SELAUT | A cluster node selector, or ls --all, needs platform:manage. A tenant node selector needs tenant:manage in that tenant. |
Constraints and admission
Section titled “Constraints and admission”| Code | Refusal |
|---|---|
X400000BADREQ | shc constraint set was given neither --where nor --prefer. |
X400253CNSCOP | --scope is not cluster, tenant or deployment. |
X400254CNSFIT | The tenant, stack and environment do not fit the scope. |
X403163RULGLB | A cluster constraint needs platform:manage. |
X409255CNEMPT | The where leaves no node. |
X409256CNSCHG | Constraints changed while this was being set. |
X404161RULNOF | A constraint the caller may not see reads as not found. |
X409171FNCEMP | Admission: the rules, resources and node conditions leave no node. |
X409179PLCPND | Nodes match the rules and none of them fits the deployment now. Nothing was installed. |
X409172FNCNOD | The named or recorded node sits outside the eligible set. shc update --where relocates it. |
X409180FNCMOV | An install over an existing deployment names another node. A rule change relocates. |
X409183FNCNDY | A where depends on derived labels the reconciler has not written yet. |
X400187FNCRTM | Every node the rules leave runs a runtime that refuses the service. |
X400186FNCSHR | --scale puts pods that share a volume on a node’s own disk into sets with no node in common. |
X400182FNCPOD | The pod’s replicas cannot be asked for as its --scale states them. |
X400298FNCFIT | A service asks for more of a resource than every node’s capacity. Nothing was written. |
X400251FNCGON | shc fence create, rm, add-node and remove-node are gone. An operator’s node set is a label. |