示例规范 - 您的蓝图标题

包含您的 Launchpad 蓝图的 URL

https://blueprints.launchpad.net/manila/+spec/example

介绍段落 – 为什么要进行这项工作？一段操作员可以理解的散文。

关于使用此模板的一些说明

  • 您的规范应使用 ReSTructured 文本，就像此模板一样。

  • 请将文本换行到 79 列。

  • Git 仓库中的文件名应与 Launchpad URL 匹配，例如，URL 为：https://blueprints.launchpad.net/manila/+spec/awesome-thing 应该命名为 awesome-thing.rst

  • 请勿删除此模板中的任何部分。如果您对整个部分没有什么要说的，只需写上：无

  • 有关语法帮助，请参阅 https://sphinx-doc.cn/rest.html

  • 要测试您的格式，请使用 tox 构建文档，或参阅：https://www.siafoo.net/reST.xml

  • 如果您的规范建议对 Manila REST API 进行任何更改，例如更改可以返回或接受的参数，甚至客户端调用 API 时发生情况的语义，那么您应该将 APIImpact 标志添加到提交消息中。可以使用以下查询找到带有 APIImpact 标志的规范：https://review.openstack.org/#/q/status:open+project:openstack/manila-specs+message:apiimpact,n,z

  • 如果您想为您的规范提供图表，则首选文本表示形式。acsiiflow [1] 和 blockdiag [2] 是可以协助完成此操作的好工具。首选文本表示形式，因为用于审查规范的工具完全基于纯文本。纯文本将允许审查人员无需查看无法在 gerrit 中查看的附加文件即可进行审查。它还将允许对图表本身进行内联反馈。

  • 图表示例

asciiflow

+----------+     +-----------+        +----------+
| A        |     |  B        |        |  C       |
|          +-----+           +--------+          |
+----------+     +-----------+        +----------+

blockdiag

actdiag

nwdiag

seqdiag

问题描述

问题的详细描述。这个蓝图要解决什么问题？

用例

此规范解决了哪些用例？此更改对参与者有什么影响？请确保您清楚地了解每个用例中的参与者：开发人员、最终用户、部署者等。

提议的变更

在这里详细介绍您建议进行的更改。您如何提出解决此问题的方法？

如果这是更大工作的一部分，请明确说明这部分在哪里结束。换句话说，这项工作的范围是什么？

备选方案

解决所解决的问题有哪些替代方法？为什么选择所提出的方法而不是其他替代方法？为什么我们不使用那些方法？这不需要过多的详细描述，而是要展示已经对所提出的解决方案进行了思考，并提供一些关于为什么它是适当选择的信息。

数据模型影响

需要修改数据模型的变化通常会对系统产生更广泛的影响。社区通常对数据模型应该如何演进持有强烈的意见，从功能和性能的角度来看都是如此。因此，尽早捕获并达成对任何拟议的数据模型更改的共识非常重要。

本节需要解决的问题包括

  • 这将需要哪些新的数据对象和/或数据库模式更改？

  • 哪些数据库迁移将伴随此更改。

  • 如何生成初始的新数据对象集，例如，如果您需要考虑现有实例，或修改其他现有数据，请描述如何操作。

REST API 影响

每个添加或更改的 API 方法都应具有以下内容

  • 方法的规范

    • 适合在用户文档中使用的对方法描述

    • 方法类型 (POST/PUT/GET/DELETE)

    • 正常的 http 响应代码

    • 预期的错误 http 响应代码

      • 应包含每个可能错误代码的描述，描述可能导致该错误发生的语义错误，例如提供给该方法的参数不一致，或者当实例不在请求成功状态时。JSON schema 定义涵盖的语法问题导致的错误不需要包含。

    • 资源的 URL

    • 可以通过 url 传递的参数

    • 如果允许，则为 body 数据定义 JSON schema

    • 如果存在，则为响应数据定义 JSON schema

  • 示例用例，包括调用者提供的数据和响应的典型 API 示例

  • 讨论任何策略更改，并讨论部署者在定义其策略时需要考虑的事情。

可以在 Manila 树中找到示例 JSON schema 定义 http://git.openstack.org/cgit/openstack/manila/tree/manila/api/schemas/v1.1

请注意，模式应尽可能定义为限制性。应将必需的参数标记为必需，并且在极少数情况下才应允许未在模式中定义的附加参数（例如 additionaProperties 应为 False）。

鼓励重用现有的预定义参数类型，例如密码和用户定义名称的正则表达式。

驱动程序影响

描述对驱动程序调用语法的任何更改或行为更改。这包括但不限于对 ShareDriver 类进行的更改，以及对以不同的方式调用驱动程序或对返回值有不同期望的 ShareManager 的更改。

  • 对已删除/更改接口的逐步弃用做了哪些安排？

  • 是否需要为驱动程序作者提供新的文档？

  • 是否需要更新驱动程序的测试？

安全影响

描述对系统造成的任何潜在安全影响。需要考虑的一些项目包括

  • 此更改是否涉及敏感数据，例如令牌、密钥或用户数据？

  • 此更改是否以可能影响安全性的方式更改了 API，例如访问敏感信息的新方式或登录的新方式？

  • 此更改是否涉及密码学或哈希？

  • 此更改是否需要使用 sudo 或任何特权？

  • 此更改是否涉及使用或解析用户提供的数据？这可能是直接在 API 级别，或间接例如更改缓存层。

  • 此更改是否会启用资源耗尽攻击，例如允许单个 API 交互消耗大量的服务器资源？这方面的一些例子包括为每个连接启动子进程，或 XML 中的实体扩展攻击。

有关更详细的指导，请参阅 OpenStack 安全指南作为参考 (https://wiki.openstack.org/wiki/Security/Guidelines)。这些指南正在不断完善中，旨在帮助您识别安全最佳实践。有关更多信息，请随时通过 openstack-security@lists.openstack.org 联系 OpenStack 安全组。

通知影响

请指定任何通知的更改。无论是额外的通知、对现有通知的更改，还是删除通知。

其他最终用户影响

除了 API 之外，用户还有其他方式与此功能交互吗？

  • 此更改是否对 python-manilaclient 有影响？那里的用户界面是什么样的？

性能影响

描述对系统造成的任何潜在性能影响，例如新代码将被调用多少次，以及现有代码的调用模式是否有重大变化。

需要考虑的一些示例包括

  • 周期性任务可能看起来是一个小的补充，但在考虑大规模部署时，建议的调用实际上可能在数百个节点上执行。

  • 调度器过滤器在为每个正在创建的卷为每个主机调用一次，因此它们引入的任何延迟与系统的大小成线性关系。

  • 对实用函数或常用装饰器的微小更改可能对性能产生巨大影响。

  • 导致数据库查询的调用会对性能产生深刻的影响，尤其是在代码的关键部分。

  • 此更改是否包含任何锁定，如果是这样，对持有锁有什么考虑？

其他部署者影响

讨论将影响您部署和配置 OpenStack 的事情，这些事情尚未提及，例如

  • 正在添加哪些配置选项？它们是否应该比建议的更通用（例如，其他卷驱动程序可能想要实现的标志）？默认值是否适用于实际部署？

  • 此更改是否在合并后立即生效，还是需要显式启用？

  • 如果此更改是新的二进制文件，将如何部署它？

  • 请说明那些进行持续部署或从以前版本升级的人需要注意的任何事情。还描述了弃用配置值或功能的计划。例如，如果我们更改存储目标（LVM）的目录名称，我们如何处理更改落地之前创建的任何已使用的目录？我们是否移动它们？我们是否在代码中有一个特殊情况？我们是否假设操作员将重新创建云中的所有卷？

开发人员影响

讨论将影响在 OpenStack 上工作的其他开发人员的事情，例如

  • 开发环境中的新依赖项

  • 对典型开发工作流程的更改

  • 需要更新 CI 的更改

  • 对共享代码的更改，需要更新此功能之外的其他代码区域。

实现

负责人

谁在编写代码？或者这是一个蓝图，您正在将其抛出以查看谁会接受它？

如果有多个人正在进行实现，请指定主要作者和联系人。

主要负责人

<launchpad-id 或 None>

其他贡献者

<launchpad-id 或 None>

工作项

工作项目或任务 – 将该功能分解为实施它需要完成的事情。这些部分可能最终由不同的人完成，但我们主要试图了解实施的时间表。

依赖项

  • 包含对 Manila 或其他项目中规范和/或蓝图的具体引用，该规范和/或蓝图依赖于或与该规范相关。

  • 如果这需要另一个项目的功能，而 Manila 当前未使用该功能（例如，当我们以前只需要 v1 时使用的 glance v2 API），请记录这一事实。

  • 此功能是否需要任何新的库依赖项或未包含在 OpenStack 中的代码？或者它是否依赖于库的特定版本？

测试

请讨论如何测试更改。我们特别想知道将添加哪些 tempest 测试。假设将添加单元测试覆盖率，因此无需显式提及，但讨论为什么您认为单元测试就足够了，我们不需要添加更多 tempest 测试将需要包括在内。

鉴于当前的限制（可用的特定硬件/软件配置），这在 gate 中是否无法测试？如果是这样，是否有缓解计划（第三方测试、gate 增强等）。

文档影响

此更改对文档团队有什么影响？有些更改可能需要向文档团队捐赠资源以更新文档。不要重复上面讨论的细节，但请在此处引用它们。

参考资料

请添加任何有用的参考资料。您不需要有任何参考资料。此外，当您的参考资料不可用时，此规范仍然应该有意义。您可以包括的内容示例是

  • 邮件列表或 IRC 讨论的链接

  • 峰会会议记录的链接

  • 如果合适，相关研究的链接

  • 相关规范（例如，链接到任何厂商文档）

  • 您认为值得参考的任何其他内容

图表工具参考