[#3290] docs - ha-scopes warning

1 files changed, 16 insertions, 2 deletions

diff --git a/doc/sphinx/arm/hooks-ha.rst b/doc/sphinx/arm/hooks-ha.rst
index 0f8c35cb58..154d688413 100644
--- a/doc/sphinx/arm/hooks-ha.rst
+++ b/doc/sphinx/arm/hooks-ha.rst
@@ -1920,9 +1920,23 @@ The ``ha-scopes`` Command
 -------------------------
 
 This command allows an administrator to modify the HA scopes being served.
+It can be useful when recovering from a failure or when performing maintenance.
 Consult :ref:`ha-load-balancing-config` and :ref:`ha-hot-standby-config` to
-learn which scopes are available for the different HA modes of operation. The
-:isccmd:`ha-scopes` command has the following structure (in a DHCPv4 example):
+learn which scopes are available for the different HA modes of operation.
+
+.. warning::
+
+   The :isccmd:`ha-scopes` command can put Kea servers into conflicting states,
+   which can lead to unexpected behavior. Changing scopes does not automatically
+   change the state of the server or its relationship with a partner.
+   
+   For example, when we add primary scopes to the standby server it will start
+   responding to DHCP traffic for those scopes. This can lead to a situation where
+   both servers are responding to the same traffic, which can lead to IP address
+   collisions.
+
+The :isccmd:`ha-scopes` command has the following structure;
+using an example in DHCPv4.:
 
 ::