Merge "Document instance_uuid JSON PATCH non-compliance"

api-ref/source/baremetal-api-v1-nodes.inc

@@ -678,6 +678,13 @@ Request
 The BODY of the PATCH request must be a JSON PATCH document, adhering to
 `RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
 
+.. note::
+    The ``instance_uuid`` field is an exception to the RFC 6902 behavior.
+    The "add" operator cannot replace an existing ``instance_uuid`` value.
+    Attempting to do so will result in a 409 Conflict error (NodeAssociated
+    exception). This protection prevents race conditions when multiple
+    Nova compute agents try to associate the same node.
+
 .. rest_parameters:: parameters.yaml
 
    - node_ident: node_ident

api-ref/source/parameters.yaml

@@ -1291,6 +1291,13 @@ instance_info:
 instance_uuid:
   description: |
     UUID of the Nova instance associated with this Node.
+
+    .. note::
+        This field does not follow standard JSON PATCH RFC 6902 behavior.
+        The "add" operator cannot replace an existing instance_uuid value.
+        Attempting to do so will result in a 409 Conflict error (NodeAssociated
+        exception). This protection prevents race conditions when multiple
+        Nova compute agents try to associate the same node.
   in: body
   required: true
   type: string
@@ -1886,6 +1893,13 @@ req_instance_info:
 req_instance_uuid:
   description: |
     UUID of the Nova instance associated with this Node.
+
+    .. note::
+        This field does not follow standard JSON PATCH RFC 6902 behavior.
+        The "add" operator cannot replace an existing instance_uuid value.
+        Attempting to do so will result in a 409 Conflict error (NodeAssociated
+        exception). This protection prevents race conditions when multiple
+        Nova compute agents try to associate the same node.
   in: body
   required: false
   type: string