Skip to content
SHC Docs

Relocating a deployment

A deployment never names a node. Where it may run is its --where, a selector over node labels, and the scheduler places it on a node that matches. There is no --node on shc install, shc deploy or shc recover, and there is no move verb: you relocate a deployment by changing its --where.

Terminal window
shc install postgres --where 'location=hetzner/hel1' # anywhere in hel1
shc install postgres --where 'node=hel-02' # this node only
shc install postgres --where 'location=hetzner/hel1 & tier!=spot' --prefer 'disk=nvme'

A selector is key=value and key!=value terms joined by & (and) and | (or), with parentheses to group. --where is a must: a node that does not match is never used. --prefer is a should: among the nodes --where leaves, the ones that match rank first, and none is ruled out. shc node label <node> lists a node’s labels.

shc constraint explain -s <deployment> shows the expressions in force and the nodes they leave, one step per & term. A deployment installed from a path on a node’s filesystem carries node=<that node> on its own, because no other node holds the package.

Terminal window
shc update postgres --where 'node=hel-03' --plan
shc update postgres --where 'node=hel-03'
shc update postgres --where 'node=hel-03' --yes

--where replaces the deployment’s whole expression, and --where '' clears it. The same holds for --prefer. A flag left out leaves what is stored.

When the new expression still matches the node the deployment runs on, the update records it and nothing moves. When it excludes that node, the update prints a plan and asks before anything is copied:

  • the replicas that move, and from which node to which;
  • each volume and what happens to it;
  • the durable data to carry;
  • the expected downtime.

--plan prints the plan and stops. --yes skips the question. Without a terminal and without --yes the update refuses rather than relocate unasked.

A deployment whose services run several replicas is judged replica by replica. The deployment itself stays on its node while that node is inside the rules; each replica the rules remove gets a node of its own, and the plan names it:

relocation plan for prod/guestbook/prod
placement: web r1: home01 is the first of 3 nodes that fit
replicas: web r1 moves far01 -> home01

The replicas the rules keep are not listed and are not touched. The move runs one replica at a time. A replica that mounts no volume is brought up on the new node beside its copy, which serves until the new one reads ready and is then retired. A replica that mounts a volume stops on its node, its volumes are copied or reattached, and it starts on the new node, since a volume has one writer. Each lands before the next one moves. A move that fails puts that replica back where it was and stops there. The last line names what moved and what did not; the replicas moved before it stay where they landed and keep serving, and the rule change is not recorded.

A rule that removes the deployment’s own node moves it the same way when its replicas run on more than one node. Each replica the rule removes moves on its own, the ones it keeps never stop, and once every one has landed the deployment’s own row moves to a node inside the rule. Nothing stops the deployment as a whole, and the plan names that node:

relocation plan for prod/guestbook/prod
placement: the deployment's row moves to home02: home02 is the first of 3 nodes that fit; api r0: home01 is the first of 3 nodes that fit; web r0: home03 is the first of 3 nodes that fit
replicas: api r0 moves far01 -> home01
web r0 moves far01 -> home03
deployment: its row moves far01 -> home02 once every replica has landed

A deployment that runs on that one node alone still moves as a whole, every replica with it.

A where: in the app’s shc.yaml is recorded by shc update <name> with no --where typed. The rollout that follows keeps every replica on its node, so a replica the new rule removes is named in the update’s own output:

the rollout of prod/guestbook/prod to v1:sha256:1209e888... finished
outside: replica web-r1 of prod/guestbook/prod is bound to far01, which its deployment rule where location=learn/home removes X200195FNCOUT
relocation plan for prod/guestbook/prod
replicas: web r1 moves far01 -> home01
relocate prod/guestbook/prod as planned? [y/N]

The update then prints the plan and asks, as a typed --where does; --yes moves them without asking. Without a terminal and without --yes the update has landed, the replica stays where the output says it is, and the line that names --yes is printed in place of the question.

A brought rule that removes the deployment’s own node is recorded the same way. The update names each replica on that node, and the plan moves them as a typed --where would: replica by replica with the row after them when the deployment runs on more than one node, as a whole when it runs on that one.

A volume the app’s backup.yaml keeps is durable. Every other volume is scratch. An app that ships no backup.yaml has every volume durable.

VolumeSource node aliveSource node dead
Durable, can attach to the targetreattachedreattached
Durable, cannot attach to the targetcopiedrefused by name, or restored with --restore-from-backup
Scratchrecreated emptyrecreated empty

Durable data is copied only while the node it is on is alive. A dead node is one the cluster registers unreachable and a fresh probe cannot reach.

Terminal window
shc update postgres --where 'node=hel-03' --restore-from-backup

When the source node is dead and a durable volume cannot be reattached on the target, the update is refused and names the volume. --restore-from-backup recovers the deployment on the target from its latest backup instead. What was written after that backup stays on the dead node.

--restore-from-backup is refused while the cluster does not call the source node dead, on --plan as on the run. The refusal gives the reason: the state the node is registered in, or the address where it answered a probe. A node that has just stopped is not called dead at once: shc node ls can read it unreachable some seconds before the relocation does. Run the update again then, or drop --restore-from-backup to move a deployment off a node that is alive with its data.

Terminal window
shc rename nextcloud cloud --dry-run
shc rename nextcloud cloud --yes && shc update cloud

A rename keeps the deployment in its tenant and environment. A deployment on one node stays on it. One whose replicas run on more than one node comes back with every replica on the node that runs the rename, and the plan names each replica and the node it runs on first. A rename does not re-render the ingress, so run shc update <name> with it, as one operation.