REST API 版本历史¶

本文档记录了每次微版本变更对 REST API 所做的更改。每个版本的描述都应详细，包含足够的信息，以便在用户文档中使用。

3.0 (Mitaka 中的最大版本)¶

Cinder 3.0 API 包含在引入微版本之前存在的所有 v2 核心 API。使用 /v3 URL 调用 3.0 API。这是 Cinder API 的初始版本，支持微版本。

用户可以在 API 请求中指定一个 header

OpenStack-API-Version: volume <version>

其中 <version> 是此 API 的任何有效 API 版本。

如果未指定版本，则 API 将表现得好像请求了版本 3.0。

版本 3.0 中唯一的 API 变更为 versions，即 GET https://:8786/，现在返回有关 3.0 及更高版本及其各自 /v3 端点的信息。

所有其他 3.0 API 在功能上与版本 2.0 相同。

3.1¶

为 _volume_upload_image 请求添加了参数 protected 和 visibility。

3.2¶

根据卷的“bootable”状态作为过滤器，获取 cinder 卷列表的 ‘GET API 请求’ 的返回值变更。

在 V3.2 之前，如果 bootable 过滤器值为 false 或 False 中的任何一个，则 ‘GET API 请求’ 获取卷列表将返回不可启动的卷。对于提供给此过滤器的任何其他值，它始终返回可启动的卷列表。

但在 V3.2 中，此行为已更新。在 V3.2 中，只有当 bootable 过滤器值为 ‘T/True/1/true’ 中的任何一个时，才会返回可启动的卷列表。对于 ‘F/False/0/false’ 中的任何 bootable 过滤器值，将返回不可启动的卷列表。但对于传递给 bootable 过滤器的任何其他值，它将返回“无效输入：bootable={filter value}”错误。

3.3¶

添加了 /messages API。

3.4¶

为 list/detail volumes 请求添加了过滤器参数 glance_metadata。

3.5¶

为 /messages API 添加分页支持

3.6¶

允许在 consisgroup-update 操作中设置空描述和空名称，以保持一致性组的一致性。

3.7¶

为 service list/detail 添加了 cluster_name 字段。

添加了 /clusters 端点以列出/显示/更新集群。

Show 端点需要集群名称，并可选地将二进制作为 URL 参数（默认为“cinder-volume”）。返回

{
    "cluster": {
        "created_at": "",
        "disabled_reason": null,
        "last_heartbeat": "",
        "name": "cluster_name",
        "num_down_hosts": 4,
        "num_hosts": 2,
        "state": "up",
        "status": "enabled",
        "updated_at": ""
    }
}

Update 端点允许以类似于 service 的 update 端点的方式启用和禁用集群，但在主体中我们必须指定名称，并可选地指定二进制（“cinder-volume”是默认值）和禁用原因。返回

{
    "cluster": {
        "name": "cluster_name",
        "state": "up",
        "status": "enabled",
        "disabled_reason": null
    }
}

Index 和 detail 接受按 name、binary、disabled、num_hosts、num_down_hosts 以及 up/down 状态 (is_up) 作为 URL 参数进行过滤。

Index 端点返回

{
    "clusters": [
        {
            "name": "cluster_name",
            "state": "up",
            "status": "enabled"
        }
    ]
 }

Detail 端点返回

{
    "clusters": [
        {
            "created_at": "",
            "disabled_reason": null,
            "last_heartbeat": "",
            "name": "cluster_name",
            "num_down_hosts": 4,
            "num_hosts": 2,
            "state": "up",
            "status": "enabled",
            "updated_at": ""
        }
    ]
}

3.8¶

添加了先前在扩展中存在的以下资源

os-volume-manage => /v3/<project_id>/manageable_volumes
os-snapshot-manage => /v3/<project_id>/manageable_snapshots

3.9¶

添加了用于更改名称和描述的备份更新接口。返回

{
    "backup": {
        "id": "backup_id",
        "name": "backup_name",
        "links": "backup_link"
    }
}

3.10¶

为 list/detail volumes 请求添加了过滤器参数 group_id。

3.11¶

添加了组类型和组规范 API。

3.12¶

添加了 volumes/summary API。

3.13¶

添加了用于通用卷组的创建/删除/更新/列出/显示 API。

3.14¶

添加了组快照和从 src 创建组的 API。

3.15 (Newton 中的最大版本)¶

添加了将响应的 Etag header 注入以避免卷元数据丢失更新问题。

3.16¶

os-migrate_volume 现在接受 cluster 参数，当我们想要将卷迁移到集群时。如果传递了卷的 host 参数，并且该卷位于集群中，则请求将发送到集群，就好像请求了特定的集群一样。只能提供 host 或 cluster。

创建托管卷也支持 cluster 参数。

3.17¶

os-snapshot-manage 和 os-volume-manage 现在支持在列表（摘要和详细）上使用 cluster 参数。这两个位置参数，cluster 和 host 是排斥性的，并且只能提供一个。

3.18¶

添加了备份项目属性。

3.19¶

为组快照添加了 reset_status 操作。

3.20¶

为通用卷组添加了 reset_status 操作。

3.21¶

在管理员的卷详细视图中显示 provider_id。

3.22¶

添加了基于快照元数据过滤快照列表的支持。

3.23¶

允许将 force 参数传递给卷删除。

3.24¶

新的 API 端点 /workers/cleanup 允许触发 cinder-volume 服务的清理。用于清理失败节点上正在进行的操作。

清理将由属于同一集群的其他服务执行，因此至少必须有一个服务处于启动状态才能执行清理。

无法在云升级期间触发清理。

如果未提供任何参数，清理将尝试为所有处于关闭状态的节点发出清理请求，但我们可以使用参数 service_id、cluster_name、host、binary 和 disabled 来限制我们要清理哪些节点。

也可以使用 resource_type 和 resource_id 参数清理特定资源。

我们甚至可以使用 is_up 强制清理处于启动状态的节点，但不建议这样做，只有在您知道自己在做什么的情况下才应该这样做。例如，如果您知道特定的 cinder-volume 处于关闭状态，但它仍然未在列出服务时报告为关闭状态，并且您知道集群中至少还有另一个服务可以执行清理。

API 将返回一个字典，其中包含两个列表，一个包含已发出清理请求的服务 (cleaning 键)，另一个包含无法立即清理的服务，因为该集群中没有替代服务可以执行清理 (unavailable 键)。

在这些两个列表中，每个服务元素返回的数据包括 id、host、binary 和 cluster_name。这些不是将执行清理的服务，而是将被清理或无法清理的服务。

3.25¶

将 volumes 字段添加到组列表/详细信息和组显示中。

3.26¶

新的 failover 操作等效于 failover_host，但同时接受 cluster 参数以及 failover_host 接受的 host。
freeze 和 thaw 操作接受 cluster 参数。
集群列表接受 name、binary、disabled、num_hosts、num_down_hosts 以及 up/down 状态 (is_up) 作为 URL 参数进行过滤，并返回每个集群的附加字段：replication_status、frozen、active_backend_id。

3.27 (Ocata 中的最大版本)¶

添加了新的附件 API。有关详细信息，请参阅 API 参考。

3.28¶

添加了对 get_pools 的过滤器支持

3.29¶

在组快照中添加了过滤器、排序器和分页支持。

3.30¶

支持按“name”对快照进行排序。

3.31¶

添加了对配置资源查询过滤器支持。

3.32¶

添加了 set-log 和 get-log 服务操作。

3.33¶

添加 resource_filters API 以检索配置的资源过滤器。

3.34¶

在 volume、backup、snapshot、message、attachment、group 和 group-snapshot 列表 API 中添加了 like 过滤器支持。

3.35¶

为 Get-Pools API 添加 volume-type 过滤器。

3.36¶

将元数据添加到 volumes/summary 响应主体。

3.37¶

支持按“name”对备份进行排序。

3.38¶

添加了 enable_replication/disable_replication/failover_replication/ list_replication_targets 用于复制组（Tiramisu）。

3.39¶

为限制添加 project_id 管理员过滤器支持。

3.40¶

添加了将卷恢复到其最新快照的支持。

3.41¶

为快照列表/详细信息和快照显示添加了 user_id 字段。

3.42¶

添加了扩展“使用中”卷的能力。用户应注意整个环境，然后再使用此功能，因为它取决于以下几个外部因素

nova-compute 版本 - 需要 Pike 的最新版本。
目前仅支持 libvirt 计算驱动程序。
目前 nova 端仅支持 iscsi 和光纤通道卷类型。

管理员可以通过更新 volume:extend_attached_volume 策略规则来禁用此能力。不允许扩展保留的卷。

3.43 (Pike 中的最大版本)¶

支持带有元数据的备份 CRUD。

3.44¶

支持附件完成。有关详细信息，请参阅 API 参考。

3.45¶

在卷、备份和快照列表和详细 API 中添加了 count 字段。

3.46¶

修改了在请求主体中传递 imageRef 时 volume-create (POST /v3/volumes) 的行为。在微版本之前，镜像只是下载并写入卷。但是，当卷附加到服务器时，可以使用 Compute API 服务器 createImage 操作创建卷的实例快照。这是一个在 Image Service 中具有零字节图像的图像，其 block_device_mapping 图像属性的值包含 snapshot 作为 source_type 和对 Block Storage 服务中卷快照的 snapshot_id 引用。从微版本 3.46 及更高版本开始，当发出引用此类图像的 volume-create 请求时，将使用它引用的快照而不是使用该图像来创建卷。

注意

由于 cinder 对与图像相关的 CVE 的更改，使用引用 nova 实例快照且微版本低于 3.46 的 imageRef 进行 volume-create 调用可能会创建一个状态为 error 的卷。当图像的 disk_format 属性不是 raw 时，会发生这种情况，因为对于非原始格式，即使图像不包含任何数据，也包含超过零字节的数据，因此图像被拒绝，因为它与声明的格式不同。

3.47¶

支持从备份创建卷。

3.48¶

在卷中添加 shared_targets 和 service_uuid 字段。

3.49¶

支持在服务列表中报告后端存储状态。

3.50 (Queens 的最大版本)¶

支持此微版本的服务能够进行卷多重挂载。创建卷时不需要请求此版本，但可以用作查询 Cinder 服务中是否存在此功能的一种方式。

3.51¶

添加对跨 AZ 备份的支持。

3.52¶

RESKEY:availability_zones 是 AZ 卷类型的保留规范键，并且现在支持通过 extra_specs 过滤卷类型。

3.53¶

已使用 jsonschema 为 V2/V3 卷 API 添加了模式验证支持。

创建卷 API
在 3.53 之前，创建卷 API 接受请求体中的任何无效参数，例如 python-cinderclient 传递的以下参数。
1. user_id
2. project_id
3. status
4. attach_status
但在 3.53 中，此行为已更新。如果用户传递任何未在 api-ref 中记录的无效参数，则会引发 badRequest 错误。
更新卷 API
在 3.53 之前，即使用户没有传递任何有效参数到请求体中，卷也会被更新。但在 3.53 中，用户需要传递至少一个有效参数到请求体中，否则会返回 400 错误。

3.54¶

在 attachment-create 中添加 mode 参数。

3.55 (Rocky 的最大版本)¶

支持将快照与其父卷一起传输的能力。

3.56¶

在列出带有详细信息的备份和显示备份详细信息 API 的响应体中添加 user_id 属性。

3.57¶

通过在 transfer 表和相关 api（创建/显示/列出详细传输 API）响应中添加 source_project_id、destination_project_id 和 accepted 字段来扩展卷传输记录详细信息。

3.58¶

在列出带有详细信息的组、列出带有详细信息的组快照、显示组详细信息和显示组快照详细信息 API 的响应体中添加 project_id 属性。

3.59 (Stein 和 Train 的最大版本)¶

支持卷传输分页。

3.60 (Ussuri 的最大版本)¶

用户可以使用 created_at 或 updated_at 字段对卷摘要列表和卷详细信息列表请求应用时间比较过滤器。时间必须以 ISO 8601 格式表示。

3.61¶

在 Active/Active HA 模式下，为管理员在卷详细信息响应体中添加 cluster_name 属性。

3.62 (Victoria 的最大版本)¶

支持为特定项目设置、获取和取消设置默认卷类型。设置此默认值会覆盖配置的 default_volume_type 值。

3.63¶

在 volume-show 和 volume-detail-list JSON 响应中包含卷类型 ID。在此微版本之前，Cinder 在卷详细信息中仅返回卷类型名称。

3.64 (Wallaby 的最大版本)¶

如果关联卷已加密，则在卷和备份详细信息中包含 encryption_key_id。

3.65¶

在卷和快照详细信息中包含一个 consumes_quota 字段，以指示资源是否正在消耗配额。此外，在卷和快照列表请求中接受一个 consumes_quota 过滤器，该过滤器采用布尔值。（默认列表行为是不使用此过滤器。）

3.66 (Xena 的最大版本)¶

可以创建正在使用的卷的快照，而无需“force”标志。虽然在卷快照请求中传递时，“force”标志现在被认为无效，但为了向后兼容，具有评估为 True 的值的“force”标志会被静默忽略。

3.67¶

API URL 无需在其中包含“project_id”参数。例如，API 路由：https://$(controller)s/volume/v3/$(project_id)s/volumes 等效于 https://$(controller)s/volume/v3/volumes。与 cinder 服务交互时，作为系统或域范围用户，不应在 API 路径中指定 project_id。

3.68 (Yoga 的最大版本)¶

支持使用特定镜像重新镜像卷。在请求体中指定 os-reimage 操作。

3.69¶

卷字段 shared_targets 现在是一个三态布尔值，含义如下

true：当主机 iSCSI 发起程序不支持手动扫描时，执行 os-brick 锁定。
false：从不执行锁定。
null：无论 iSCSI 发起程序如何，都强制锁定。

3.70 (Zed、2023.1 和 2023.2 的最大版本)¶

添加了传输加密卷及其快照的能力。此功能删除了先前对传输加密卷的限制。否则，API 请求和响应模式保持不变。

3.71 (2024.1 和 2024.2 的最大版本)¶

添加了 os-extend_volume_completion 卷操作，Nova 可以使用它来通知 Cinder 处理 volume-extended 外部服务器事件的成功和错误。