API changes for skipped actions: patch actions and status_message

This patch implements the changes in the API required for the skipped action blueprint. It includes: - New field `status_message` is visible in API get calls for Audits, ActionPlans and Audits. - New Patch call is added to `/actions/{action_id}` which allows to manually move actions in PENDING state to SKIPPED for ActionPlans which have not been started. - A new API microversion 1.5 is added for these changes. It also adds requried tests and documentation. Implements: blueprint add-skip-actions Assisted-By: Cursor (claude-4-sonnet) Change-Id: I71fb9af76085e5941a7fd3e9e4c89d6f3a3ada47 Signed-off-by: Alfredo Moralejo <amoralej@redhat.com>
2025-08-06 17:37:15 +02:00
parent 6d35be11ec
commit e06f1b0475
30 changed files with 797 additions and 60 deletions
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -189,6 +189,13 @@ action_state:
  in: body
  required: true
  type: string
+action_status_message:
+  description: |
+    Message with additional information about the Action state.
+  in: body
+  required: false
+  type: string
+  min_version: 1.5
 action_type:
  description: |
    Action type based on specific API action. Actions in Watcher are
@@ -230,6 +237,13 @@ actionplan_state:
  in: body
  required: false
  type: string
+actionplan_status_message:
+  description: |
+    Message with additional information about the Action Plan state.
+  in: body
+  required: false
+  type: string
+  min_version: 1.5

 # Audit
 audit_autotrigger:
@@ -320,6 +334,13 @@ audit_state:
  in: body
  required: true
  type: string
+audit_status_message:
+  description: |
+    Message with additional information about the Audit state.
+  in: body
+  required: false
+  type: string
+  min_version: 1.5
 audit_strategy:
  description: |
    The UUID or name of the Strategy.
--- a/api-ref/source/samples/action-skip-request-with-message.json
+++ b/api-ref/source/samples/action-skip-request-with-message.json
@@ -0,0 +1,12 @@
+[
+    {
+        "op": "replace",
+        "value": "SKIPPED",
+        "path": "/state"
+    },
+    {
+        "op": "replace",
+        "value": "Skipping due to maintenance window",
+        "path": "/status_message"
+    }
+]
--- a/api-ref/source/samples/action-skip-request.json
+++ b/api-ref/source/samples/action-skip-request.json
@@ -0,0 +1,7 @@
+[
+    {
+        "op": "replace",
+        "value": "SKIPPED",
+        "path": "/state"
+    }
+]
--- a/api-ref/source/samples/action-skip-response.json
+++ b/api-ref/source/samples/action-skip-response.json
@@ -0,0 +1,29 @@
+{
+    "state": "SKIPPED",
+    "description": "Migrate instance to another compute node",
+    "parents": [
+        "b4529294-1de6-4302-b57a-9b5d5dc363c6"
+    ],
+    "links": [
+        {
+            "rel": "self",
+            "href": "http://controller:9322/v1/actions/54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a"
+        },
+        {
+            "rel": "bookmark",
+            "href": "http://controller:9322/actions/54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a"
+        }
+    ],
+    "action_plan_uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf",
+    "uuid": "54acc7a0-91b0-46ea-a5f7-4ae2b9df0b0a",
+    "deleted_at": null,
+    "updated_at": "2018-04-10T12:15:44.026973+00:00",
+    "input_parameters": {
+        "migration_type": "live",
+        "destination_node": "compute-2",
+        "resource_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
+    },
+    "action_type": "migrate",
+    "created_at": "2018-04-10T11:59:12.725147+00:00",
+    "status_message": "Action skipped by user. Reason:Skipping due to maintenance window"
+}
--- a/api-ref/source/samples/actionplan-list-detailed-response.json
+++ b/api-ref/source/samples/actionplan-list-detailed-response.json
@@ -21,7 +21,8 @@
            "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf",
            "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a",
            "created_at": "2018-04-10T11:59:52.640067+00:00",
-            "hostname": "controller"
+            "hostname": "controller",
+            "status_message": null
        }
    ]
 }
--- a/api-ref/source/samples/actionplan-show-response.json
+++ b/api-ref/source/samples/actionplan-show-response.json
@@ -17,5 +17,6 @@
    "strategy_name": "dummy_with_resize",
    "uuid": "4cbc4ede-0d25-481b-b86e-998dbbd4f8bf",
    "audit_uuid": "7d100b05-0a86-491f-98a7-f93da19b272a",
-    "hostname": "controller"
-}
+    "hostname": "controller",
+    "status_message": null
+}
--- a/api-ref/source/samples/actions-list-detailed-response.json
+++ b/api-ref/source/samples/actions-list-detailed-response.json
@@ -24,7 +24,8 @@
                "duration": 3.2
            },
            "action_type": "sleep",
-            "created_at": "2018-03-26T11:56:08.235226+00:00"
+            "created_at": "2018-03-26T11:56:08.235226+00:00",
+            "status_message": null
        }
    ]
-}
+}
--- a/api-ref/source/samples/actions-show-response.json
+++ b/api-ref/source/samples/actions-show-response.json
@@ -22,5 +22,6 @@
        "message": "Welcome"
    },
    "action_type": "nop",
-    "created_at": "2018-04-10T11:59:12.725147+00:00"
-}
+    "created_at": "2018-04-10T11:59:12.725147+00:00",
+    "status_message": null
+}
--- a/api-ref/source/samples/audit-create-response.json
+++ b/api-ref/source/samples/audit-create-response.json
@@ -51,5 +51,6 @@
    "updated_at": null,
    "hostname": null,
    "start_time": null,
-    "end_time": null
+    "end_time": null,
+    "status_message": null
 }
--- a/api-ref/source/samples/audit-list-detailed-response.json
+++ b/api-ref/source/samples/audit-list-detailed-response.json
@@ -53,7 +53,8 @@
            "updated_at": "2018-04-06T09:44:01.604146+00:00",
            "hostname": "controller",
            "start_time": null,
-            "end_time": null
+            "end_time": null,
+            "status_message": null
        }
    ]
 }
--- a/api-ref/source/samples/audit-show-response.json
+++ b/api-ref/source/samples/audit-show-response.json
@@ -51,5 +51,6 @@
    "updated_at": "2018-04-06T11:54:01.266447+00:00",
    "hostname": "controller",
    "start_time": null,
-    "end_time": null
+    "end_time": null,
+    "status_message": null
 }
--- a/api-ref/source/watcher-api-v1-actionplans.inc
+++ b/api-ref/source/watcher-api-v1-actionplans.inc
@@ -139,6 +139,7 @@ Response
    - global_efficacy: actionplan_global_efficacy
    - links: links
    - hostname: actionplan_hostname
+    - status_message: actionplan_status_message

 **Example JSON representation of an Action Plan:**

@@ -177,6 +178,7 @@ Response
    - global_efficacy: actionplan_global_efficacy
    - links: links
    - hostname: actionplan_hostname
+    - status_message: actionplan_status_message

 **Example JSON representation of an Audit:**

@@ -233,6 +235,7 @@ version 1:
    - global_efficacy: actionplan_global_efficacy
    - links: links
    - hostname: actionplan_hostname
+    - status_message: actionplan_status_message

 **Example JSON representation of an Action Plan:**

--- a/api-ref/source/watcher-api-v1-actions.inc
+++ b/api-ref/source/watcher-api-v1-actions.inc
@@ -114,6 +114,7 @@ Response
    - description: action_description
    - input_parameters: action_input_parameters
    - links: links
+    - status_message: action_status_message

 **Example JSON representation of an Action:**

@@ -151,8 +152,62 @@ Response
    - description: action_description
    - input_parameters: action_input_parameters
    - links: links
+    - status_message: action_status_message

 **Example JSON representation of an Action:**

 .. literalinclude:: samples/actions-show-response.json
   :language: javascript
+
+Skip Action
+===========
+
+.. rest_method::  PATCH /v1/actions/{action_ident}
+
+Skips an Action resource by changing its state to SKIPPED.
+
+.. note::
+    Only Actions in PENDING state can be skipped. The Action must belong to
+    an Action Plan in RECOMMENDED or PENDING state. This operation requires
+    API microversion 1.5 or later.
+
+Normal response codes: 200
+
+Error codes: 400,404,403,409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - action_ident: action_ident
+
+**Example Action skip request:**
+
+.. literalinclude:: samples/action-skip-request.json
+   :language: javascript
+
+**Example Action skip request with custom status message:**
+
+.. literalinclude:: samples/action-skip-request-with-message.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+    - uuid: uuid
+    - action_type: action_type
+    - state: action_state
+    - action_plan_uuid: action_action_plan_uuid
+    - parents: action_parents
+    - description: action_description
+    - input_parameters: action_input_parameters
+    - links: links
+    - status_message: action_status_message
+
+**Example JSON representation of a skipped Action:**
+
+.. literalinclude:: samples/action-skip-response.json
+   :language: javascript
--- a/api-ref/source/watcher-api-v1-audits.inc
+++ b/api-ref/source/watcher-api-v1-audits.inc
@@ -85,6 +85,7 @@ version 1:
    - start_time: audit_starttime_resp
    - end_time: audit_endtime_resp
    - force: audit_force
+    - status_message: audit_status_message

 **Example JSON representation of an Audit:**

@@ -184,6 +185,7 @@ Response
    - start_time: audit_starttime_resp
    - end_time: audit_endtime_resp
    - force: audit_force
+    - status_message: audit_status_message

 **Example JSON representation of an Audit:**

@@ -231,6 +233,7 @@ Response
    - start_time: audit_starttime_resp
    - end_time: audit_endtime_resp
    - force: audit_force
+    - status_message: audit_status_message

 **Example JSON representation of an Audit:**

@@ -286,6 +289,7 @@ version 1:
    - start_time: audit_starttime_resp
    - end_time: audit_endtime_resp
    - force: audit_force
+    - status_message: audit_status_message

 **Example JSON representation of an Audit:**

@@ -341,6 +345,7 @@ Response
    - start_time: audit_starttime_resp
    - end_time: audit_endtime_resp
    - force: audit_force
+    - status_message: audit_status_message

 **Example JSON representation of an Audit:**