docs(cluster): "Running HFS in a Cluster" operator chapter and cluster-testing skill section (Phase 0.5) - #909
Open
aacruzgon wants to merge 1 commit into
Open
docs(cluster): "Running HFS in a Cluster" operator chapter and cluster-testing skill section (Phase 0.5)#909aacruzgon wants to merge 1 commit into
aacruzgon wants to merge 1 commit into
Conversation
There was no operator-facing description of what happens when N hfs instances share a database: which subsystems are safe, which still need a pinned instance, what HFS_CLUSTER refuses, and how a cluster is verified. Book chapter 15 covers prerequisites, the one-switch setup with the refusal and warning tables as implemented, a per-subsystem 1-vs-N matrix that names what is safe today (CRUD with compare-and-swap version bumps, schema init, bulk data on PostgreSQL, SIGTERM drain, JWT validation) and what is still per-instance and planned (SQL-on-FHIR async export, reindex, subscriptions, HTS caches and bootstrap, composite async sync), load-balancer notes (sticky sessions required today for exports and subscriptions, and why they are not sufficient for subscriptions), and the two-instance smoke harness. The test-hfs skill gains the T1/T2/T3 cluster testing section in both skill trees. Tests: mdbook build succeeds and the chapter renders; no code changes.
aacruzgon
force-pushed
the
cluster/p0.5-ch15
branch
from
September 2, 2026 18:55
f922141 to
7d442b7
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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.
Summary
Phase 0.5 of the cluster-capable-state rebuild (discussion #223): the operator chapter "Running HFS in a Cluster" (book ch. 15) and the cluster-testing section of the
test-hfsskill. Documentation only.Branched from
main; the chapter describes the refusal and warning tables that #906 implements and the SIGTERM drain that #907 implements, so it reads best once those merge, but it does not conflict with them (different files).Changes
book/src/ch15-cluster-deployment.md(new) +SUMMARY.mdentry: prerequisites; theHFS_CLUSTER=trueone-switch setup with the refusal table (SQLite primary,local-fsbulk output, bulk export on a MongoDB/S3 primary, file audit, explicit memory job store) and the two warnings ($sql-exportper-instance job state,HFS_EXPORT_SINK=fs); a per-subsystem 1-vs-N matrix that states plainly what is safe today and what is still per-instance and planned; load-balancer notes (sticky sessions required today for async exports and Subscriptions, and why sticky is not sufficient for Subscriptions); how to verify a cluster with the smoke harness or by hand.test-hfsskill (both.claude/skillsand.agents/skills): the T1/T2/T3 tiers, the two-handle harness and its definition-of-done rows, the commands for the T2 suites that exist today, and how to dispatch the smoke workflow on a branch.Testing
mdbook build booksucceeds;ch15-cluster-deployment.htmlrenders with the summary link.Notes