8.3 Decommission

Included from Basic tier

After this you can: retire a node safely — export, delete, destroy — and restore it if you must.

Before you start — tick each one:

• Lesson 8.2 — Definitions under change control (opschain learn 8.2)

In the GUI: Export subtree… on a node's actions menu is step 1; a deleted subtree vanishes from the Estate tree and the list's Show deleted view lists it with Restore and Destroy… (the manifest preview, then a typed-path confirmation); Audit history under Governance keeps every api:nodes:* event the drill emitted, after the destroy included.

Retiring estate is a three-step drill, each step deliberate: export → delete → destroy. The verbs live under opschain admin nodes and need the node's deletable permission (lesson 7.2); archiving (opschain nodes update <path> --archived=true, lesson 1.2) remains the soft option when the estate is only resting.

1. Export first

The archive is one credential-free zip: the subtree's definitions (nodes with their template coordinates, templates and versions as git coordinates, git remotes without their credentials, workflows and triggers in the same interchange YAML as lesson 8.2, the properties and settings values — --with-history adds their version trails), the run history as JSONL, and the full event trail, always — the audit is the point.

opschain admin nodes export acme --out acme-export.zip --with-history

exported /projects/acme to acme-export.zip

Log lines and artifact blobs stay on the server; the manifest records their counts and the blob digests, so you know exactly what did not travel. The CLI verifies the downloaded zip opens before it reports success. Prove the zip is credential-free: unzip -p acme-export.zip | grep -i -c 'password\|secret\|token' finds nothing of yours.

2. Delete — reversible

Without --confirm the verb previews; confirmed, a soft delete hides the node and everything beneath it from every list, route and screen:

opschain admin nodes delete acme --confirm

deleted project /projects/acme — hidden and reserved; `opschain admin nodes restore acme` undoes this

The path stays reserved (recreating it is refused by name), new work is refused, and automation under it goes quiet — a trigger elsewhere that targets the deleted subtree settles its firings failed with the reason. Nothing is removed. The server refuses by name while changes or workflow runs are still active beneath — a delete never cancels work; you do, explicitly. Change your mind any time:

opschain admin nodes restore acme

restored project /projects/acme

Restore is the exact inverse: the subtree is listed again, unchanged.

3. Destroy — not reversible

Destroy is valid only on a node you already soft-deleted (two deliberate steps, always). Without --confirm it prints the honest per-type manifest of what would be removed and removes nothing:

opschain admin nodes destroy acme

would destroy /projects/acme and every row beneath it (events excepted — the audit persists):
  changes                  214
  nodes                    7
  steps                    1931
  …
re-run with --confirm to destroy permanently

Confirmed, the cascade removes every stored row beneath the node and releases the artifact blobs nothing else references — except the events table, which is never touched:

opschain admin nodes destroy acme --confirm

destroyed /projects/acme — removed:
  changes                  214
  nodes                    7
  steps                    1931
  …
events were not touched; the audit trail persists

Deleted, restored and destroyed each emit their own api:nodes:* event (the destroy event carries the manifest), so the decommission itself is part of the audit that outlives it — opschain events still answers the subtree's full trail afterwards.

4. The archive comes back as definitions

admin nodes import replays an export's definitions through the same authorised create endpoints a GUI edit uses — history never merges into a live instance; the archive remains the record of what ran. An existing path is refused; --into <new-path> recreates the subtree elsewhere (trigger scopes inside it remap too). Credentials never travel, so the import names the git remotes whose secrets you must re-enter:

opschain admin nodes import acme-export.zip --into acme_restored

imported the definitions of /projects/acme into /projects/acme_restored
  git_remotes              2
  nodes                    7
  templates                3
  template_versions        9
  …
history was not imported — the archive remains the record; re-enter any git remote credentials

opschain git-remotes update acme_restored/origin --password-prompt

Check yourself

• What is the difference between deleting and destroying a node, and what does restore bring back?
• Which table does destroy never touch, and what in the archive never travels?

What you learned

• Export is the lasting record: definitions, run history and the full event trail, never a credential.
• Delete hides and reserves; it refuses while work is active beneath, and restore undoes it exactly.
• Destroy needs a prior delete, previews its manifest, and leaves the events table alone.
• Import recreates definitions through the ordinary authorised endpoints; secrets are re-entered by hand.

Next: lesson 8.4 — The posture ladder (opschain learn 8.4), or back to your track (opschain learn).