[DPE-8774] docs(stereo-mode): add two-node HA explanation and deployment guide#1740
Merged
Conversation
Document stereo mode: a two-`postgresql`-unit topology paired with a standalone `postgresql-watcher` that contributes a third Raft vote, so high availability works with only two database copies. - explanation/stereo-mode.md: why an odd voter count is needed, how the watcher joins the Raft quorum (patroni-raft-controller on port 2222), when it votes vs. abstains, and availability-zone placement — with an architecture diagram. - how-to/deploy/stereo-mode.md: deploy the two units and the watcher, integrate over watcher-offer/watcher, and verify with a real `juju status` sample. - Wire both pages into the explanation, deploy, and home-page navigation. - Add "systemd" to the spelling wordlist. Scoped to a single cluster. Stereo mode currently ships only in 16/edge; a TODO marks the deploy guide for a 16/stable update once released. Signed-off-by: Marcelo Henrique Neppel <marcelo.neppel@canonical.com>
marceloneppel
changed the title
marceloneppel
requested review from
a-velasco,
carlcsaposs-canonical,
dragomirp,
juju-charm-bot and
taurus-forever
and removed request for
a team
dragomirp
reviewed
Jun 3, 2026
dragomirp
previously approved these changes
Jun 3, 2026
Address PR review feedback on the stereo-mode docs: - Explanation: describe the watcher as stopping its Raft service and leaving the quorum on odd unit counts of three or more, rather than merely "abstaining" — this matches how the watcher charm actually behaves (it removes its Raft member and stops the service). Hedge the section heading to cover both the running and stopped states. - How-to: require `postgresql` revision 1149 or higher instead of pointing at the 16/edge channel, since the channel will move on. Drop the obsolete 16/stable TODO and bump the sample `juju status` revision to 1150. Signed-off-by: Marcelo Henrique Neppel <marcelo.neppel@canonical.com>
a-velasco
previously approved these changes
Jun 9, 2026
Contributor
There was a problem hiding this comment.
This looks great @marceloneppel, thank you :) Let's merge it here so that it's available in the current docs for the release.
I'll then integrate it manually into my branch for the single kernel migration.
taurus-forever
previously approved these changes
Jun 10, 2026
marceloneppel
dismissed stale reviews from taurus-forever, a-velasco, and dragomirp
The base branch was changed.
marceloneppel
added
documentation
a-velasco
approved these changes
Jun 10, 2026
taurus-forever
approved these changes
Jun 10, 2026
dragomirp
approved these changes
Jun 10, 2026
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
4 participants
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.
Issue
Stereo mode — two-node high availability where two
postgresqlunits are paired with a standalonepostgresql-watcherthat supplies a third Raft vote — shipped in16/edgewith no user-facing documentation. There was no explanation of why the extra vote is needed and no guide for deploying the topology.Solution
Document stereo mode: a two-
postgresql-unit topology paired with a standalonepostgresql-watcherthat contributes a third Raft vote, so high availability works with only two database copies.explanation/stereo-mode.md: why an odd voter count is needed, how the watcher joins the Raft quorum (patroni-raft-controlleron port 2222), when it votes vs. abstains, and availability-zone placement — with an architecture diagram.how-to/deploy/stereo-mode.md: deploy the two units and the watcher, integrate overwatcher-offer/watcher, and verify with a realjuju statussample.Scoped to a single cluster. Stereo mode currently ships only in
16/edge; a TODO marks the deploy guide for a16/stableupdate once released.Out of scope (intentional): this pass covers only the single-cluster topology through the Explanation and How-to Diátaxis categories. It deliberately does not document:
get-cluster-status,show-topology, andtrigger-health-checkactions, which do not exist yet.Branch strategy: This PR targets the
stereo-mode-docsbranch first. From there we'll decide whether these docs can be merged into16/edge, or whether we need to wait for the VM and K8s charm docs unification before doing so.Checklist