180 lines
10 KiB
Markdown
180 lines
10 KiB
Markdown
# System Administrator Lifecycle User Story
|
|
|
|
## Story
|
|
|
|
> As a system administrator, I can execute one shell command that downloads a
|
|
> verified GovOPlaN distribution and starts a completely configured Core control
|
|
> plane without optional modules. In the WebUI I can browse compatible signed
|
|
> module releases, select the modules for this installation, and follow every
|
|
> download, validation, migration, installation, activation, and health-check
|
|
> step. When an update is available, I can review its impact and confirm it.
|
|
>
|
|
> I can add API or worker replicas on containers or other servers without
|
|
> copying mutable local state. I can operate development, test, and production
|
|
> systems, transfer a versioned configuration through the WebUI, undo an applied
|
|
> configuration version, test an update in one environment, and then apply the
|
|
> same immutable update recipe to another environment.
|
|
|
|
This is a product-level story owned by the GovOPlaN platform rather than by an
|
|
individual domain module. It joins installation, module lifecycle, operations,
|
|
configuration packages, and release provenance into one administrator journey.
|
|
The canonical backlog item is
|
|
[GovOPlaN #13](https://git.add-ideas.de/GovOPlaN/govoplan/issues/13).
|
|
|
|
## Terms
|
|
|
|
- **Core control plane:** the smallest bootable distribution: Core API, Core
|
|
WebUI, PostgreSQL, Redis, installer worker, migration runner, and durable
|
|
storage configuration. No optional GovOPlaN module package is installed.
|
|
- **Bootstrap administrator:** a single-use, time-limited installation identity
|
|
that may access only first-run and module-lifecycle functions. It is retired
|
|
when the selected identity/access configuration becomes healthy.
|
|
- **Module release:** an immutable, signed package plus manifest, compatibility
|
|
contract, migrations, WebUI contribution, checksums, and SBOM references.
|
|
- **Configuration revision:** an immutable, schema-versioned export of
|
|
non-secret system/module settings, policies, compositions, and secret
|
|
references. Secret values are never exported.
|
|
- **Update recipe:** the reviewed, immutable plan containing exact Core/module
|
|
versions, configuration revision, migration order, preflight results,
|
|
maintenance/drain requirements, health checks, and permitted rollback or
|
|
forward-recovery actions.
|
|
|
|
## Acceptance journeys
|
|
|
|
### One-command first installation
|
|
|
|
1. The administrator runs one documented command on a supported host.
|
|
2. The bootstrapper verifies a signed distribution manifest before executing or
|
|
starting downloaded artifacts.
|
|
3. It checks container/runtime, ports, storage, entropy, memory, architecture,
|
|
and connectivity requirements; generates deployment-local secrets with
|
|
restrictive permissions; and never prints them.
|
|
4. It starts PostgreSQL, Redis, Core API/WebUI, one installer worker, and the
|
|
migration runner. Readiness does not pass until migrations and durable
|
|
dependencies are healthy.
|
|
5. It prints the local URL and one-time bootstrap credential. Re-running the
|
|
command is idempotent and shows or repairs the existing installation rather
|
|
than creating another identity or database.
|
|
6. No optional module is installed or enabled at this point.
|
|
|
|
### Module selection, installation, and update
|
|
|
|
1. Core reads an approved signed catalog and trusted keyring through the shared
|
|
outbound-network policy.
|
|
2. The WebUI shows available, installed, compatible, blocked, withdrawn, and
|
|
update-available releases with their channel, provenance, contracts,
|
|
migrations, permissions, configuration requirements, and release notes.
|
|
3. Selecting modules produces a dependency/compatibility plan before any
|
|
mutation. The administrator can amend the selection or confirm the plan.
|
|
4. Installation executes durably in a worker. The UI receives persisted step
|
|
state and can reconnect without losing progress.
|
|
5. Package signature/checksum, version alignment, contract closure, migration
|
|
graph, configuration schema, and health checks are mandatory gates.
|
|
6. Remote artifacts are acquired by a deployment-owned downloader that permits
|
|
approved origins, pins the validated connection peer, enforces size and time
|
|
limits, and verifies signature/checksum before making a local immutable
|
|
artifact available. `pip`, `npm`, archive tools, and any compatibility Git
|
|
importer then run without unrestricted network access. A restricted-network
|
|
profile can satisfy the same contract through operator-prefetched artifacts.
|
|
7. A failed or interrupted operation reaches a visible retry, forward-recovery,
|
|
rollback, or manual-intervention state. It never reports success merely
|
|
because the initiating request returned.
|
|
8. An available update follows the same preview and confirmation path. Exact
|
|
repeated requests are idempotent.
|
|
|
|
### Horizontal scaling
|
|
|
|
1. API, WebUI, installer, scheduler, and ordinary worker roles are stateless
|
|
with respect to local container disks. Durable state uses PostgreSQL, Redis,
|
|
and configured shared file/object storage.
|
|
2. A documented command can add API or queue-specific worker replicas. The
|
|
default Compose profile supports local scale-out; an orchestrator profile
|
|
supplies equivalent health/readiness probes and rolling replacement.
|
|
3. Only one migration or module-lifecycle mutation may own the deployment lock,
|
|
while any healthy replica can serve read and normal domain traffic.
|
|
4. Workers announce identity, queues, software composition, heartbeat, and
|
|
drain state. Operators can see skew and safely retire a replica.
|
|
5. Sessions, throttling, idempotency, jobs, installer progress, and scheduled
|
|
work remain correct when requests move between replicas.
|
|
|
|
### Development, test, and production promotion
|
|
|
|
1. The administrator exports a configuration revision from development through
|
|
the WebUI. The package is versioned, checksummed, attributable, and contains
|
|
secret references or required-secret declarations, never secret values.
|
|
2. Test imports the package into a preview area. Core reports environment-bound
|
|
values, missing capabilities/secrets, compatibility changes, and the exact
|
|
apply plan.
|
|
3. Applying creates a new revision; the previous effective revision remains
|
|
addressable. Undo is a new audited revision that restores the earlier
|
|
configuration where contracts permit it.
|
|
4. After tests and health checks pass, Core emits an update recipe with exact
|
|
immutable release and configuration identifiers.
|
|
5. Production validates the recipe against its own environment, requires a new
|
|
confirmation, and executes the same ordered plan. Environment-specific
|
|
secret bindings and endpoints remain local.
|
|
6. Promotion never copies tenant/business data implicitly. Data migration,
|
|
anonymized fixtures, and backup/restore are separate explicit operations.
|
|
|
|
## Safety and governance requirements
|
|
|
|
- Catalogs, artifacts, recipes, and configuration revisions have signatures,
|
|
checksums, provenance, expiry/revocation semantics, and audit evidence.
|
|
- Catalog and artifact retrieval is not delegated to an unrestricted package
|
|
manager. Approved-origin and peer-pinned download, response bounds,
|
|
signature/checksum verification, extraction safety, offline installation, and
|
|
deployment egress policy form separate defenses.
|
|
- The installer has a dedicated narrow authority; normal domain permissions do
|
|
not imply host/package-management access.
|
|
- The UI distinguishes reversible configuration rollback from database or
|
|
package migrations that require forward recovery.
|
|
- Cluster-wide mutations use fencing/leases so an expired worker cannot later
|
|
commit a stale result.
|
|
- Update plans declare availability impact, worker draining, backup/restore
|
|
prerequisites, database compatibility windows, and post-change probes.
|
|
- Deployment profiles set secure headers, trusted proxies/hosts, body limits,
|
|
outbound-network policy, storage, TLS/cookie posture, and observability.
|
|
- Release publication requires aligned backend/frontend/manifest versions and
|
|
machine-readable dependency/SBOM provenance.
|
|
|
|
## Implementation slices
|
|
|
|
1. **Reproducible Core-only distribution.** Publish pinned multi-architecture
|
|
images, signed distribution manifest, Core-only Compose profile, bootstrap
|
|
preflight, generated secrets, readiness, and idempotent rerun/repair.
|
|
2. **First-run control plane.** Add the restricted bootstrap administrator,
|
|
one-time enrollment, initial catalog/keyring configuration, and retirement
|
|
after durable administrator access is established.
|
|
3. **Read-only online module directory.** Move the existing catalog and module
|
|
directory contracts into the installed Core WebUI with compatibility,
|
|
provenance, release-note, and update-state presentation.
|
|
4. **Durable module plan and install.** Reuse the existing installer queue,
|
|
locks, signed-package validator, rollback drill, and run evidence behind a
|
|
plan/confirm/progress UI. Add initial catalog-entry synthesis and artifact
|
|
acquisition where the current release console still assumes local sources.
|
|
5. **Safe module update.** Add drain/maintenance coordination, backup gate,
|
|
migration compatibility window, reconnectable progress, health verification,
|
|
retry/recovery, and update notification.
|
|
6. **Stateless replica profile.** Remove remaining local-runtime assumptions,
|
|
expose role-specific commands/images, implement worker registration/drain,
|
|
and prove multiple API and worker replicas against shared dependencies.
|
|
7. **Configuration revision model.** Define provider export/import schemas,
|
|
canonical serialization, secret references, validation/diff, immutable
|
|
revision storage, audit, apply, and undo-as-new-revision.
|
|
8. **Environment promotion and recipes.** Add source/target fingerprints,
|
|
preview, environment bindings, acceptance evidence, exact recipe generation,
|
|
signed transfer, and independently confirmed application.
|
|
9. **Operational proof.** Exercise interrupted installs, stale locks, unavailable
|
|
catalogs, revoked keys, failed migrations, replica loss, configuration undo,
|
|
and development-to-test-to-production promotion in release CI and target
|
|
drills.
|
|
|
|
## Explicit non-goals for the first distribution slice
|
|
|
|
- Shipping optional modules in the Core image.
|
|
- Exporting secrets or production business data with configuration.
|
|
- Pretending every schema migration can be reversed automatically.
|
|
- Building a proprietary orchestrator instead of supporting Compose and a
|
|
standard cluster scheduler through the same role/readiness contracts.
|
|
- Allowing the browser process to execute arbitrary shell commands.
|