Skip to content
SHC Docs

Labels and selectors

New line, in development. This page describes SHC as it is on the dev branch, 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.

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

KeyValueCode
nodeThe node’s name, or its id when it has no name.nodeLabel
locationEvery level of the location path.LocationFenceIDs
cloudWho runs the node, lowercased. Empty means no cloud label.Derive
runtimeThe runtime the node’s record names. A node whose runtime cannot be read carries no runtime label, so no runtime selector matches it.nodeLabels
archThe 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
gpuEach 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
storageThe 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
endpointpublic, and only when the node has a public address.publicEndpoint
control-planetrue, 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.

Terminal window
shc node label n1
shc node label n1 tier=gold rack=r12
shc node label n1 tier!

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:

FormMeaning
@edgeA 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).

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:

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

Terminal window
shc update myblog --where location=hel1 --where db:location=nbg1
shc 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).

Terminal window
shc install nextcloud --where 'location=hetzner/hel1' --prefer 'tier=gold'
shc update myblog --where 'location=hetzner/hel1' --plan
shc update myblog --where ''

shc node ls takes the same selector:

Terminal window
shc node ls --where 'location=hetzner/hel1&tier=gold'

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.

Terminal window
shc node selector set edge 'tier=edge&runtime=docker' --scope cluster
shc node ls --where '@edge&cloud!=hetzner'
shc node selector ls
shc node selector show edge
shc node selector rm edge --scope cluster -y

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.

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.

Terminal window
shc node label ci-01 pool=ci
shc label set pool=ci --reserved
shc install gitlab-runner --where pool=ci

Spread everywhere, traffic to the closest location. One replica in each leaf location, and in-cluster names route nearest.

Terminal window
shc install web --scale web=1/location

One 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=replica
Terminal window
shc install postgres --where pool=db --scale postgres=1/location --expose 5432=postgres

Port 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 } }
Terminal window
shc install app --where 'web-blue:location=home' --where 'web-green:location=hetzner/hel1'
shc update app --var active=green

shc install nextcloud stays one command: no where, no prefer, scale 1, any ready node holding no reserved value.

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.

Terminal window
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 acme
shc constraint ls -t acme
shc constraint clear --where --scope deployment -s wiki -t acme

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

These are summaries of the refusals, not their exact output templates.

CodeRefusal
X400188LBLKEYThe key is one SHC writes, so no operator sets it.
X400189LBLSYNThe entry is not key=value or key!.
X400190LBLDUPThe request names one key twice.
X404154FNCNODThe node is not in the cluster.
X409157FNCSTRThe edit would strand running deployments outside their eligible set. Move or drain them first.
X409192LBLMOVThe node’s labels changed while the request ran. Nothing was written.
X409177FNCCPEThe edit would empty the control-plane fence.
X404153FNCNOFcontrol-plane=true and the control-plane fence is missing.
X501395ROLCAPThe node cannot join the control plane: its host lacks the voter capability.
X409136PUBOVRThe edit would put two deployments on the same port and protocol on one node (LabelOverlapGuard).
CodeRefusal
X400240SELSYNThe text is not a selector. The error names the byte.
X400241SELRESThe selector names a place that cannot be answered.
X400242SELFLGA gone placement flag was passed.
X400260SELNAMThe name is not 1 to 63 of a-z, 0-9, ., _, -, starting with a letter or digit.
X400261SELSCPThe scope is not cluster or tenant, or it does not fit (a cluster scope takes no tenant, a tenant scope needs one).
X409262SELLOCThe name is a location a node is in.
X409263SELSHDThe name is already defined at the other scope.
X409264SELCONThe name is a connection.
X400265SELEMPThe named node selector is empty.
X400266SELGRPA named node selector cannot use @( ).
X400267SELVISThe selector names a place that is not visible here.
X400268SELCYCThe selector names itself.
X409269SELUSEAnother node selector names this one. Remove that one first.
X404260SELNOFThe node selector was not found.
X409265SELCHGNamed node selectors changed while this one was being written. Nothing was written.
X403261SELAUTA cluster node selector, or ls --all, needs platform:manage. A tenant node selector needs tenant:manage in that tenant.
CodeRefusal
X400000BADREQshc constraint set was given neither --where nor --prefer.
X400253CNSCOP--scope is not cluster, tenant or deployment.
X400254CNSFITThe tenant, stack and environment do not fit the scope.
X403163RULGLBA cluster constraint needs platform:manage.
X409255CNEMPTThe where leaves no node.
X409256CNSCHGConstraints changed while this was being set.
X404161RULNOFA constraint the caller may not see reads as not found.
X409171FNCEMPAdmission: the rules, resources and node conditions leave no node.
X409179PLCPNDNodes match the rules and none of them fits the deployment now. Nothing was installed.
X409172FNCNODThe named or recorded node sits outside the eligible set. shc update --where relocates it.
X409180FNCMOVAn install over an existing deployment names another node. A rule change relocates.
X409183FNCNDYA where depends on derived labels the reconciler has not written yet.
X400187FNCRTMEvery 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.
X400182FNCPODThe pod’s replicas cannot be asked for as its --scale states them.
X400298FNCFITA service asks for more of a resource than every node’s capacity. Nothing was written.
X400251FNCGONshc fence create, rm, add-node and remove-node are gone. An operator’s node set is a label.