Skip to content
SHC Docs

Clone and rename

Layer 11. Lifecycle. Lifecycle

The clone module copies a deployment, relocates one, and renames the stack axis. The running unit is the deployment.

  • clone: Service.Clone copies a deployment to a new name, on the same node or another.
  • relocation: Service.Move places a deployment on another node. The operator runs shc update --where (modules/clone/relocate.go).
  • rename: Service.Rename changes the stack axis name in place, for a deployment that runs as one compose project. One that runs as replica projects is renamed by the move’s backup and recover instead (SHC-2319): its replicas and their volumes are named for the deployment on every node that holds one, and nothing renames them in place.

All three are unusually stateful: each touches the database, the vault, the filesystem (deployment/app dirs, volume mounts), the container runtime, the scheduler, and the backup cache in one atomic-feeling operation that can survive partial failure.

Source: modules/clone/service.go. The public type is Service.

  1. Preflight: resolve target scope, detect fast-path eligibility, validate runtime/node/storage, build the rename map for multi-deployment clones, and reject up-front conflicts.
  2. Consistency snapshot: take backups of the source deployments into a temp staging directory, with a shared consistency_id so a multi-deployment clone is restorable as a group.
  3. State transition: run the phases for clone, relocation, or rename, with events emitted between phases.
  4. Rollback: on failure before the target is healthy, tear down any partially-installed target and restart the sources.
  5. Group manifest: when cloning more than one deployment (via --all-connections), pack the per-deployment .bak archives into a single .bkg group archive so the result is restorable as a unit.

Service exposes:

func (s *Service) Clone(ctx context.Context, req StackCloneRequest) (CloneResult, error)
func (s *Service) Move(ctx context.Context, req StackMoveRequest) (MoveResult, error)
func (s *Service) Rename(ctx context.Context, source, target, environment string) (RenameResult, error)
flowchart LR
preflight --> backup --> recover --> cleanup["cleanup temp"]
recover -- "on error" --> rollback["rollback: cleanup_partial_target"]
PhaseWhat it does
preflightResolve source, target scope, rename map; reject X404600CLNSRC, X409600CLNCOL or X400600CLNCON if invalid; then place the copy through the fence gate (see below)
backupCreate one .bak per deployment under <staging_dir>/clone/<operation id>; a kept archive rests into the deployment’s backups dir labelled pre-move; pack into .bkg if more than one deployment; raises X500602CLNBKP on failure
recoverrecoverPhase restores each deployment from its .bak
rollbackOn failure after backup, cleanupPartialTarget removes the partial target

Events emitted: V200600CLNPRE → V200601CLNBKP → V200603CLNRCV → A200600STKCLN (success) or V500600CLNRLB + A400600CLNFAL (failure). The full topic list lives in the generated event reference.

The source is not stopped during a clone; it stays running. The backup is the point of consistency, not a stop-the-world lock.

Phase machine: a move (relocation or rename)

Section titled “Phase machine: a move (relocation or rename)”
flowchart TB
preflight --> fastpath{"fast path?"}
fastpath -- yes --> rename --> done
fastpath -- no --> backup --> stop --> recover --> uninstall --> cleanup["cleanup temp"]
uninstall -- "on error" --> targetup{"target_up?"}
targetup -- yes --> raise["raise; target kept, source needs manual cleanup"]
targetup -- no --> rollback["cleanup_partial_target + restart_stopped_sources"]

The rollback step raises X500601CLNROL if rollback itself fails.

A move collapses to a rename when the preflight determines all four of:

  • same tenant
  • same environment
  • same node
  • name actually changes

Emits A200601STKMOV with fast_path=true. No backup, no uninstall, no container restart of the deployment itself, just the rename machinery below.

PhaseWhat it does
backupSame as clone: consistency snapshot
stopStop the source deployment(s) and every deployment transitively connected via plugs/sockets (app.graph.get_connected_stacks). Returns the list of stopped source deployments so rollback can restart them.
recoverInstall + restore the target on the new scope
uninstallTear down the source. Once target_up=True, an uninstall failure is logged but the exception still propagates; SHC never deletes the source unless the target is confirmed healthy.

The asymmetry between clone and move is deliberate: clone can tolerate a partial target because the source is untouched; move must treat the transition window as critical and roll back aggressively until the target is confirmed up.

Rename is a single non-rollbackable operation (there’s nothing to back up; it’s all in-place renames). It does the following under a best-effort try/except:

  1. Stop the source deployment.
  2. Rename volumes: _rename_volumes renames the Docker volumes from {tenant}_{old_name}_* to {tenant}_{new_name}_* using docker volume create + rsync + docker volume rm (volumes cannot be renamed natively by the Docker API).
  3. Rename deployment dir: paths.deployment_dir(tenant, old, env) → paths.deployment_dir(tenant, new, env).
  4. Rename app dir: paths.app_dir(tenant, old, env) → new.
  5. Update the DeploymentModel: stack.name = new_name and flush.
  6. Rename schedules: every ScheduleModel.stack_name = old → new.
  7. Rename vault secrets: every ref+vault://…?scope=stack (and by extension deployment-scoped) key under the old stack name is re-keyed to the new one.
  8. Rename backup cache: paths.backup_cache_dir(tenant, old, env) → new, so subsequent backups stay incremental-compatible.
  9. Restart the deployment under its new name.

Emits A200602STKRNM on success, A400602RNMFAL on failure.

If step 2 or 3 crashes mid-operation, the source is left in an inconsistent state; the operator is expected to use shc doctor / restore from backup to recover. Rename is therefore gated by the CLI to require an explicit confirmation when there are running containers.

Setting all_connections=True expands the operation set from [source] to the transitive closure of deployments connected via plugs/sockets (app.graph.get_connected_stacks).

The preflight builds a rename_map: {old_name → new_name} so each connected deployment’s stack name is known up-front. For deployments whose target stack name collides with something already installed, _generate_unique_name appends -1, -2, … up to 100, then raises X409601CLNAUF if no slot is free.

Without all_connections, a clone/move that would break an existing integration across nodes is rejected with X400600CLNCON. Same-node clones are always allowed because the integration hostnames resolve identically.

When len(stacks) > 1, _backup_phase writes each .bak as normal and then builds a BKGArchive, a simple tar-of-tars with a manifest listing the individual backups’ consistency_id. The .bkg is included in the result’s backup_ids for operators to pass to shc backup restore --group, recreating the entire clone set from a single file.

See flow: backup/restore for the .bak/.bkg on-disk layout.

_preflight raises the first applicable error:

CodeReason
X404600CLNSRCsource stack doesn’t exist in the current tenant
X409600CLNCOLtarget (tenant, name, env) already exists (clones and cross-scope moves)
X404607CLNNODa relocation’s settled node is not in the DB or cluster (never a clone: a clone names no node)
X400600CLNCONsource has integrations that would break without --all-connections
X409601CLNAUF--all-connections rename couldn’t find a free target name

A clone names no node. Once the checks above pass, preflight asks the fence gate an install is placed by (Providers.Placement, wired to fence.Service.Admit) with Carry set: the copy is a new deployment that takes the source deployment’s own rules plus the ones the clone states. The node the gate answers is the node the recovery restores on, and the rules are recorded on the copy only once the clone has succeeded. A copy that keeps connections outside the cloned set is held to the source’s node as a request rule, and every other member of an --all-connections set is admitted on the primary’s node by its own source’s rules. The clone route refuses a body that carries node or node_id with X400647CLNNOD.

And computes four booleans:

sameTenant := targetTenant == source.TenantName
sameEnv := targetEnv == source.Environment
sameNode := targetNode == source.NodeID
nameChanging := targetName != source.Name
fastPathEligible := isMove && sameTenant && sameEnv && sameNode && nameChanging
CodeMeaning
V200600CLNPREpreflight completed
V200601CLNBKPbackup phase completed
V200602CLNUNIsource uninstall completed (move only)
V200603CLNRCVtarget recovery (reinstall + restore) completed
V500600CLNRLBrollback triggered
A200600STKCLNclone succeeded
A200601STKMOVmove succeeded (carries fast_path: bool)
A200602STKRNMrename succeeded
A400600CLNFALclone failed
A400601MOVFALmove failed
A400602RNMFALrename failed
CodeRaised when
X404600CLNSRCsource stack not found
X404607CLNNODa relocation’s target node does not exist
X400647CLNNODa clone request body named a node
X409600CLNCOLtarget name already exists at target scope
X409601CLNAUFauto-unique-naming exhausted (100 suffixes tried)
X400600CLNCONcross-node clone/move would orphan an integration
X500601CLNROLrollback itself failed (source and target both may be unhealthy)
X500602CLNBKPbackup phase failed

The 11 errors declared in modules/clone/errors.go cover the remaining validation/internal cases. See reference/errors for the full list.

  • CLI: shc clone (see reference/cli/clone), shc rename, and the relocation shc update --where runs when new rules exclude the deployment’s node (see reference/cli/relocate).
  • HTTP: modules/clone/router.go exposes:
    • POST /api/method/shc.stack.clone
    • POST /api/method/shc.stack.relocate
    • POST /api/method/shc.stack.rename