Add high-level distributed runners documentation#963
Conversation
|
Warning Review limit reachedYou’ve reached a temporary PR review limit under our Fair Usage Limits Policy. Next review available in: 35 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
Comment |
![miren-code-agent[bot]](https://avatars.githubusercontent.com/u/174767976?s=60&v=4){kind=small}
There was a problem hiding this comment.
🍪 biscuit: ✅ ready to merge — auto-review, non-blocking
This draft adds the new distributed-runners.md page and two glossary entries (Coordinator, Distributed Runner) in terminology.md, with small cross-reference tweaks in workload-identity.md and disks.md, plus a sidebar entry. The docs are ready to hand off to human review.
Accuracy against the rest of the codebase. The new page's claims are consistent with what the other docs already say. The "disks pin to coordinator" rule is confirmed by the disks.md text and its Limitations section. The workload-identity section on distributed runners (in workload-identity.md) already existed and matches the new page's description of token issuance routing through the coordinator. The scheduler preference for runners and the overlay network ranges (10.8.0.0/16, 10.10.0.0/16) are stated as fact; I can't verify them from doc files alone, but they read like deliberate product details rather than guesses.
Security guidance is sound. The :::warning and :::danger admonitions around join tokens are well-placed. The reusable-token section rightly emphasises keeping the secret in a secret manager and the cloud-init idempotency guard (systemctl cat) is a practical and correct pattern.
A few minor things worth noting:
- Line 58 of
distributed-runners.md: the token is described as having "the coordinator's address baked in" — this is useful, but it isn't explained anywhere how a runner that has no pre-existing network path to the coordinator would resolve or reach it. That's probably fine for a high-level doc, but operators running across cloud VPCs may hit this and find no guidance. Worth a one-liner note or a follow-up issue. - The
--forceflag in the cloud-init bash snippet (line 135) is used alongside--skip-system-check, but--forcesemantics aren't described anywhere in the doc or referenced command. If--forceimplies something operationally significant (e.g. overwriting an existing config), that deserves a brief inline callout. - The sidebar addition puts
distributed-runnersin "Run & Scale" betweenscalingandadmin-interface— that ordering is logical.
Overall the prose is clear, internally consistent, and the structure (how it works → adding a runner → automating → operating → caveats → next steps) follows a natural operator journey. Nothing here blocks graduation to human review.
🍪 full review note · comment /biscuit review to run biscuit again.
| miren runner install \ | ||
| --token "$TOKEN" \ | ||
| --skip-system-check \ | ||
| --force |
There was a problem hiding this comment.
The --force flag is used here but isn't described anywhere in this page or referenced to a command doc. If it has any destructive or surprising behavior (e.g. overwriting an existing config or bypassing a safety check), a brief inline explanation would help operators understand what they're opting into.
🤖 Prompt for AI Agents
In docs/docs/distributed-runners.md, line 135, the
bash snippet passes --force to `miren runner
install` without explanation. Add a short inline
comment or a sentence in the surrounding prose
that describes what --force does in this context
(e.g. 'overwrites any partially written config
from a previous attempt') so operators know what
they are opting into. If the flag is benign in
this specific context, say so explicitly.
There was a problem hiding this comment.
Added an explanation in the surrounding prose: --force overwrites the service file left by a half-finished earlier attempt, so a retried boot installs cleanly. The systemctl cat guard already keeps the happy path from re-running, so this only bites on a recovery. Fixed in 055c181.
maryelizbeth
left a comment
maryelizbeth
left a comment
There was a problem hiding this comment.
other than addressing the comments from biscy - docs lgtm
The distributed runners feature shipped with a full runner-* CLI reference but no conceptual page, so a reader had all the verbs and no mental model. This adds a guide that ties it together: the coordinator/runner architecture, the overlay network and scheduling rules, a manual walkthrough for adding a node, an automated enrollment pattern for provisioning at scale, and an honest account of the current constraints. Written for the default-on flip, so there's no labs gating in the prose. Also adds Coordinator and Distributed Runner glossary entries and points the existing distributed-runner mentions in disks and workload-identity at the new page.
3b3c287 to
055c181
Compare
2 participants
Distributed runners had a complete
runner *CLI reference in the docs, but nothing that explained what any of it meant. A reader arriving fresh got a pile of commands (join, cordon, drain, reissue) with no picture of how a coordinator and its runners actually fit together. This fills that gap with a proper conceptual page.The new page walks the whole arc: what problem distributed runners solve (one machine has a ceiling, so scale out instead of up), how the coordinator/runner split works, where the scheduler places things, and the two ways to add a node. The manual path is the three-step token/join/start flow. The automated path is the pattern we actually run our own fleet with: a reusable enrollment token in a secret manager plus an idempotent
runner installcall baked into cloud-init.It's written for the default-on flip that's landing in parallel, so there's no labs-flag framing anywhere in the prose. The constraints section is honest about today's limits (the coordinator is a single point of coordination, and disk-backed apps stay pinned to it) while being clear those aren't permanent: the control plane is built to grow multi-node, and stateful migration is on the way.
Rounding it out:
CoordinatorandDistributed Runnerglossary entries, a sidebar slot under Run & Scale, and the existing distributed-runner mentions in the disks and workload-identity pages now link to the new page instead of bouncing to the labs index.Closes MIR-1173