From 14fdce299caedb32ed6cee55ad7482038a479e7d Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Thu, 20 Aug 2026 23:16:43 +1000 Subject: [PATCH] docs: Add "Why Arbiter?" section Add information to the Arbiter page explaining why Arbiter is used and explaining the process whereby Arbiter deploys an external AZ to restore quorum to clusters that have lost quorum. Signed-off-by: Zac Dover --- docs/architecture/cloud-storage/arbiter.md | 29 ++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/architecture/cloud-storage/arbiter.md b/docs/architecture/cloud-storage/arbiter.md index b8198dd..d6c33b9 100644 --- a/docs/architecture/cloud-storage/arbiter.md +++ b/docs/architecture/cloud-storage/arbiter.md @@ -15,6 +15,35 @@ The operator also monitors the remote cluster to verify its availability and ensure that the tenant has sufficient permissions to handle the deployment of Arbiter. +## Why Use Arbiter? + +The diagram below explains how Arbiter works and why it is necessary. The three +paragraphs that follow this one walk you through the procedure detailed in the +diagram. + +Red section: In the event that there is an outage of an availability zone (AZ) +or a network failure between two availability zones, the cluster loses quorum +because neither side can reach a majority (one out of two isn't enough). In +this event, Ceph is unable safely to make decisions about the cluster state. + +Blue Section: This situation can be remedied if Arbiter has been deployed. The +operator will spring into action, reading the Ceph cluster, reserving an +`externalMonID`, creating remote resources, and then making sure all necessary +updates are in place. + +Green Section: After the Arbiter Operator has taken remedial action, a remote +and independent cluster (`mon.ext-a` in the diagram) will be in operation, +restoring quorum to the cluster. + +![Arbiter Diagram](../../assets/project-owned/diagrams/purpose-external-arbiter-operator.png) + +>[!IMPORTANT] +>It is important to understand the scope of Arbiter, and the problem that it +>solves. Arbiter restores control-plane quorum to clusters that have lost +>quorum. It does not guarantee data redundancy. Arbiter ensures that the +>cluster is still able to make quorum-related decisions. It does not guarantee +>the congruency of data between OSDs. + ## Requirements and Setup ### Required Tools