Master cluster join

doc/ref/configuration/master.rst

@@ -339,6 +339,43 @@ listens on for incoming TCP connections. The default is ``4520``
 
     cluster_pool_port: 4520
 
+.. conf_master:: cluster_secret
+
+``cluster_secret``
+------------------
+
+.. versionadded:: 3008.0
+
+Pre-shared string that authenticates a master joining the cluster. All peers
+must be configured with the same value. Leaving it unset matches empty against
+empty and provides no authentication -- always set a high-entropy value in
+production. See :ref:`tutorial-master-cluster`.
+
+.. code-block:: yaml
+
+    cluster_secret: "d8b4c2e1f07a4c3e8a1b5d0a9c7f3e42b6d9a1c4f8e2b7d0a3c6e9f1b4d7a0c3"
+
+.. conf_master:: cluster_pub_fingerprint
+
+``cluster_pub_fingerprint``
+---------------------------
+
+.. versionadded:: 3008.0
+
+Optional SHA-256 hex digest of the shared cluster public key. When set, a
+joining master rejects any discover-reply whose cluster public key does not
+hash to this value. Useful when the joining master cannot read the cluster
+public key from a shared ``cluster_pki_dir``; otherwise leave unset and rely
+on ``cluster_secret`` to authenticate the join.
+
+.. code-block:: shell
+
+    openssl dgst -sha256 /path/to/cluster_pki_dir/cluster.pub
+
+.. code-block:: yaml
+
+    cluster_pub_fingerprint: "3b1f9d...<64 hex chars>...c7a2"
+
 .. conf_master:: extension_modules
 
 ``extension_modules``

doc/topics/tutorials/master-cluster.rst

@@ -97,3 +97,52 @@ Master Config:
         pillar_roots:
           base:
             - /my/gluster/share/srv/pillar
+
+
+Dynamic Join
+============
+
+.. versionadded:: 3008.0
+
+A new master can join a running cluster without reconfiguring the existing
+peers. The joining master needs the same ``cluster_id``,
+``cluster_pki_dir``, and ``cluster_secret`` as the cluster, plus at least
+one reachable peer in its ``cluster_peers`` -- it does not need the full
+peer list. On startup it runs a discover/join handshake against those
+peers, and on success it receives the shared cluster public key and the
+current in-memory AES session key and is added to every peer's
+``cluster_peers``.
+
+Joining master config:
+
+.. code-block:: yaml
+
+        id: 10.27.9.42
+        cluster_id: master_cluster
+        cluster_peers:
+          - 10.27.12.13
+        cluster_pki_dir: /my/gluster/share/pki
+        cluster_secret: "d8b4c2e1f07a4c3e8a1b5d0a9c7f3e42b6d9a1c4f8e2b7d0a3c6e9f1b4d7a0c3"
+        cachedir: /my/gluster/share/cache
+
+Add the new master to the load balancer's backend pools so publish/return
+traffic starts reaching it.
+
+Security notes:
+
+* ``cluster_secret`` is what authenticates the join. Always set a
+  high-entropy value in production; an empty/unset secret matches an empty
+  secret on the peer and provides no authentication.
+* Discover and join payloads are signed per-master, and ``cluster_secret``,
+  the AES session key, and the cluster key are encrypted to the
+  recipient's public key. Restrict the cluster transport to a trusted
+  network -- an attacker with ``cluster_secret`` and transport access can
+  still join.
+* The joining master normally reads the cluster public key from the
+  shared ``cluster_pki_dir``. If that is not available, pin it with
+  :conf_master:`cluster_pub_fingerprint` on the joining master.
+
+To remove a peer, drop it from the load balancer, stop the master, delete
+its ``cluster_pki_dir/peers/<peer_id>.pub``, and restart the remaining
+masters. Rotate ``cluster_secret`` if you want to prevent the removed
+peer from re-joining.

requirements/constraints.txt

@@ -4,3 +4,12 @@
 wheel >= 0.46.3
 setuptools >= 80.10.2
 pip == 25.2
+# jsonschema 4.x pulls in referencing, which uses attrs.field(alias=...); that
+# requires attrs>=22.2. Keep attrs new enough for either jsonschema line.
+attrs >= 22.2.0
+# Salt CI pins jsonschema 3.2.x for Python <3.13; jsonschema 4.x is only
+# resolved for 3.13+ (see static ci/py3.13/*.txt). Cap 3.11/3.12 so optional
+# tools cannot upgrade jsonschema and break attrs/referencing (see attrs note).
+# Note: some third-party tools (e.g. mcp) require jsonschema>=4 on all Python
+# versions; use Python 3.13+ with Salt's compiled reqs, or a separate venv, for those.
+jsonschema < 4; python_version < "3.13"

requirements/static/ci/common.in

@@ -22,7 +22,8 @@ filelock>=3.20.3 ; python_version >= '3.10'
 gitpython>=3.1.37
 google-auth==2.35.0; python_version == '3.9'
 jmespath>=1.1.0
-jsonschema
+jsonschema>=3.2.0,<4.0.0; python_version < "3.13"
+jsonschema>=4.23.0; python_version >= "3.13"
 junos-eznc; sys_platform != 'win32'
 junit-xml>=1.9
 jxmlease; sys_platform != 'win32'

requirements/static/ci/py3.10/cloud.txt

@@ -36,6 +36,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -c requirements/static/pkg/py3.10/linux.txt
     #   aiohttp
@@ -273,6 +274,7 @@ jmespath==1.1.0
     #   botocore
 jsonschema==3.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/static/ci/common.in
 junit-xml==1.9

requirements/static/ci/py3.10/darwin.txt

@@ -30,6 +30,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/pkg/py3.10/darwin.txt
     #   aiohttp
     #   jsonschema
@@ -211,7 +212,9 @@ jmespath==1.1.0
     #   boto3
     #   botocore
 jsonschema==3.2.0
-    # via -r requirements/static/ci/common.in
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
 junit-xml==1.9
     # via -r requirements/static/ci/common.in
 junos-eznc==2.6.7

requirements/static/ci/py3.10/docs.txt

@@ -24,6 +24,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.10/linux.txt
     #   aiohttp
 autocommand==2.2.2

requirements/static/ci/py3.10/freebsd.txt

@@ -29,6 +29,7 @@ async-timeout==5.0.1 ; python_full_version < '3.11'
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/pkg/py3.10/freebsd.txt
     #   aiohttp
     #   jsonschema
@@ -37,6 +38,7 @@ attrs==25.4.0
     #   pytest-skip-markers
     #   pytest-subtests
     #   pytest-system-statistics
+    #   referencing
 autocommand==2.2.2
     # via
     #   -c requirements/static/pkg/py3.10/freebsd.txt
@@ -220,8 +222,16 @@ jmespath==1.1.0
     #   -r requirements/static/ci/common.in
     #   boto3
     #   botocore
-jsonschema==3.2.0
-    # via -r requirements/static/ci/common.in
+jsonschema==3.2.0 ; python_full_version < '3.13'
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
+jsonschema==4.26.0 ; python_full_version >= '3.13'
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
+jsonschema-specifications==2025.9.1 ; python_full_version >= '3.13'
+    # via jsonschema
 junit-xml==1.9
     # via -r requirements/static/ci/common.in
 junos-eznc==2.6.7 ; sys_platform != 'win32'
@@ -369,7 +379,7 @@ pyopenssl==25.3.0
     #   etcd3-py
 pyparsing==3.0.9 ; sys_platform != 'win32'
     # via junos-eznc
-pyrsistent==0.19.3
+pyrsistent==0.19.3 ; python_full_version < '3.13'
     # via jsonschema
 pyserial==3.5 ; sys_platform != 'win32'
     # via junos-eznc
@@ -466,6 +476,10 @@ pyzmq==27.1.0
     #   -c requirements/static/pkg/py3.10/freebsd.txt
     #   -r requirements/zeromq.txt
     #   pytest-salt-factories
+referencing==0.37.0 ; python_full_version >= '3.13'
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
 requests==2.31.0 ; python_full_version < '3.11'
     # via
     #   -c requirements/static/pkg/py3.10/freebsd.txt
@@ -498,6 +512,10 @@ responses==0.23.1
     # via moto
 rfc3987==1.3.8
     # via -r requirements/static/ci/common.in
+rpds-py==0.30.0 ; python_full_version >= '3.13'
+    # via
+    #   jsonschema
+    #   referencing
 rpm-vercmp==0.1.2 ; sys_platform == 'linux'
     # via
     #   -c requirements/static/pkg/py3.10/freebsd.txt

requirements/static/ci/py3.10/lint.txt

@@ -55,6 +55,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -c requirements/static/pkg/py3.10/linux.txt
     #   aiohttp
@@ -300,6 +301,7 @@ jmespath==1.1.0
     #   botocore
 jsonschema==3.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.10/linux.txt
     #   -r requirements/static/ci/common.in
 junit-xml==1.9

requirements/static/ci/py3.10/linux.txt

@@ -39,6 +39,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/pkg/py3.10/linux.txt
     #   aiohttp
     #   jsonschema
@@ -233,7 +234,9 @@ jmespath==1.1.0
     #   boto3
     #   botocore
 jsonschema==3.2.0
-    # via -r requirements/static/ci/common.in
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
 junit-xml==1.9
     # via -r requirements/static/ci/common.in
 junos-eznc==2.6.7

requirements/static/ci/py3.10/tools.txt

@@ -2,8 +2,9 @@
 #    uv pip compile requirements/static/ci/tools.in --python-platform=linux --python-version=3.10 --constraint requirements/constraints.txt --no-emit-index-url -o=requirements/static/ci/py3.10/tools.txt
 annotated-types==0.6.0
     # via pydantic
-attrs==20.3.0
+attrs==26.1.0
     # via
+    #   -c requirements/constraints.txt
     #   -r requirements/static/ci/tools.in
     #   python-tools-scripts
 boto3==1.26.152

requirements/static/ci/py3.10/windows.txt

@@ -28,6 +28,7 @@ async-timeout==5.0.1
     #   aiohttp
 attrs==25.4.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/pkg/py3.10/windows.txt
     #   aiohttp
     #   jsonschema
@@ -209,7 +210,9 @@ jmespath==1.1.0
     #   boto3
     #   botocore
 jsonschema==3.2.0
-    # via -r requirements/static/ci/common.in
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
 junit-xml==1.9
     # via -r requirements/static/ci/common.in
 keyring==5.7.1

requirements/static/ci/py3.11/cloud.txt

@@ -31,6 +31,7 @@ asn1crypto==1.5.1
     #   oscrypto
 attrs==23.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.11/linux.txt
     #   -c requirements/static/pkg/py3.11/linux.txt
     #   aiohttp
@@ -263,6 +264,7 @@ jmespath==1.1.0
     #   botocore
 jsonschema==3.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.11/linux.txt
     #   -r requirements/static/ci/common.in
 junit-xml==1.9

requirements/static/ci/py3.11/darwin.txt

@@ -26,6 +26,7 @@ asn1crypto==1.5.1
     #   oscrypto
 attrs==23.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/pkg/py3.11/darwin.txt
     #   aiohttp
     #   jsonschema
@@ -204,7 +205,9 @@ jmespath==1.1.0
     #   boto3
     #   botocore
 jsonschema==3.2.0
-    # via -r requirements/static/ci/common.in
+    # via
+    #   -c requirements/constraints.txt
+    #   -r requirements/static/ci/common.in
 junit-xml==1.9
     # via -r requirements/static/ci/common.in
 junos-eznc==2.6.7

requirements/static/ci/py3.11/docs.txt

@@ -20,6 +20,7 @@ apache-libcloud==3.9.0
     #   -r requirements/base.txt
 attrs==23.2.0
     # via
+    #   -c requirements/constraints.txt
     #   -c requirements/static/ci/py3.11/linux.txt
     #   aiohttp
 autocommand==2.2.2