docs: rewrite the bannered legacy operator guides for the Go stack#508
Merged
Conversation
Replace 18 Python/Docker-era operator guides + runbooks (bannered legacy in #505) with accurate Go-era docs for the single-binary + PostgreSQL + systemd + Kensa stack. Authored via a multi-agent sweep under a hard anti-fabrication rule: every command/endpoint/flag/path verified against the code; capabilities absent in rc.5 (Prometheus metrics, horizontal scaling, openwatch backup/restore, migrate down, API rate limiting, scan-execution endpoints) marked not-implemented rather than invented. Refresh .secrets.baseline for placeholder credentials in the rewritten docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Replaces the 18 Python/Docker-Compose-era operator guides and runbooks that #505 bannered as legacy with accurate Go-era documentation for the current stack: one
openwatchbinary serving the API + embedded UI on:8443, PostgreSQL-only, systemd, native RPM/DEB, Kensa engine.How (and the guardrail)
Authored by a multi-agent sweep under a hard anti-fabrication rule: each agent verified every command, endpoint, flag, and path against the code (
cmd/,internal/,api/openapi.yaml,packaging/, the systemd unit,install_guide.md) before writing it. Anything the old guide covered that does not exist in the rc.5 binary is marked "not yet implemented", never invented.(Run in batches of 4 — a single 16-wide agent burst was tripping the API's transient request-rate throttle.)
Files
.github/workflows/README.md,docs/architecture/KENSA_INTEGRATION.mdHonestly marked "not yet implemented" (verified absent)
Prometheus
/metrics+ bundled monitoring stack; horizontal API scaling + a packaged worker systemd unit;openwatch backup/restoresubcommands (docs usepg_dump/pg_restore);migrate down; API-layer rate limiting; scan-execution endpoints; distributed tracing.Review done before committing
I verified, not just trusted the agents:
/api/v1path the docs mention exists inopenapi.yaml, or is in a "not implemented" section (scans).openwatchsubcommands (serve/worker/migrate/create-admin/check-config) are used as commands;backup/restoreare explicitly called out as non-existent.roles.gen.go(dropped the 6 fabricated Python roles)..secrets.baselinerefreshed for placeholder credentials (allCHANGE_ME-style, verified).Separate, pre-existing (not in this PR)
docs/guides/SCANNING_AND_COMPLIANCE.md(active-fixed in #505, on main) presents/api/v1/scans/kensa/as a live command, but that endpoint isn't inopenapi.yamlyet — worth a follow-up fix.