为运行动作计划添加跳过观察者动作的机制

https://blueprints.launchpad.net/watcher/+spec/add-skip-actions

观察者服务应允许在两种情况下从动作计划执行中排除动作

• 云管理员明确希望在启动动作计划之前排除一个或一组动作的执行。

• 观察者应用程序检测到应用动作的对象处于不应应用动作的状态。例如，在迁移动作中，实例不再存在。

问题描述

当前观察者没有提供在运行动作计划时排除动作执行的方法

• 管理员缺乏标准化的机制来预先跳过动作。

• 预条件失败与执行失败没有明确区分。

请注意，动作已经包含 其状态机 中的 CANCELLED 状态，但它仅用于两种特定情况

• 当动作计划被取消时，包含的所有动作都将被移动到 CANCELLED 状态。

• 当 watcher-applier 进程启动时，分配给它的所有处于 ONGOING 状态的动作都将被移动到 CANCELLED 状态（参见 此链接）。

本规范的目的是记录观察者中实现这两种使用情况的动作执行排除所需的更改。

用例

• 管理员覆盖：管理员可以使用补丁 API 调用将动作状态从 PENDING 移动到 SKIPPED，以便在执行动作计划时不会执行该动作。

• 预条件检测：当动作的 pre_condition 方法返回特定类型的异常时，该动作将被移动到 SKIPPED，并且不会执行执行和后置条件。

在两种情况下，可以提供一个 status_message 并将其存储在数据库中。 类似地，一个 status_message 字段将被添加到 ActionPlan 对象中，用于提供有关跳过的动作的信息。 为了保持一致性，status_message 也将被添加到 Audit 对象中，未来将用于存储与状态更改相关的信息。

提议的变更

当前，动作的状态机从 PENDING 状态提供以下转换

• PENDING -> CANCELLED（在动作开始之前取消动作计划）

• PENDING -> ONGOING（开始动作执行）

• ONGOING -> CANCELLED（在动作运行时取消动作计划）

• ONGOING -> SUCCEEDED（动作成功完成）

• ONGOING -> FAILED（动作执行失败）

本规范中提出的更改是添加一个新的状态 SKIPPED，它表示动作被排除在动作计划执行之外，原因在于上述任何一种使用情况。

在此更改之后，此外，动作的状态机将允许以下状态转换

• PENDING -> SKIPPED（在开始之前将动作排除在执行之外）

• PENDING -> FAILED（动作在预条件中以意外错误失败）

请注意，从 PENDING 到 SKIPPED 的转换可以由云管理员使用 API 调用触发，或者在观察者检测到预条件执行中某些预定义的条件时自动触发。 将动作从 PENDING 转换为 ONGOING 应意味着预条件执行成功完成。 在预条件执行中以任何不同于预定义条件的错误失败的动作将在移动到 ONGOING 状态之前将状态更改为 FAILED。

处于 SKIPPED 状态的动作不会影响动作计划的最终状态。 只有当执行完成时，一个或多个动作处于 FAILED 状态时，动作计划才会被认为 FAILED。 但是，为了向用户提供有关执行的实际结果的详细信息，将向动作计划添加一个新字段 status_message，该字段将在跳过一个或多个动作时使用相关信息进行更新。

对于预条件检测用例，将创建一个新的异常类 ActionSkipException。 当 pre_condition 抛出它时，正在进行的动作将被切换到 SKIPPED 状态，并且 status_message 将基于异常消息添加。

对于管理员覆盖用例，将向 Actions 添加一个新的补丁 API 调用方法，该方法仅允许在父动作计划也处于 PENDING 状态时将状态从 PENDING 更改为 SKIPPED 状态。 在这种情况下，一个注释 由用户跳过 将包含在 status_message 中。 可选地，用户可以向消息添加更多详细信息。

此外，应在 python-watcherclient 和 watcher-dashboard 中包含对 API 更改的支持，以便云管理员可以从 PENDING 状态跳过一个动作，并查看 SKIPPED 动作的 status_message 值。

观察者 API 的微版本将针对此更改增加如下

• 新的动作状态 SKIPPED 不会被视为微版本化的。 这意味着动作状态的值将是相同的，无论使用的观察者 API 微版本如何。

• 新的字段 status_message 将包含在新微版本中的 Action、ActionPlan 和 Audit 对象中，因此它仅在使用了新微版本或更高版本时才包含在相应的 API 调用中。 使用以前的版本时，新字段将不包含在 API 响应中。

• 新的补丁 API 调用仅在使用了新微版本或更新版本时可用。

备选方案

在审查本规范期间，讨论了多个方面并做出了决定。 最重要的方面是

SKIPPED 与重用 CANCELLED

与其创建一个新的 SKIPPED 状态，我们可以重用现有的 CANCELLED 状态来涵盖这两个新的用例。 在讨论了这一选项后 在 irc <https://meetings.opendev.org/irclogs/%23openstack-watcher/%23openstack-watcher.2025-05-13.log.html#openstack-watcher.2025-05-13.log.html#t2025-05-13T12:53:54>_，我们认为它会导致 CANCELLED 动作的实际情况产生歧义，因为多种且非常不同的情况可能导致它。

通过此提案，SKIPPED 状态仅限于用于从未在已执行的动作计划中实际执行的动作。

使用 PATCH 与 PUT 或 POST API 调用

本规范中 API 更改的另一种方法是在 /v1/action_plans/{plan_id}/actions/{action id or index} 上使用 POST 调用。 虽然这将遵循 REST API 实现的最佳实践，并且更正确地将动作显示为 ActionPlan 的内部元素，但批准的实现与观察者中现有的 API 方法以及 API 中动作的当前表示方式作为顶级元素更加一致。

动作计划状态，当动作被跳过时

本规范提案不会修改完成的动作计划的状态，当其包含的任何动作被用户或预条件失败跳过时。 此外，status_message 字段将用于让用户知道如果确实跳过了动作，即使动作计划处于 SUCCEEDED 状态，因为已经认为这对于用户来说是相关信息。

这种方法的替代方案是在 ActionPlans 中创建一个特定的字段 skipped_actions 来专门提供该信息，或者创建一个新的状态 SUCCEDED_WITH_SKIPPED，该状态将用于自动跳过动作的动作计划。

但是，已经认为使用新的通用字段 status_message 更合适且可重用，以便在未来提供更多详细信息（例如，对于 FAILED 动作），并且 SUCCEEDED 状态可以正确地表示实际状态，因为专门由用户决定或由观察者检测到导致动作进入 SKIPPED 而不是 FAILED 状态的预定义条件自动跳过动作。

将 status_message 添加到 Audits

虽然审计状态不受拟议用例的直接影响，但已确定 status_message 字段对审计也很有用。 已经决定将其包含在相同的 API 微版本中，以保持 API 对象和客户端之间的一致性。

数据模型影响

• 在 Actions 表中添加一个新列 status_message，类型为 String(255)。

• 在 ActionPlans 表中添加一个新列 status_message，类型为 String(255)。

• 在 Audits 表中添加一个新列 status_message，类型为 String(255)。

REST API 影响

在新微版本中，以下 API 响应将被扩展

• 新字段 status_message 将包含在 actions 中

  • GET /v1/actions/detail

  • GET /v1/actions/``{action_id}

  Return code(s) 中没有更改。

  在 GET /v1/actions/``{action_id} 响应中添加 json 的示例

  {
      "state": "SKIPPED",
      "description": "Logging a NOP message",
      "status_message": "Skipped by user",
      ....
  }
  

• 新字段 status_message 将包含在 actionplans 中

  • GET /v1/actionplans/detail

  • GET /v1/actionplans/``{action_id}

  Return code(s) 中没有更改。

  在 GET /v1/actionplans/``{actionplan_id} 响应中添加 json 的示例

  {
      "state": "SUCCEEDED",
      "status_message": "Action XXX was skipped by user",
      ....
  }
  

• 新字段 status_message 将包含在 audits 中

  • GET /v1/audits/detail

  • GET /v1/audits/``{audit_id}

  Return code(s) 中没有更改。

  在 GET /v1/audits/``{audit_id} 响应中添加 json 的示例

  {
      "state": "CANCELED",
      "status_message": "Audit was canceled by user",
      ....
  }
  

• 将在 /v1/actions/``{action_id} 上添加一个新的 Patch 方法，用于跳过 PENDING 状态中的 Action。

  正常响应代码：200

  错误代码：400,409,404

  跳过 PENDING 动作的请求示例

  [
      {
          "op": "replace",
          "value": "SKIPPED",
          "path": "/state"
      },
      {
          "op": "add",
          "value": "Exclude migration of intance foo",
          "path": "/status_message"
      },
  ]
  

  尝试补丁一个不存在的 Action 将返回 404 错误。

  使用 Patch API 方法在任何不同于 PENDING 的状态下跳过动作的请求将返回 409 错误。

  API Patch 调用允许修改处于 SKIPPED 状态的动作的 status_message 字段。

安全影响

没有安全影响。

通知影响

动作、动作计划和审计通知将扩展为包含新添加的字段。

其他最终用户影响

将在 watcherclient 中实现以下更改

• 新字段 status_message 将包含在命令中

  openstack optimize action show <action id>
  

• 将向 优化动作 命令添加一个新选项 skip

  openstack optimize action update --state skipped --message <message> <action id>
  

将在 watcher-dashboard 包中实现类似的功能，以执行相同的操作并从 horizon 仪表板获取类似的信息。

性能影响

预计没有性能影响。

其他部署者影响

没有新的配置参数或对部署者的任何其他影响

开发人员影响

无

实现

负责人

主要负责人

amoralej

工作项

• 在 Actions 表中添加一个新字段。

• 在 Actions GET REST API 中添加一个新字段

• 添加一个新的异常类型，如果 pre_condition 抛出它，则将正在进行的动作移动到 SKIPPED 状态。

• 向 actions api 添加一个新的补丁方法，以跳过待处理的动作。

• 在 watcherclient 中添加支持。

• 在 watcher-dashboard 中添加支持。 * 在 ActionPlans 详细视图的 相关动作 中包含新的字段 status_message。 * 此外，也可以在动作详细视图中添加一个 跳过 按钮。

依赖项

无

测试

现有的单元和 API 测试将扩展为验证新的微版本包含 status_message。

单元测试将验证在 pre_condition 中引发新的异常的动作，会将动作移动到 SKIPPED 状态。

单元测试以测试 actions 上的新补丁方法。

新的 tempest 测试，以测试动作跳过功能，包括可选字段 status_message。

文档影响

• API 参考

• REST API 版本历史记录

• watcher client

参考资料

历史

修订版

Flamingo	描述
2025.2	引入