迁移到 Keystone v3¶

https://blueprints.launchpad.net/neutron/+spec/keystone-v3

此蓝图旨在捕获 Neutron 仓库（neutron、neutron-lib 和 python-neutronclient）为了与 Keystone v3 API 完全集成的所需更改。

本文档中描述的所有步骤也适用于仓库 neutron-fwaas、neutron-lbaas、neutron-vpnaas 和 neutron-dynamic-routing。但是，只有 neutron、neutron-lib 和 python-neutronclient 中的更改才需要考虑此蓝图已完成。

问题描述¶

Keystone v3 API https://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html#what-s-new-in-version-3-0 [1] 于 2013 年 2 月 20 日发布。在 Icehouse 版本中，Keystone v2 API 被弃用 https://blueprints.launchpad.net/keystone/+spec/deprecate-v2-api [2]。由于许多 OpenStack 项目尚未支持 v3 API，因此不得不撤销 [3] 弃用。

在 Mitaka 版本中，Keystone 再次弃用 v2 API [4]。项目可以使用 v2 API 未来四个版本，但之后将不再支持。为了与其他 OpenStack 项目保持一致，并能够继续使用身份服务，我们必须更新 Neutron 以专门使用 Keystone v3，并在不再支持 v2 时使用。

使用 Keystone v3 API，“租户”的概念已被弃用，取而代之的是“项目”。特别是，属性 tenant_id 被替换为 project_id。Neutron 最初必须支持 project_id 作为 tenant_id 的别名，然后再完全替换 tenant_id。只要 Neutron CLI 得到支持，弃用就会持续。

在对 Neutron 的请求中，Neutron 服务器已经将 project_id 视为 tenant_id 的别名。在内部，Neutron 最终应将 tenant_id 替换为属性和数据库字段中的 project_id。

在从 Neutron 到其他 OpenStack 服务的请求中，Neutron 组件应使用 keystoneauth，它抽象了 v2/v3 差异。

提议的变更¶

将 Neutron 代码中所有现有的 Keystone v2 用法更改为 Keystone v3。最初将支持 API 的两个版本。迁移将分几个步骤进行。

更新 Neutron 服务器以接受请求中的 Keystone v3 上下文。[已完成]
更新 python-neutronclient 中的 API 绑定，以正确处理 project_id 和 tenant_id。
更新 Neutron 服务器以仅使用 keystoneauth 向其他 OpenStack 服务发送请求。
更新有关 tenant_id 属性弃用的文档
1. OpenStack Networking API 参考，
2. Neutron 和 neutronclient 开发人员参考。
为 DB 中的所有 tenant_id 列创建 project_id 别名。
更新代码库，将所有出现的 tenant 替换为 project，在适当的情况下。需要特别注意
1. 在重命名可调用函数的参数时，一些调用者可能会使用 kwargs 符号（tenant_id=…）而不是位置传递参数。
2. 在更改被外部项目使用的代码时，更改不得破坏外部项目。应设置弃用警告。

Neutron API¶

Neutron API 接受 project_id 属性，并将其视为 tenant_id 属性的别名。这已经实现 [5]。

此外，tenant_id 用作 Neutron API 中的过滤器参数。要求此用例将继续有效。

Neutron API 响应将扩展为包含 tenant_id 和 project_id。目前我们无法淘汰 tenant_id，因为这需要 API 版本更改。当采用微版本 [7] 用于 Neutron API 时，可以开始删除已弃用的属性的任务。同时，我们将通过另一个默认启用的 API 扩展公开 project_id。

Neutron 客户端¶

对于 CLI 命令，Neutron 客户端正在被弃用，转而支持 OpenStack Client [8]。因此，python-neutronclient 的 CLI 部分将不会更新。在 OpenStack Client 中，CLI 命令已经采用了使用 project_ 而不支持 tenant_ 的策略。

python-neutronclient 中唯一将被修改的部分是 Python API 绑定。所有接受 tenant_id 和 tenant_name 的绑定都需要扩展为也接受 project_id 和 project_name。tenant_ 参数将被标记为已弃用，并在未来删除。

OpenStack 文档¶

Neutron 客户端 CLI 正在被弃用，转而支持 OpenStack Client [8]，因此有关其行为的唯一文档更新将包含有关弃用的信息。

neutronclient Python API 文档将更新以显示绑定相应的更改。

Neutron 开发人员参考¶

术语 tenant 在整个文档中都有使用。所有地方都需要更新，并提供有关 tenant_id 弃用以支持 project_id 的额外信息。

将为所有子项目/关联项目提供其他指南，关于需要进行修改以与 Neutron API 更改保持一致。

数据库¶

将列从 tenant_id 重命名为 project_id，以及从 tenant_name 重命名为 project_id 将需要停机时间，并将通过合同迁移来完成。

为了允许以较小的块进行更改，并为了向后兼容，我们将暂时使用 SQLAlchemy 同义词功能 [6] 使 tenant_id 成为 project_id 列的同义词。

一段时间内，数据库操作将分别看到 tenant_id 和 project_id 属性出现在属性列表中等，并且需要注意如何在它们之间进行过滤和传递。

一旦所有现有列都已重命名为 project_id，添加到任何 Neutron 代码的所有新列都应仅使用 project_id。将添加一个黑客规则以防止在源代码中重新引入 tenant_id。

内部更改¶

服务器代码更改将以可审查的块提交，不会中断外部 API 或外部项目依赖项。客户端代码更改是累加的，直到弃用的关键字被删除。

测试¶

API 测试¶

编写测试以检查 tenant 和 project 参数的响应，以确保引入的更改一致。

功能测试¶

测试 project_id 是否返回与 tenant_id 相同的响应。
测试当 project_id 更新时，tenant_id 是否更新。

迁移到 Keystone v3