Arnike/watcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add user guide for continuous audits

Browse Source 
Introduce a new user guide describing how to run continuous audits using
the dummy strategy. The guide covers:
- Overview and state machine
- Creating audits with interval and cron expressions
- Time window constraints (start/end time)
- Monitoring executions and action plan lifecycle
- Managing audits (stop/modify)
- Configuration reference and links to related specs

Closes-Bug: #2120437

Assisted-By: GPT-5 (Cursor)
Assisted-By: claude-sonnet-4 (Claude Code)
Change-Id: I842139271752cedb138e422027020488f22fe248
Signed-off-by: Chandan Kumar (raukadah) <chkumar@redhat.com>
This commit is contained in:
Chandan Kumar (raukadah)
2025-08-12 15:23:10 +05:30
parent 635be7a009
commit 3c8bc6be62
2 changed files with 431 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

430
doc/source/user/continuous_type_audit.rst Normal file
View File

@@ -0,0 +1,430 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
=======================
Using Continuous Audit
=======================
Continuous audits allow Watcher to continuously monitor and optimize your
OpenStack infrastructure based on predefined schedules or intervals. This guide
demonstrates how to set up and use continuous audits with the dummy strategy,
which is useful for testing, development, and understanding the continuous
audit workflow. However, this doc is valid for any other combination of
strategy and goal.
Overview
========
A continuous audit differs from a oneshot audit in that it runs repeatedly
at specified intervals. It supports both time-based intervals
(in seconds) and cron-like expressions for more complex scheduling patterns.
The dummy strategy is a test strategy that doesn't perform actual optimization
but creates sample actions (nop and sleep) to demonstrate the complete audit
workflow. It's ideal for:
- Testing continuous audit functionality
- Development and debugging
- Learning how Watcher works
Prerequisites
=============
Before setting up continuous audits, ensure:
1. Watcher services are running and configured properly
2. You have administrator access to OpenStack
You can verify the services are running:
.. code-block:: bash
$ openstack optimize service list
+----+-------------------------+------------+--------+
| ID | Name | Host | Status |
+----+-------------------------+------------+--------+
| 1 | watcher-decision-engine | controller | ACTIVE |
| 2 | watcher-applier | controller | ACTIVE |
+----+-------------------------+------------+--------+
Continuous Audit State Machine
==============================
You can view the Audit state machine diagram in the Watcher documentation:
`Audit State Machine`_
.. _Audit State Machine: https://docs.openstack.org/watcher/latest/architecture.html#audit-state-machine
Transitions:
- An audit is created and enters the **PENDING** state.
- When the scheduled time arrives, a **PENDING** audit becomes **ONGOING**.
- A continuous audit remains in the **ONGOING** state across executions.
It does not switch to **SUCCEEDED** after each run.
- If an execution fails, the audit transitions to **FAILED** and is no longer
executed.
- Each execution produces a new action plan. When a new action plan is created
by the same continuous audit, previous **RECOMMENDED** action plans are moved
to **CANCELLED**. Only the latest action plan remains in **RECOMMENDED**.
- An administrator can **CANCEL** an audit that is **PENDING** or **ONGOING**.
- An administrator can **SUSPEND** an **ONGOING** audit.
- A **SUSPENDED** audit can be resumed by an administrator, at which point it
becomes **ONGOING** again.
- An administrator can **DELETE** an audit only when its state is
**SUCCEEDED**, **FAILED**, or **CANCELLED**.
.. note::
You can enable the auto-trigger option if you want to automatically apply action
plans generated by continuous audits as soon as they are created.
Depending on the environment, continuous audits are often good candidates for
auto-trigger.
Create a Continuous Audit
--------------------------
Create a continuous audit that will run at regular intervals. You can specify
the interval in seconds or use cron-like expressions.
Using Time Interval (seconds)
------------------------------
This example creates a continuous audit that runs every 5 minutes indefinitely
(300 seconds):
.. code-block:: bash
$ openstack optimize audit create \
--goal dummy \
--strategy dummy \
--audit_type CONTINUOUS \
--interval 300 \
--name "continuous-dummy-5min"
+---------------+--------------------------------------+
| Field | Value |
+---------------+--------------------------------------+
| UUID | 7607cf57-ea05-4e1a-b8d7-34e570f95132 |
| Name | continuous-dummy-5min |
| Created At | 2025-08-12T07:26:18.496536+00:00 |
| Updated At | None |
| Deleted At | None |
| State | PENDING |
| Audit Type | CONTINUOUS |
| Parameters | {'para1': 3.2, 'para2': 'hello'} |
| Interval | 300 |
| Goal | dummy |
| Strategy | dummy |
| Audit Scope | [] |
| Auto Trigger | False |
| Next Run Time | None |
| Hostname | None |
| Start Time | None |
| End Time | None |
| Force | False |
+---------------+--------------------------------------+
Using Cron Expression
----------------------
For more complex scheduling, you can use cron-like expressions. This example
runs the audit every hour at the 15-minute mark:
.. code-block:: bash
$ openstack optimize audit create \
--goal dummy \
--strategy dummy \
--audit_type CONTINUOUS \
--interval "15 * * * *" \
--name "continuous-dummy-hourly"
+---------------+--------------------------------------+
| Field | Value |
+---------------+--------------------------------------+
| UUID | 9cbce4f1-eb75-405a-8f4e-108eb08fdd0a |
| Name | continuous-dummy-hourly |
| Created At | 2025-08-12T07:32:31.469309+00:00 |
| Updated At | None |
| Deleted At | None |
| State | PENDING |
| Audit Type | CONTINUOUS |
| Parameters | {'para1': 3.2, 'para2': 'hello'} |
| Interval | 15 * * * * |
| Goal | dummy |
| Strategy | dummy |
| Audit Scope | [] |
| Auto Trigger | False |
| Next Run Time | None |
| Hostname | None |
| Start Time | None |
| End Time | None |
| Force | False |
+---------------+--------------------------------------+
Time Constraints via start_time and end_time
--------------------------------------------
We can limit when the continuous audit runs by setting start and end times
in a time-interval schedule. The interval can passed in seconds or cron expression.
.. note::
Start and End Time are interpreted in the timezone configured on the host where the
Watcher Decision Engine service is running. We can provide ``start_time`` and
``end_time`` in ISO 8601 format, for example ``'2025-08-13T14:30:00'``.
The example below creates a continuous audit that runs from 12:00 to 13:00
with a 5 minute interval.
.. code-block:: bash
$ openstack optimize audit create \
--goal dummy \
--strategy dummy \
--audit_type CONTINUOUS \
--interval 300 \
--start-time "$(date -d 'today 12:00' +%Y-%m-%dT%H:%M:%S)" \
--end-time "$(date -d 'today 13:00' +%Y-%m-%dT%H:%M:%S)" \
--name "continuous-dummy-5min"
+---------------+--------------------------------------+
| Field | Value |
+---------------+--------------------------------------+
| UUID | dadd279b-1e3d-4c38-aba6-4a730a78589b |
| Name | continuous-dummy-5min |
| Created At | 2025-08-12T08:36:42.924460+00:00 |
| Updated At | None |
| Deleted At | None |
| State | PENDING |
| Audit Type | CONTINUOUS |
| Parameters | {'para1': 3.2, 'para2': 'hello'} |
| Interval | 300 |
| Goal | dummy |
| Strategy | dummy |
| Audit Scope | [] |
| Auto Trigger | False |
| Next Run Time | None |
| Hostname | None |
| Start Time | 2025-08-12T12:00:00 |
| End Time | 2025-08-12T13:00:00 |
| Force | False |
+---------------+--------------------------------------+
Monitoring Continuous Audit Execution
======================================
Create a continuous audit
--------------------------
Create a continuous audit with 5 second interval:
.. code-block:: bash
$ openstack optimize audit create \
--goal dummy \
--strategy dummy \
--audit_type CONTINUOUS \
--interval 5 \
--name "continuous-dummy-5sec"
+---------------+--------------------------------------+
| Field | Value |
+---------------+--------------------------------------+
| UUID | 7d1f1961-41a6-47ae-a94a-cf5e43174fbd |
| Name | continuous-dummy-5sec |
| Created At | 2025-08-12T09:27:33.592575+00:00 |
| Updated At | None |
| Deleted At | None |
| State | PENDING |
| Audit Type | CONTINUOUS |
| Parameters | {'para1': 3.2, 'para2': 'hello'} |
| Interval | 5 |
| Goal | dummy |
| Strategy | dummy |
| Audit Scope | [] |
| Auto Trigger | False |
| Next Run Time | None |
| Hostname | None |
| Start Time | None |
| End Time | None |
| Force | False |
+---------------+--------------------------------------+
Once created, the continuous audit will be automatically scheduled and executed
by the Watcher Decision Engine. You can monitor its progress:
Check Audit Status
------------------
.. code-block:: bash
$ openstack optimize audit show 7d1f1961-41a6-47ae-a94a-cf5e43174fbd
+---------------+--------------------------------------+
| Field | Value |
+---------------+--------------------------------------+
| UUID | 7d1f1961-41a6-47ae-a94a-cf5e43174fbd |
| Name | continuous-dummy-5sec |
| Created At | 2025-08-12T09:27:34+00:00 |
| Updated At | 2025-08-12T09:28:28+00:00 |
| Deleted At | None |
| State | ONGOING |
| Audit Type | CONTINUOUS |
| Parameters | {'para1': 3.2, 'para2': 'hello'} |
| Interval | 5 |
| Goal | dummy |
| Strategy | dummy |
| Audit Scope | [] |
| Auto Trigger | False |
| Next Run Time | 2025-08-12T09:28:33 |
| Hostname | chkumar-devstack-1 |
| Start Time | None |
| End Time | None |
| Force | False |
+---------------+--------------------------------------+
.. note::
The *Next Run Time* is the next time the audit will run. It is calculated based on the
interval and the start and end times.
List Generated Action Plans
---------------------------
Each execution of the continuous audit generates a new action plan:
.. code-block:: bash
$ openstack optimize actionplan list --audit 7d1f1961-41a6-47ae-a94a-cf5e43174fbd
+--------------------------------------+--------------------------------------+-------------+
| UUID | Audit | State |
+--------------------------------------+--------------------------------------+-------------+
| b301dd17-a139-4a45-ade2-b2c2ddf006ef | 7d1f1961-41a6-47ae-a94a-cf5e43174fbd | CANCELLED |
| 22a5bc60-adef-447a-aa27-731b4f5f7ee3 | 7d1f1961-41a6-47ae-a94a-cf5e43174fbd | RECOMMENDED |
+--------------------------------------+--------------------------------------+-------------+
.. note::
In continuous audits, when a new action plan is generated, previous
RECOMMENDED action plans are automatically set to CANCELLED state to
avoid conflicts.
Manage Continuous Audits
========================
Stop a Continuous Audit
------------------------
To stop a continuous audit, update its state:
.. code-block:: bash
$ openstack optimize audit update 550e8400-e29b-41d4-a716-446655440000 replace state=CANCELLED
Modify Audit Interval
---------------------
You can change the interval of a running continuous audit:
.. code-block:: bash
$ openstack optimize audit update 550e8400-e29b-41d4-a716-446655440000 replace interval=900
The Decision Engine will automatically reschedule the audit with the new
interval.
Modify End Time
---------------
You can change the end time of a running continuous audit:
.. code-block:: bash
$ openstack optimize audit update 550e8400-e29b-41d4-a716-446655440000 replace end_time=2025-08-12T14:00:00
Delete a Continuous Audit
--------------------------
In order to delete a continuous audit, the audit state must be
SUCCEEDED, FAILED, or CANCELLED.
An audit with PENDING or ONGOING state cannot be deleted.
To delete an ongoing or pending continuous audit, update its state to
CANCELLED:
.. code-block:: bash
$ openstack optimize audit update 550e8400-e29b-41d4-a716-446655440000 replace state=CANCELLED
Then, delete the audit:
.. code-block:: bash
$ openstack optimize audit delete 550e8400-e29b-41d4-a716-446655440000
Configuration Reference
========================
Continuous Audit Intervals
---------------------------
**Numeric Intervals (seconds):**
- Minimum recommended: 60 seconds
- Common values: 300 (5 min), 600 (10 min), 1800 (30 min), 3600 (1 hour)
**Cron Expressions (5 format fields):**
See the `POSIX crontab specification <https://pubs.opengroup.org/onlinepubs/9799919799/utilities/crontab.html>`_.
- ``0 * * * *``: Every hour at minute 0
- ``*/15 * * * *``: Every 15 minutes
- ``0 9-17 * * 1-5``: Every hour during business hours (9 AM - 5 PM, Mon-Fri)
- ``30 2 * * *``: Daily at 2:30 AM
Decision Engine Configuration
-----------------------------
The continuous audit polling interval is configured in ``watcher.conf``:
.. code-block:: ini
[watcher_decision_engine]
# Interval for checking continuous audits (seconds)
continuous_audit_interval = 30
Spec Linked with Continuous Audit
=================================
- `Watcher Continuous Optimization <https://specs.openstack.org/openstack/watcher-specs/specs/newton/implemented/continuously-optimization.html>`_
- `Cron-based continuous audits <https://specs.openstack.org/openstack/watcher-specs/specs/pike/implemented/cron-based-continuous-audits.html>`_
- `Add the start and end time for CONTINUOUS audit <https://specs.openstack.org/openstack/watcher-specs/specs/stein/implemented/add-start-end-time-for-continuous-audit.html>`_

1
doc/source/user/index.rst
View File

@@ -8,3 +8,4 @@ User Guide
ways-to-install
user-guide
event_type_audit
continuous_type_audit