From 2f7a649870071614d2b73dd5f81b0a1bfb95f55d Mon Sep 17 00:00:00 2001
From: JaminMartin <jamin@dawnaerospace.com>
Date: Fri, 19 Dec 2025 11:26:24 +1300
Subject: [PATCH] doc: added documentation for WAN service discovery

---
 doc/book/reference-manual/configuration.md | 16 +++++++++++++---
 src/rpc/consul.rs                          | 12 +++++++++++-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/doc/book/reference-manual/configuration.md b/doc/book/reference-manual/configuration.md
index d26d9253..fcf731e6 100644
--- a/doc/book/reference-manual/configuration.md
+++ b/doc/book/reference-manual/configuration.md
@@ -61,8 +61,9 @@ client_key = "/etc/consul/consul-key.crt"
 tls_skip_verify = false
 tags = [ "dns-enabled" ]
 meta = { dns-acl = "allow trusted" }
-
-
+# If your consul cluster is in a WAN configuration, you can provide the datacenter names to allow garage to do discovery across a WAN federation.
+# This is not required for non-WAN consul instances. 
+# datacenters = ["dc1", "dc2", "dc3"] 
 [kubernetes_discovery]
 namespace = "garage"
 service_name = "garage-daemon"
@@ -127,12 +128,14 @@ The `[consul_discovery]` section:
 [`client_cert`](#consul_client_cert_and_key),
 [`client_key`](#consul_client_cert_and_key),
 [`consul_http_addr`](#consul_http_addr),
+[`datacenters`](#consul_datacenters)
 [`meta`](#consul_tags_and_meta),
 [`service_name`](#consul_service_name),
 [`tags`](#consul_tags_and_meta),
 [`tls_skip_verify`](#consul_tls_skip_verify),
 [`token`](#consul_token).
 
+
 The `[kubernetes_discovery]` section:
 [`namespace`](#kube_namespace),
 [`service_name`](#kube_service_name),
@@ -726,8 +729,15 @@ node_prefix "" {
 }
 ```
 
-#### `tags` and `meta` {#consul_tags_and_meta}
 
+### `consul datacenters` {#consul_datacenters}
+
+Optional list of datacenters that allow garage to do service discovery when consul is configured in WAN federation.
+e.g datacenters = ["dc1", "dc2", "dc3"]
+In a WAN configuration the consul services API only responds with local `LAN` services.
+This queries the consul server API by datacenter directly, allowing for garage to discover nodes across consul WAN.
+
+#### `tags` and `meta` {#consul_tags_and_meta}
 Additional list of tags and map of service meta to add during service registration.
 
 ### The `[kubernetes_discovery]` section
diff --git a/src/rpc/consul.rs b/src/rpc/consul.rs
index a9e0ec93..54f75e74 100644
--- a/src/rpc/consul.rs
+++ b/src/rpc/consul.rs
@@ -126,7 +126,17 @@ impl ConsulDiscovery {
 	}
 
 	// ---- READING FROM CONSUL CATALOG ----
-
+	/// Query Consul for Garage nodes registered under the configured service name.
+	///
+	/// This method supports querying multiple Consul datacenters for WAN or
+	/// multi-datacenter deployments. If `config.datacenters` is set and non-empty,
+	/// each listed datacenter is queried and the results are aggregated. Otherwise,
+	/// only the local datacenter is queried. `config.datacenters` does not need to be set
+	/// when all the datacenters are on the same LAN, in this case service discovery works normally
+	///
+	/// # Returns
+	/// A list of `(NodeID, SocketAddr)` pairs corresponding to all valid discovered
+	/// nodes across the queried datacenters.
 	pub async fn get_consul_nodes(&self) -> Result<Vec<(NodeID, SocketAddr)>, ConsulError> {
 		let mut ret = vec![];