添加策略文档¶

https://blueprints.launchpad.net/nova/+spec/policy-docs

目前运维人员需要阅读代码才能理解策略规则的实际含义。这非常糟糕，本规范建议通过为每个策略规则添加描述来解决这个问题。

问题描述¶

运维人员需要阅读代码来理解策略规则控制的内容。

用例¶

运维人员希望审计默认策略规则，并查看它们是否适合其部署环境。
运维人员希望授予用户访问他们当前访问时收到 403 错误 API 的权限。
运维人员希望限制用户当前拥有的 API 访问权限。

提议的变更¶

我们应该填写系统中所有策略规则的描述字段。为了帮助确保运维人员无需阅读代码就能完全理解每个规则的影响，我们应该确保

所有文档应使用 API 文档中描述的实体名称：https://developer.openstack.org/api-ref/compute/
我们应该以与 api-ref 中相同格式声明策略规则影响的 API 的 URL，例如：DELETE /servers/{server_id}
我们应该确保文档在生成的策略文件中渲染良好，包括确保所有规则默认被注释掉：https://docs.openstack.org/developer/nova/sample_policy.html 请注意，我们已经以 yaml 格式渲染示例策略文件。

例如，我们可能会在示例策略中看到如下内容

# Show details of a specific server
#
# GET /servers/{server_id}
#
# "os_compute_api:servers:show": "rule:admin_or_owner"

# Show real hostname of nova-compute managing the server
#
# Users normally only see an obfuscated hostname that is unique
# to each project. If you pass this rule, we show the real hostname
# so admins can find which host the server is on.
#
# GET /servers/details
# GET /servers/{server_id}
#
# "os_compute_api:servers:show:host_status": "rule:admin_api"

# Create a server
#
# POST /servers/{server_id}
#
# "os_compute_api:servers:create": "rule:admin_or_owner"

# Create an image from a server
#
# POST /servers/{server_id}/action (createImage)
#
# "os_compute_api:servers:create_image": "rule:admin_or_owner"

# List all host aggregates
#
# GET /os-aggregates
#
# "os_compute_api:os-aggregates:index": "rule:admin_api"

# Delete a host aggregate
#
# DELETE /os-aggregates/{aggregate_id}
#
# "os_compute_api:os-aggregates:delete": "rule:admin_api"

作为一个例子，我们将从以下策略定义更新

policy.RuleDefault(SERVERS % 'show', RULE_AOO),

更新为如下所示

policy.DocumentedRuleDefault(SERVERS % "show", RULE_AOO,
    "Show details of a specific server",
    operations=[{"method": "GET", "path": "/servers/{server_id}"}])

取决于 DocumentedRuleDefault 的可用时间，我们可能会使用 nova 内部的包装器来模拟它，以便在发布之前取得进展。oslo.policy > 1.20 现在支持多行描述。

备选方案¶

我们可以尝试将文档与代码分开，但事实证明这很难维护并与代码保持同步。

数据模型影响¶

无

REST API 影响¶

无

安全影响¶

更好地理解每个规则的含义只能帮助运维人员和开发人员正确配置策略。

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

无

其他部署者影响¶

无

开发人员影响¶

我们必须在添加策略规则时添加描述。这些是创建 DocumentedRuleDefault 时的所有必需参数。

实现¶

负责人¶

主要负责人: John Garbutt (johnthetubaguy)
其他贡献者: OSIC

工作项¶

为每个策略规则添加文档
确保示例策略文件渲染正确
添加 hacking 检查以优先使用 DocumentedRuleDefault 而不是 RuleDefault

依赖项¶

等待 oslo.polcy 的更改才能完成此操作。我们主要等待此更改：https://review.openstack.org/#/c/439070/

测试¶

文档任务生成更新的策略示例文件。这清楚地显示了哪些规则遗漏以及更新后的规则外观。

文档影响¶

我们获得了一个改进的示例策略文件。

我们应该确保将其纳入 Nova 的配置指南中。

参考资料¶

无

历史¶

修订版¶
发布名称	描述
Pike	引入

添加策略文档