添加 v2 API 端点以重置不同范围的状态¶

https://storyboard.openstack.org/#!/story/2005395

CloudKitty 需要在其 v2 API 中添加一个端点来重置一个或多个范围的状态。本规范旨在定义需要做什么以及原因。本文档中的所有内容均可讨论，同样适用于相关的故事板和 gerrit。

问题描述¶

目前 CloudKitty 的状态是，如果管理员出于任何原因希望重置给定范围的计算，例如 CloudKitty 的收集配置更改、某些评级规则的更新等，他必须停止所有处理器，更新数据库中该范围的状态，然后重新启动所有处理器。这是一个繁琐的过程，我们应该以新的 v2 API 端点的形式为最终用户提供一种更简便的方法。

提议的变更¶

将向管理员用户提供一个在 PUT /v2/scope 上可用的端点，其参数与 GET /v2/scope 端点上的过滤参数相对相似。这将允许最终用户一次重置多个范围的状态（如果他们愿意）。稍后会详细介绍一个额外的参数，用于防止最终用户过快地执行任何不可逆转的更改。

备选方案¶

我们只能允许在 PUT /v2/scope/<scope_id> 上重置范围状态，但这会阻止最终用户一次重置多个范围状态，并且会强制每次范围状态重置尝试都需要一个请求。

此外，可以将请求影响的范围列表返回给最终用户，但我们已经有一个指定的端点 GET /v2/scope 用于此用例。因此，这没有必要，并且不会为预期的使用增加不必要的复杂性。

数据模型影响¶

无。

REST API 影响¶

这将添加一个在 /v2/scope 上的端点，并支持 PUT HTTP 方法。

该端点将支持以下参数

all_scopes：（与 scope_id 互斥，默认为 False）是否一次性针对所有范围。此参数旨在防止最终用户过快地犯错。如果同时缺少或同时存在 all_scopes 和 scope_id 参数，则请求不会影响任何数据，并且将返回 400 Bad Request 响应。
scope_id：（与 all_scopes 互斥）可以多次指定。要用于筛选以重置关联范围状态的一个或多个 scope_id。如果同时缺少或同时存在 all_scopes 和 scope_id 参数，则请求不会影响任何数据，并且将返回 400 Bad Request 响应。
collector：（可选）可以多次指定。要用于筛选以重置关联范围状态的一个或多个 collector。
fetcher：（可选）可以多次指定。要用于筛选以重置关联范围状态的一个或多个 fetcher。
scope_key：（可选）可以多次指定。要用于筛选以重置关联范围状态的一个或多个 scope_key。

由于范围状态重置是一项耗时的操作，并且依赖于底层的 AMQP 系统，因此它将是对 API 的异步调用，并在消息队列中发送通知后，以 202 Accepted 向调用者响应。此请求的响应体为空。

因此，对此端点上 PUT 请求的预期 HTTP 成功响应代码是 202 Accepted。

对此端点上 PUT 请求的预期 HTTP 错误响应代码是

400 Bad Request：请求格式错误。当同时存在或同时缺少 all_scopes 和 scope_id 参数时，也会发生这种情况。
403 Forbidden：用户无权重置任何范围的状态。
404 Not Found：未找到提供的参数的范围。

此端点仅授权给管理员。

安全影响¶

任何访问此端点的用户都可以对一个或多个范围执行范围状态重置，这是一项具有严重副作用的操作。因此，应谨慎授予非管理员用户访问此端点的权限，或者如果可能，根本不授予权限。

通知影响¶

将向 AMQP 侦听器发送通知，以触发范围状态重置。要发送的通知的结构如下

{
   "scopes": [
       {
           "collector": "gnocchi",
           "fetcher": "keystone",
           "scope_id": "7a7e5183264644a7a79530eb56e59941",
           "scope_key": "project_id"
       },
       {
           "collector": "gnocchi",
           "fetcher": "keystone",
           "scope_id": "9084fadcbd46481788e0ad7405dcbf12",
           "scope_key": "project_id"
       },
       {
           "collector": "gnocchi",
           "fetcher": "keystone",
           "scope_id": "1f41d183fca5490ebda5c63fbaca026a",
           "scope_key": "project_id"
       }
    ]
}

其他最终用户影响¶

客户端也将更新，以便包含一个函数和一个 CLI 命令，允许重置一个或多个给定范围的状态。

性能影响¶

范围状态重置调用所执行的删除操作取决于目标范围关联的数据量，并且可能会耗时，同时会损害数据库性能。

其他部署者影响¶

范围状态重置将不再是一个棘手而繁琐的过程，并将使管理员和部署者受益于操作范围。

开发人员影响¶

无。

实现¶

负责人¶

主要负责人: <jferrieu>
其他贡献者: <peschk_l>

工作项¶

使用单元测试实现 API 端点
添加 tempest 测试
在客户端中支持此端点。

依赖项¶

无。

测试¶

将添加该端点的 tempest 测试。

文档影响¶

该端点将被添加到 API 参考中。

参考资料¶

获取/重置范围状态的规范：https://specs.openstack.org/openstack/cloudkitty-specs/specs/train/reset_scope_state.html

添加 v2 API 端点以重置不同范围的状态