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>

doc/source/architecture.rst

@@ -481,6 +481,39 @@ change to a new value:
 .. image:: ./images/action_plan_state_machine.png
    :width: 100%
 
+.. _action_state_machine:
+
+Action State Machine
+-------------------------
+
+An :ref:`Action <action_definition>` has a life-cycle and its current state may
+be one of the following:
+
+-  **PENDING** : the :ref:`Action <action_definition>` has not been executed
+   yet by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SKIPPED** : the :ref:`Action <action_definition>` will not be executed
+   because a predefined skipping condition is found by
+   :ref:`Watcher Applier <watcher_applier_definition>` or is explicitly
+   skipped by the :ref:`Administrator <administrator_definition>`.
+-  **ONGOING** : the :ref:`Action <action_definition>` is currently being
+   processed by the :ref:`Watcher Applier <watcher_applier_definition>`
+-  **SUCCEEDED** : the :ref:`Action <action_definition>` has been executed
+   successfully
+-  **FAILED** : an error occurred while trying to execute the
+   :ref:`Action <action_definition>`
+-  **DELETED** : the :ref:`Action <action_definition>` is still stored in the
+   :ref:`Watcher database <watcher_database_definition>` but is not returned
+   any more through the Watcher APIs.
+-  **CANCELLED** : the :ref:`Action <action_definition>` was in **PENDING** or
+   **ONGOING** state and was cancelled by the
+   :ref:`Administrator <administrator_definition>`
+
+The following diagram shows the different possible states of an
+:ref:`Action <action_definition>` and what event makes the state change
+change to a new value:
+
+.. image:: ./images/action_state_machine.png
+   :width: 100%
 
 
 .. _Watcher API: https://docs.openstack.org/api-ref/resource-optimization/

doc/source/image_src/plantuml/action_state_machine.txt

@@ -0,0 +1,23 @@
+@startuml
+
+skinparam ArrowColor DarkRed
+skinparam StateBorderColor DarkRed
+skinparam StateBackgroundColor LightYellow
+skinparam Shadowing true
+
+[*] --> PENDING: The Watcher Planner\ncreates the Action
+PENDING --> SKIPPED: The Action detects skipping condition\n in pre_condition or was\n skipped by cloud Admin.
+PENDING --> FAILED: The Action fails unexpectedly\n in pre_condition.
+PENDING --> ONGOING: The Watcher Applier starts executing/n the action.
+ONGOING --> FAILED: Something failed while executing\nthe Action in the Watcher Applier
+ONGOING --> SUCCEEDED: The Watcher Applier executed\nthe Action successfully
+FAILED --> DELETED : Administrator removes\nAction Plan
+SUCCEEDED --> DELETED : Administrator removes\n theAction
+ONGOING --> CANCELLED : The Action was cancelled\n as part of an Action Plan cancellation.
+PENDING --> CANCELLED : The Action was cancelled\n as part of an Action Plan cancellation.
+CANCELLED --> DELETED
+FAILED --> DELETED
+SKIPPED --> DELETED
+DELETED --> [*]
+
+@enduml