docs: move the standalone runbook to its own home, sharpen the README to the shared contract#36
Merged
Merged
Conversation
Move the standalone runbook into its own published document: when to use standalone, quick start, installation, applying the configuration, systemd automation with the liveness healthcheck, and the self-update loop (prerequisites, supervision, rolling back), with the document's own reference list. The README keeps the shared contract; its slimming and the pointer section follow separately.
Dissolve the Host-specific values section, a leftover from the flat parameter surface: the uid facts (host data, no default, compile-time guard and the concerns that need it) move into the runner_account contract text, and the control-repository-path facts (host data, default, runtime catch by the self-update fetch and the healthcheck staleness assertion) into the standalone contract text.
Make explicit that packages.sources.manage and packages.install are independent layers, and name the two supported shapes on a host whose content platform (orcharhino, Foreman/Katello) serves the packages: platform-owned sources with module-installed packages, or platform-owned packages outright.
Move the remaining standalone material out of the README: the installation, apply-script, systemd-automation, self-update and rollback sections now live only in docs/standalone.md, and the host-local secret store (the file, the rationale, the editing procedure) moves there too. The Quick start is rewritten for the fleet path, a Standalone deployment pointer section follows the Operating model, the Operating-model bullet spells out the standalone/self-update layering, and the reference list is renumbered contiguously after the move.
The example host data now sets control_repository_path to the module default /opt/gitlab-runner-infra instead of a divergent /opt path; the spec asserting the example threads into the apply script follows.
examples/README.md now leads with fleet adoption (Puppetfile lines, the data/ layer, server-side tokens) and keeps the skeleton as the standalone complement, pointing at docs/standalone.md; the example host data gains a standalone-only banner on the standalone block and its comments point at the runbook.
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
1 participant
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.
Closes #16.
The README was serving two readers at once: the fleet consumer, who needs the configuration contract and nothing about host bring-up, and the standalone operator, who needs a full runbook. This PR gives each their own document: the README keeps the contract shared by every consumer and now leads with the fleet path, while the standalone bring-up and operations move to a new published runbook,
docs/standalone.md.README.mddocs/standalone.mdMoved to the runbook: installation, the apply script and manual applies, systemd automation with the liveness healthcheck, the self-update loop (prerequisites, the supervision it layers onto the healthcheck, rolling back), and the host-local secret store (the file, the rationale for a file over environment variables, the editing procedure). The runbook carries its own reference list; the README's remaining references are renumbered contiguously.
Changed in the README beyond the move:
runner_accountandstandalonecontract sections (it predated the grouped parameter surface).packages.sourcesnow states explicitly that the sources switch and the install list are independent layers, and names the two supported shapes on a host whose content platform (orcharhino, Foreman/Katello) serves the packages.Examples:
examples/README.mdis reframed the same way, fleet adoption first (thedata/layer and the token key shape) and the skeleton second as the standalone complement. The example host data marks itsstandaloneblock as standalone-only and now uses the module-default control-repository path.No behavior change: one new shipped file, prose, and one spec assertion following the example data. Verified:
just checkgreen on every commit; both reference lists contiguous with every citation resolving; all cross-file links checked against live headings.