From f7e9da0a799bad6e0c87feb87c781e93ae889c6d Mon Sep 17 00:00:00 2001 From: Afonne-CID Date: Tue, 21 Oct 2025 06:27:39 +0100 Subject: [PATCH] Document instance_uuid JSON PATCH non-compliance Add API documentation noting that instance_uuid does not follow RFC 6902 behavior in that the "add" operator cannot replace existing values, preventing race conditions between Nova compute agents. Closes-Bug: #1310843 Change-Id: I1caaf5b6133d756cf9484d3e5b56f7b8280525db Signed-off-by: Afonne-CID --- api-ref/source/baremetal-api-v1-nodes.inc | 7 +++++++ api-ref/source/parameters.yaml | 14 ++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc index 94c6bcb6fb..8664977a9c 100644 --- a/api-ref/source/baremetal-api-v1-nodes.inc +++ b/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 `_. +.. 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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 0b32bd5524..ba727130fd 100644 --- a/api-ref/source/parameters.yaml +++ b/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