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.
Hold a deployment to a place
Section titled “Hold a deployment to a place”shc install postgres --where 'location=hetzner/hel1' # anywhere in hel1shc install postgres --where 'node=hel-02' # this node onlyshc 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.
Relocate with shc update --where
Section titled “Relocate with shc update --where”shc update postgres --where 'node=hel-03' --planshc 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 service with more than one replica
Section titled “A service with more than one replica”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 -> home01The 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 landedA deployment that runs on that one node alone still moves as a whole, every replica with it.
A rule the package brings
Section titled “A rule the package brings”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... finishedoutside: replica web-r1 of prod/guestbook/prod is bound to far01, which its deployment rule where location=learn/home removes X200195FNCOUTrelocation plan for prod/guestbook/prod replicas: web r1 moves far01 -> home01relocate 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.
What happens to volumes
Section titled “What happens to volumes”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.
| Volume | Source node alive | Source node dead |
|---|---|---|
| Durable, can attach to the target | reattached | reattached |
| Durable, cannot attach to the target | copied | refused by name, or restored with --restore-from-backup |
| Scratch | recreated empty | recreated 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.
A dead node
Section titled “A dead node”shc update postgres --where 'node=hel-03' --restore-from-backupWhen 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.
Rename with shc rename
Section titled “Rename with shc rename”shc rename nextcloud cloud --dry-runshc rename nextcloud cloud --yes && shc update cloudA 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.