40 lines
2.2 KiB
Markdown
40 lines
2.2 KiB
Markdown
|
# INTENT
|
||
|
|
|
||
|
|
## Why this repository exists
|
||
|
|
|
||
|
|
Operators should be able to carry out real IT administration and operation tasks
|
||
|
|
by following a guided interface instead of a document. Raw runbooks fail in the
|
||
|
|
same ways every time: the operator loses their place, pastes the wrong value,
|
||
|
|
skips a verification, or records nothing. This repository provides the
|
||
|
|
runbook-tutorial engine and user interface that presents a runbook as a
|
||
|
|
sequence of parameterized steps with visible state, gates, copyable commands,
|
||
|
|
verification and rollback, and non-secret evidence of what actually happened.
|
||
|
|
|
||
|
|
## Direction
|
||
|
|
|
||
|
|
- **One engine, many packs.** The engine is generic. The runbooks themselves
|
||
|
|
are *runbook packs* that live in a `runbooks/` directory of the repository
|
||
|
|
that owns the procedure. A pack stays next to the system it operates, so its
|
||
|
|
owner can change both together. This repository owns no operational content
|
||
|
|
beyond examples and its own conformance packs.
|
||
|
|
- **Existing runbooks keep working.** The NetKingdom security bootstrap console
|
||
|
|
predates this repository. Its guided flow is carried across through a legacy
|
||
|
|
adapter first and migrated into the pack format only where that pays off.
|
||
|
|
- **Parameters, not copies.** A runbook declares its parameters; the engine
|
||
|
|
renders commands with the operator's values and never asks for secrets.
|
||
|
|
- **Evidence over assertion.** A step is done when its declared check has
|
||
|
|
passed and its outcome is recorded. A runbook that was never run is labelled
|
||
|
|
unexercised, following the attended-procedure standard.
|
||
|
|
- **Never a secret vault.** The engine does not collect, store, log or
|
||
|
|
transmit secret values. It shows the command; the operator runs it.
|
||
|
|
- **Guide, not executor by default.** Steps are run by the operator. Any
|
||
|
|
automated execution is opt-in per step, explicit, and audited.
|
||
|
|
|
||
|
|
## Relationship to other repositories
|
||
|
|
|
||
|
|
- `net-kingdom` provides the first runbook pack (security bootstrap) and the
|
||
|
|
operator tutorials, and the console this engine grows out of.
|
||
|
|
- Each repo that wants guided operation adds `runbooks/<pack>/` and follows the
|
||
|
|
pack specification published here.
|
||
|
|
- `state-hub` records workplans; this repo does not become a task tracker.
|