From 1b3ce7ebd4b02ad225ace4567ff89b14ad1c4a58 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 8 Apr 2025 15:46:13 +0200
Subject: [PATCH] docs(inventory): improve extendSettings docs

---
 docs/site/manual/distributed-services.md | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/site/manual/distributed-services.md b/docs/site/manual/distributed-services.md
index 5396737cd..d8867e6cd 100644
--- a/docs/site/manual/distributed-services.md
+++ b/docs/site/manual/distributed-services.md
@@ -281,26 +281,29 @@ Next we need to define the settings and the behavior of these distinct roles.
 }
 ```
 
-## Vendoring settings for a machine
+## Using values from a NixOS machine inside the module
 
 !!! Example "Experimental Status"
     This feature is experimental and should be used with care.
 
-Sometimes the *default* value depends on something within a machines `config`.
+Sometimes a settings value depends on something within a machines `config`.
 
-Since the `interface` is defined completely machine-agnostic this means default values from a machine cannot be set in the traditional way.
+Since the `interface` is defined completely machine-agnostic this means values from a machine cannot be set in the traditional way.
 
 The following example shows how to create a local instance of machine specific settings.
 
 ```nix title="someservice.nix"
 {
     # Maps over all instances and produces one result per instance.
-    perInstance = { instanceName, settings, machine, roles, ... }: {
+    perInstance = { instanceName, extendSettings, machine, roles, ... }: {
         nixosModule = { config, ... }:
           let
-            # Calling settings via function application
-            # will extend the underlying module
-            localSettings = settings { ipRanges = lib.mkDefault config.network.ip.range; };
+            # Create new settings with
+            # 'ipRanges' defaulting to 'config.network.ip.range' from this machine
+            # This only works if there is no 'default' already.
+            localSettings = extendSettings {
+                ipRanges = lib.mkDefault config.network.ip.range;
+            };
           in
             {
                 # ...
@@ -311,4 +314,6 @@ The following example shows how to create a local instance of machine specific s
 
 !!! Danger
     `localSettings` are a local attribute. Other machines cannot access it.
-    If settings vendoring is done. Accessing that settings attribute of another machine via the `settings` argument is considered **unsafe**.
+    If calling extendSettings is done that doesn't change the original `settings` this means if a different machine tries to access i.e `roles.client.settings` it would *NOT* contain your changes.
+
+    Exposing the changed settings to other machines would come with a huge performance penalty, thats why we don't want to offer it.