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.Clonecopies a deployment to a new name, on the same node or another. - relocation:
Service.Moveplaces a deployment on another node. The operator runsshc update --where(modules/clone/relocate.go). - rename:
Service.Renamechanges 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.
Responsibilities
Section titled “Responsibilities”- 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.
- Consistency snapshot: take backups of the source deployments
into a temp staging directory, with a shared
consistency_idso a multi-deployment clone is restorable as a group. - State transition: run the phases for clone, relocation, or rename, with events emitted between phases.
- Rollback: on failure before the target is healthy, tear down any partially-installed target and restart the sources.
- Group manifest: when cloning more than one deployment (via
--all-connections), pack the per-deployment.bakarchives into a single.bkggroup archive so the result is restorable as a unit.
Entry points
Section titled “Entry points”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)Phase machine: clone
Section titled “Phase machine: clone”flowchart LR preflight --> backup --> recover --> cleanup["cleanup temp"] recover -- "on error" --> rollback["rollback: cleanup_partial_target"]| Phase | What it does |
|---|---|
preflight | Resolve source, target scope, rename map; reject X404600CLNSRC, X409600CLNCOL or X400600CLNCON if invalid; then place the copy through the fence gate (see below) |
backup | Create 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 |
recover | recoverPhase restores each deployment from its .bak |
rollback | On 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.
Fast path
Section titled “Fast path”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.
Slow path phases
Section titled “Slow path phases”| Phase | What it does |
|---|---|
backup | Same as clone: consistency snapshot |
stop | Stop 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. |
recover | Install + restore the target on the new scope |
uninstall | Tear 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.
Phase machine: rename
Section titled “Phase machine: rename”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:
- Stop the source deployment.
- Rename volumes:
_rename_volumesrenames the Docker volumes from{tenant}_{old_name}_*to{tenant}_{new_name}_*usingdocker volume create+ rsync +docker volume rm(volumes cannot be renamed natively by the Docker API). - Rename deployment dir:
paths.deployment_dir(tenant, old, env)→paths.deployment_dir(tenant, new, env). - Rename app dir:
paths.app_dir(tenant, old, env)→new. - Update the DeploymentModel:
stack.name = new_nameand flush. - Rename schedules: every
ScheduleModel.stack_name = old→new. - Rename vault secrets: every
ref+vault://…?scope=stack(and by extensiondeployment-scoped) key under the old stack name is re-keyed to the new one. - Rename backup cache:
paths.backup_cache_dir(tenant, old, env)→new, so subsequent backups stay incremental-compatible. - 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.
Several deployments (all_connections)
Section titled “Several deployments (all_connections)”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.
Group backup format (.bkg)
Section titled “Group backup format (.bkg)”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 rules
Section titled “Preflight rules”_preflight raises the first applicable error:
| Code | Reason |
|---|---|
X404600CLNSRC | source stack doesn’t exist in the current tenant |
X409600CLNCOL | target (tenant, name, env) already exists (clones and cross-scope moves) |
X404607CLNNOD | a relocation’s settled node is not in the DB or cluster (never a clone: a clone names no node) |
X400600CLNCON | source 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.TenantNamesameEnv := targetEnv == source.EnvironmentsameNode := targetNode == source.NodeIDnameChanging := targetName != source.NamefastPathEligible := isMove && sameTenant && sameEnv && sameNode && nameChangingEvents
Section titled “Events”| Code | Meaning |
|---|---|
V200600CLNPRE | preflight completed |
V200601CLNBKP | backup phase completed |
V200602CLNUNI | source uninstall completed (move only) |
V200603CLNRCV | target recovery (reinstall + restore) completed |
V500600CLNRLB | rollback triggered |
A200600STKCLN | clone succeeded |
A200601STKMOV | move succeeded (carries fast_path: bool) |
A200602STKRNM | rename succeeded |
A400600CLNFAL | clone failed |
A400601MOVFAL | move failed |
A400602RNMFAL | rename failed |
Errors
Section titled “Errors”| Code | Raised when |
|---|---|
X404600CLNSRC | source stack not found |
X404607CLNNOD | a relocation’s target node does not exist |
X400647CLNNOD | a clone request body named a node |
X409600CLNCOL | target name already exists at target scope |
X409601CLNAUF | auto-unique-naming exhausted (100 suffixes tried) |
X400600CLNCON | cross-node clone/move would orphan an integration |
X500601CLNROL | rollback itself failed (source and target both may be unhealthy) |
X500602CLNBKP | backup phase failed |
The 11 errors declared in modules/clone/errors.go cover the
remaining validation/internal cases. See
reference/errors for the full list.
What clone does not own
Section titled “What clone does not own”- Backup/restore file format:
.bak/.bkg/BackupManifestlive in the backup module andflow: backup/restore. - Deployment start, stop, and exec; those verbs are in the stack module.
- Install; recovery installs through the app module.
- Integration resolution: plug and socket wiring after the target comes up is the app module.
CLI / API surface
Section titled “CLI / API surface”- CLI:
shc clone(see reference/cli/clone),shc rename, and the relocationshc update --whereruns when new rules exclude the deployment’s node (see reference/cli/relocate). - HTTP:
modules/clone/router.goexposes:POST /api/method/shc.stack.clonePOST /api/method/shc.stack.relocatePOST /api/method/shc.stack.rename
Related
Section titled “Related”- Flow: clone: walkthrough of a relocation
- Backup module: the consistency primitive
- Stack module: the lifecycle primitives
- App graph: integration topology queried by preflight