Support node retirement

This change adds support for node retirement: nodes can
have additional properties 'retired' and 'retired_reason'
which change the way the nodes (can) traverse the FSM
and which operations are allowed. In particular:
- retired nodes cannot move from manageable to available;
- upon instance deletion, retired nodes move to manageable
  (rather than available).

Story: #2005425
Task: #38142

Change-Id: I8113a44c28f62bf83f8e213aeb6704f96055d52b

6 files changed, 29 insertions, 0 deletions

diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc
index 570759f30..78e8a0f1c 100644
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/api-ref/source/baremetal-api-v1-nodes.inc
@@ -426,6 +426,8 @@ Response
     - description: n_description
     - conductor: conductor
     - allocation_uuid: allocation_uuid
+    - retired: retired
+    - retired_reason: retired_reason
 
 **Example detailed list of Nodes:**
 
@@ -469,6 +471,9 @@ only the specified set.
 .. versionadded:: 1.52
   Introduced the ``allocation_uuid`` field.
 
+.. versionadded:: 1.61
+  Introduced the ``retired`` and ``retired_reason`` fields.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 66e066c52..4967fc61d 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -1542,6 +1542,20 @@ response_driver_type:
   in: body
   required: true
   type: string
+retired:
+  description: |
+    Whether the node is retired and can hence no longer be provided, i.e. move
+    from ``manageable`` to ``available``, and will end up in ``manageable``
+    after cleaning (rather than ``available``).
+  in: body
+  required: false
+  type: boolean
+retired_reason:
+  description: |
+    The reason the node is marked as retired.
+  in: body
+  required: false
+  type: string
 standalone_ports_supported:
   description: |
     Indicates whether ports that are members of this portgroup can be
diff --git a/api-ref/source/samples/node-create-response.json b/api-ref/source/samples/node-create-response.json
index 08692249a..84932a235 100644
--- a/api-ref/source/samples/node-create-response.json
+++ b/api-ref/source/samples/node-create-response.json
@@ -71,6 +71,8 @@
   "rescue_interface": null,
   "reservation": null,
   "resource_class": "bm-large",
+  "retired": false,
+  "retired_reason": null,
   "states": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
diff --git a/api-ref/source/samples/node-show-response.json b/api-ref/source/samples/node-show-response.json
index 890a311ed..3a520c96b 100644
--- a/api-ref/source/samples/node-show-response.json
+++ b/api-ref/source/samples/node-show-response.json
@@ -74,6 +74,8 @@
   "rescue_interface": null,
   "reservation": null,
   "resource_class": "bm-large",
+  "retired": false,
+  "retired_reason": null,
   "states": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
diff --git a/api-ref/source/samples/node-update-driver-info-response.json b/api-ref/source/samples/node-update-driver-info-response.json
index a3155aa30..05665a3dc 100644
--- a/api-ref/source/samples/node-update-driver-info-response.json
+++ b/api-ref/source/samples/node-update-driver-info-response.json
@@ -75,6 +75,8 @@
   "rescue_interface": null,
   "reservation": null,
   "resource_class": null,
+  "retired": false,
+  "retired_reason": null,
   "states": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
diff --git a/api-ref/source/samples/nodes-list-details-response.json b/api-ref/source/samples/nodes-list-details-response.json
index 701ac82e7..870a62558 100644
--- a/api-ref/source/samples/nodes-list-details-response.json
+++ b/api-ref/source/samples/nodes-list-details-response.json
@@ -76,6 +76,8 @@
       "rescue_interface": null,
       "reservation": null,
       "resource_class": null,
+      "retired": false,
+      "retired_reason": null,
       "states": [
         {
           "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
@@ -178,6 +180,8 @@
       "rescue_interface": "no-rescue",
       "reservation": null,
       "resource_class": null,
+      "retired": false,
+      "retired_reason": null,
       "states": [
         {
           "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",