Skip to content
SHC Docs

Flow: relocate

Layer 11. Lifecycle. Layer page.

A relocate keeps the deployment’s identity and finishes the stored render on the target. The target does not render. The leader does.

shc clone copies to a new name (modules/clone/commands/main.go, Service.Clone). shc rename changes the name in place (Service.Rename in ce modules/clone/service.go) for a deployment that runs as one compose project. A deployment that runs as replica projects is renamed by the move’s backup and recover under the new name, then the source uninstall, and its own placement rules go to the new name first (SHC-2319). Neither is the relocate path below.

sequenceDiagram
participant CLI
participant Clone
participant Leader
participant Target
CLI->>Clone: POST /api/method/shc.stack.relocate plan
Clone->>CLI: replicas, volumes, downtime
CLI->>Clone: relocate with the confirmed node
Clone->>Leader: clone.finish_stored_render
Leader->>Leader: FinishStoredMove
Note over Target: does not render
Target->>Target: start replicas from the stored spec

shc update calls this when --where or --prefer leaves the deployment outside the new rules (ce modules/app/commands/update_relocate.go). The handler is POST /api/method/shc.stack.relocate.

Service.Relocate places the deployment under the new rules (ce modules/clone/relocate.go). A plan that moves nothing returns without a move. A plan names the replicas, what happens to each volume, the durable bytes, and an expected downtime. --plan stops there. A confirmed run refuses a plan that no longer moves what was confirmed (X409657RELCNF).

Durable volumes are copied while the source node is alive. Scratch volumes are recreated empty. A dead source whose durable volumes cannot be reattached is refused unless the request sets --restore-from-backup.

The finish is FinishStoredMove on the leader. If the caller is not the leader, it sends clone.finish_stored_render and requires finished: true (ce daemon/clone_stored_render.go). FinishStoredMove starts each live replica beside the source, at the next incarnation, from the stored render (ce modules/app/stored_render.go). The target does not render.

Sources: ce modules/clone/relocate.go, modules/clone/service.go, modules/clone/commands/main.go, modules/app/commands/update_relocate.go, daemon/clone_stored_render.go, modules/app/stored_render.go.