Nova Server Count API 扩展

https://blueprints.launchpad.net/nova/+spec/server-count-api

该蓝图提出一个新的 REST API 扩展，用于返回匹配指定搜索条件的服务器数量。

问题描述

目前没有 API 可以检索与各种搜索过滤器匹配的服务器的摘要计数数据。例如，获取给定状态下的服务器总数。

检索所有服务器然后手动确定计数数据无法扩展，因为必须实现分页查询（有关详细说明，请参阅“替代方案”部分）。

推动此 API 扩展的用例源自用户在 GUI 中的体验。

用例 1：一个 UI 仪表板，其中包含云管理员的各种状态下的服务器。需要一个新的 API 扩展来检索与各种过滤器相关（例如，处于活动状态的服务器、处于构建状态的服务器、处于错误状态的服务器等）的服务器计数数据，用于整个云。

假设您的云中有 5k 个实例。管理员希望查看每个状态下实例的摘要 – 此 API 扩展将帮助他们快速确定是否存在需要关注的问题；例如，如果有很多实例处于“错误”状态。管理员在看到此计数后，很可能会深入研究数据。但是，如果没有此新的 API 扩展，管理员将不知道在没有深入研究每个集合的情况下，给定状态下是否有不可接受数量的系统。

从部署者的角度来看，使用现有 API 创建此仪表板非常痛苦，因为需要分页（假设超过默认的 1k 个项目）。此外，使用现有 API（即使是非详细的 API）获取此数据所花费的处理时间很慢（并且可能不准确 – 参见 #3），与获取和返回单个数字的处理时间相比。

用例 2：在 UI 中的表格中显示过滤后的数据。假设 UI 支持显示过滤后的数据的表格（例如，仅显示处于“错误”状态的实例），并使用分页来获取数据。许多用户不喜欢“无限滚动”，因为他们不知道列表中真正有多少项目（更多只是在向下滚动或导航到下一页时显示）。使用这个新的计数 API，UI 表格可以指示列表中总共有多少项目（例如，显示 1-20 共 1000 个）。

假设您有 500 个处于错误状态的实例，并且您可以打开一个 UI 表格来显示它们的详细信息 – 在创建表格时，假设 UI 使用页面大小为 100，并且假设没有显示“错误”计数的仪表板。在这种情况下，管理员登录到 UI 并想知道有多少服务器处于错误状态。为此，管理员导航到“处于错误状态的服务器”表格 – UI 仅检索前 100 个项目，因此不可能知道总共有 101 个项目还是 500 个项目。作为管理员，我想知道表格中的项目总数是多少。

用例 3：在使用 limit/marker 处理添加新项目时的固有时间窗口。假设您正在使用分页来迭代数据以获取计数。当您获取第 n 页时，有可能第 n-1 页有一个新项目 x 刚刚添加。由于数据的排序，limit/marker 将无法检测到添加了这个新项目。

虽然这个时间窗口很小，但它确实存在，因此使用这种方法获取准确的计数并不能保证准确性。

我知道您可以争辩说计数 API 也可能无法处理这个 UI 用例。但是，计数将始终是数据库在处理 .count() 函数时的准确值 – 不能对使用 limit/marker 获取计数提出相同的声明，因为正在调用多个数据库调用来计算数量。

提议的变更

新的计数 API 扩展必须接受与现有 /servers 和 /servers/details API 相同的过滤器值，并重用现有的过滤器处理（一旦公共部分重构为可以由两个路径利用的实用程序方法）。一旦过滤器被处理以创建查询对象，就会从数据库中检索并返回匹配的服务器数量。

计数 API 扩展将同时适用于租户和全局（仅限管理员），类似于现有的 /servers API。管理员可以提供 ‘all_tenants’ 参数来表示应全局检索服务器计数数据。

此新流程需要在计算 API 层、实例层和数据库层中创建新的函数来检索计数值；所有函数都返回一个整数值。函数的命名约定将遵循用于检索服务器实例的现有函数，例如

  • 计算 API：get_count 函数

  • 实例层（InstanceList 类）：get_count_by_filters 函数

  • DB 层：instance_count_by_filters 函数

  • Sqlalchemy 层：instance_count_by_filters 函数

在 sqlalchemy DB 层中，过滤器处理（用于处理精确名称过滤器、正则表达式过滤器和标签过滤器）需要移动到公共函数中，以便新的计数 API 扩展和现有的获取服务器 API 都可以利用它。创建查询对象后，将调用 count() 函数以检索给定查询的匹配服务器总数。

对于 v2 API 扩展，现有在 nova.api.openstack.compute.servers.Controller._get_servers 中完成的过滤预处理需要移动到静态实用程序方法中，以便新的计数 API 扩展可以利用它；这对于确保计数 API 的过滤支持与 /servers API 的过滤支持匹配至关重要。

对于 v3 API，需要将一个新的计数函数（类似于“index”和“detail”）添加到 nova.api.openstack.compute.plugins.v3.servers 中。公共过滤器处理需要分解为实用程序函数（与 v2 API 相同）。对于 v3，可以将“count” GET API 直接注册到 nova.api.openstack.compute.plugins.v3.servers.V3APIExtensionBase。

备选方案

其他 API 存在返回计数数据（配额和限制），但它们不接受过滤器值。

用户可以使用现有的非详细的 /servers API 和过滤器，然后计算结果来完成相同的结果（减去用例 #3 中注意到的时间窗口）。但是，此蓝图的主要用例是在规模上获取摘要计数数据。例如，如果整个云中有 5k 个 VM，那么使用分页查询来迭代带有过滤器和 limit/marker 的非详细的“/servers” API 效率非常低 – API 将返回用户关心的更多数据（并进行大量处理来获取它）。假设有 2,500 个实例处于活动状态；如果使用非详细查询（以及默认限制为 1k），则应用程序必须发出 3 个单独的 REST API 调用才能获取所有 VM，并且在 DB 层，将使用 marker 处理来查找要返回的正确页面数据。由于用户只关心摘要计数，因此最有效的机制是使用 count() 函数进行单个 DB 查询。

请注意，服务器上设置了默认的最大页面集（默认值为 1k）；因此，用户必须处理分页，因为正在查询的项目数量可能大于默认值。

还有其他选项可以注册 v2 和 v3 API。对于 v2，可以通过直接修改 nova.api.openstack.compute.__init__.APIRouter 中的 API 路由来注册新的计数 API（就像 /server/detail 一样）。由于 v3 仍然是实验性的，此蓝图建议将计数 API 嵌入到 nova.api.openstack.compute.plugins.v3.servers 中。

我想不到替代实现。新的 API 需要利用现有的过滤器处理，就像当前的 /servers API 一样，以确保一致性并防止双重维护。

数据模型影响

无

REST API 影响

现有 /servers 和 /servers/detail REST API 的响应不受影响。

  • 新的 v2 API 扩展

    • 名称：ServerCounts

    • 别名：os-server-counts

  • 新的 v2 URL：v2/{tenant_id}/servers/count

  • 新的 v3 URL：v3/servers/count

  • 描述：获取服务器数量

  • 方法类型：GET

  • 正常响应代码：与“v2/{tenant_id}/servers/detail”API 相同）

    • 200

    • 203

  • 错误响应代码（与“v2/{tenant_id}/servers/detail”API 相同）

    • computeFault (400, 500, …)

    • serviceUnavailable (503)

    • badRequest (400)

    • unauthorized (401)

    • forbidden (403)

    • badMethod (405)

  • 参数（与“v2/{tenant_id}/servers”API 相同，但除“limit”和“marker”参数外）

参数

风格

类型

描述

all_tenants（可选）

query

xsd:boolean

显示所有租户的服务器计数信息（仅限管理员）。

changes-since（可选）

query

xsd:dateTime

服务器上次更改状态的时间/日期戳。

image（可选）

query

xsd:anyURI

镜像名称的 URL 格式。

flavor（可选）

query

xsd:anyURI

风味的名称的 URL 格式。

name（可选）

query

xsd:string

服务器名称作为字符串。

status（可选）

query

csapi:Server Status

服务器状态的值，以便您可以过滤“ACTIVE”例如。

  • JSON 模式定义用于主体数据：N/A

  • JSON 模式定义用于响应数据：{“count”: <int>}

安全影响

无

通知影响

无

其他最终用户影响

无

性能影响

无 – 此新的 API 不会引入任何新的 DB 连接，从而影响性能。

其他部署者影响

无

开发人员影响

无

实现

负责人

主要负责人

Steven Kaufer

其他贡献者

<launchpad-id 或 None>

工作项

  • 将过滤器处理代码移动到 API 层和 DB sqlalchemy 层的实用程序函数中。

  • 在各个层中创建新的 API 函数来获取计数数据。

  • v2 API 扩展和 v3 API 更新以公开新的计数 API 函数。

依赖项

相关的（但独立的）变更正在 cinder 中提出：https://blueprints.launchpad.net/cinder/+spec/volume-count-api

测试

需要创建单元和 Tempest 测试，以确保计数数据对于各种过滤器是准确的。

应针对多种后端数据库类型进行测试。

文档影响

记录新的 v2 API 扩展和 v3 API 更新（有关详细信息，请参阅“REST API 影响”部分）。

参考资料

无