Flow: app uninstall
Layer 11. Lifecycle. Lifecycle
Step-by-step trace of shc uninstall <deployment>. The CLI sends the request
to shcd and refuses with X503738DMNREQ when it cannot reach the daemon. Source of truth is the
ce modules/app package:
router.go’s
startAsyncUninstall (the shared chokepoint behind both
POST shc.stack.uninstall and DELETE /api/resource/Stack),
service.go’s
Service.Uninstall (the state half), and
install_runner.go’s
ExecuteComposeDown (the teardown half, reached through
RunUninstallWithObserver). For multi-deployment teardown during
clone/move see uninstallPhase in
modules/clone/service.go, summarized at the end.
Uninstall is not transactional. Unlike install (which rolls back
on failure) and update (which reverts from a snapshot), the teardown
phase is a best-effort forward pass: most steps are individually
guarded, and a failure is logged but does not block later steps;
“user said delete this” should make progress even when parts of the
system are already broken. The exceptions are deliberate and sit at
the edges: the gates in Phase 0 refuse before anything is
mutated, and a managed-DNS release failure at the very end fails
the operation loud (X500979DNSRMV) instead of silently
stranding records.
Phase 0: synchronous gates (nothing mutated on refusal)
Section titled “Phase 0: synchronous gates (nothing mutated on refusal)”- Protected-deployment destroy guard.
GetProtectedon the resolved(tenant, stack, environment); a protected deployment refuses withX409001DEPROTbefore the backup gate, the state-row drop, and the async teardown. Unprotect first (shc unprotect). - Vdeployment discrimination. A name carrying the
<stack>/<instance>grammar is a vdeployment: it has no top-level deployment row, so it skips the deployment phases below and instead takes an uninstall claim (GateVdeploymentUninstall,removing+ this operation’s id) so an install racing underneath refuses symmetrically. Its teardown isUninstallVdeployment, dispatched insideExecuteComposeDown. - Pre-uninstall backup gate. The deployment row is read first
(
requireUninstallRow, same resolved coordinate): no row answersX404906STKNOFnaming the tenant and environment searched, and a store that cannot be read answers its own error, so a deployment that was never there is not reported as a failed backup. Only a row that was found reachesGateUninstallBackup, which backs the deployment up BEFORE any mutation; a backup failure aborts the whole uninstall here. The backup is a no-op when--no-backup, no hook wired, or no repo configured; the row check runs either way.
Phase 1: synchronous state drop (Service.Uninstall)
Section titled “Phase 1: synchronous state drop (Service.Uninstall)”-
Lookup ⇒
X404906STKNOFif absent. -
pre_uninstall/post_uninstallhooks (state-levelrunHook; best-effort, a failure never aborts). Status is set toremovingbetween them for any observer polling. -
Deployment row delete: the single deletion point. Dependent rows are NOT deleted by code: the ent schema (
ent/schema/deployment.go) declares the FK actions on the deployment’s edges, and the database does the rest when the row goes:Dependent table FK action service(and itscontainerrows, via the service edge)ON DELETE CASCADEhost_mapping,port_mappingON DELETE CASCADEintegration(as consumer AND as provider)ON DELETE CASCADEdeployment_node(the occupancy set)ON DELETE CASCADEvdeployment(instances this deployment hosts)ON DELETE CASCADEchild deploymentrows (tombstone self-ref)ON DELETE CASCADEbackupON DELETE SET NULL; backup rows outlive the deploymentscheduleno FK at all, purged by code in Phase 2 The in-memory repo (unit tests, non-durable mode) is not joined to the state map, so
Service.Uninstallsweeps its integration rows explicitly, a mirror of the cascade, not a second mechanism. -
Quota release (
recordQuotaDelete): drops the usage counters this deployment reserved on install. -
In-memory forget (
forgetStack): evicts the health snapshotshc statusreads; it is not DB-backed and has no other eviction path.
Phase 2: async teardown (ExecuteComposeDown, streamed over the operation’s SSE)
Section titled “Phase 2: async teardown (ExecuteComposeDown, streamed over the operation’s SSE)”- Protected guard again, at the destroyer.
RefuseIfProtectedre-checks off the manifest sidecar; a guard sited only at the callers covers only the callers someone remembered. With--data,RefuseIfAnyVdeploymentProtectedalso refuses if any hosted instance is individually protected (their sidecars live inside this deployment dir). - Manifest read. The persisted
manifest.jsonsupplies project name, runtime, hosts, integrations. Present-but-unreadable refuses (X500969DEPSTU) rather than destroying on a guess; missing means never-recorded, and the teardown proceeds best-effort against the conventional project name. pre_uninstallapp hook jobs: while the containers are still up, so service-context jobs (drains, deregistrations) have a live target. Best-effort.- Edge teardown. Every
-iedge’s authoredjobs.unintegrationruns: the consumer plug’s unwire, then the provider socket’s revoke. Best-effort; it cannot fail the uninstall. - Runtime teardown stops the deployment’s replica projects and runs
ComposeDownfor its runtime. Volumes are removed only with--data. Then a label-matched sweep (pruneOrphanComposeResources) catches stray networks (and, with--data, volumes). - Credential + role reaping.
revokeConnectionEdgesrevokes connection-minted sub-credentials this deployment owns (ownership-guarded;KeepCredentialsskips it;ce modules/app/install_runner.go), and the deployment’sstack:<name>Keycloak access role is reaped. Best-effort, loud on failure. - Ingress route file removal (
RemoveIngressRouteFile): local best-effort; the Traefik-host reconcile’s orphan sweep is the real cross-node cleanup. post_uninstallapp hook jobs: after the containers are down but BEFORE the rendered artifacts are removed (the job definitions still need to exist on disk). Service-context jobs are rejected; http/container jobs run.- Artifact removal. With
--datathe whole deployment dir goes (os.RemoveAll). Without it,removeRenderedArtifactskeepsmounts/(the data) andvdeployments/(per-instance state incl. protection mirrors) and removes everything else; a real teardown that a later reinstall of the same identity picks back up. - Managed-DNS release.
RetireDeploymentDNSlatches first (so the cluster reconcile cannot re-register records off the sidecar mid-teardown), thenDeleteDeploymentDNSRecordsremoves every record the deployment self-registered. The ONLY skip isKeepDNS(a same-key relocation;ce daemon/services_seams_stack.go). A failure here surfaces at the end of the teardown asX500979DNSRMV, the one loud tail. - Schedule purge.
SyncDeploymentCronswith an empty crons map removes everysource == "app"schedule row for the(tenant, stack, environment)tuple, leaving operator-created (user) rows alone. Schedule rows carry no deployment FK, so no cascade covers them; this in-process purge is the mechanism. - Lifecycle-config purge (
PurgeDeploymentLifecycleConfig): dropslease.expires_at/deployment.protectedconfig so a reinstall of the same identity cannot inherit a dead deployment’s expired lease. - Row purge tail (
PurgeStackRow): an idempotent re-delete of the deployment row plus a re-broadcast. The Phase-0 backup’s quiesce fallback may restart the deployment, and that restart’s re-register can land AFTER Phase 1 dropped the row; this sweeps the resurrected phantom regardless of which backup path ran.
Ordered uninstall of several deployments
Section titled “Ordered uninstall of several deployments”Teardown of several deployments (clone, tenant teardown) is driven by the
clone module: uninstallPhase in modules/clone/service.go asks
ComputeUninstallOrder (consumers come down before the providers they
depend on) and uninstalls one deployment per member. Two per-member preconditions are spent
immediately before each destructive call: the verify phase must have
OBSERVED that member’s target serving (refuseUnlessTargetProven,
X500629CLNDST) and the target must hold that member’s bytes
(refuseUnlessDataProven); a teardown reached by any path that did
not prove both refuses instead of proceeding.
Events
Section titled “Events”| Step | Event | Meaning |
|---|---|---|
| Uninstall success | A200101STKUNI | Deployment uninstalled |
| Protected refusal | X409001DEPROT | Deployment is protected |
| Manifest unreadable | X500969DEPSTU | Refuse rather than guess |
| DNS-release failure (loud tail) | X500979DNSRMV | Records may be stranded |
| Ordered: per-deployment progress / failure / summary | A200401STKUNO / A400401STKUOF / A200402STKUOC | declared in modules/app/events.go |
Contrast
Section titled “Contrast”| Install | Update | Uninstall | |
|---|---|---|---|
| Failure strategy | Rollback (reverse-order cleanup) | Revert (restore snapshot) | Gate first, then best-effort forward |
| What happens on mid-flight failure | Stack rolled back, user sees original error | Stack reverted to pre-update state | Logs accumulate; teardown proceeds (only the DNS tail fails loud) |
| What can leave zombies | Nothing (unless --no-rollback) | Nothing (revert itself can fail → failed) | External DNS (loud), external vault secrets, hook side-effects |