机器可读示例配置¶
https://blueprints.launchpad.net/oslo?searchtext=machine-readable-sample-config
目前 oslo.config 生成的示例配置是为人工阅读设计的。然而，许多部署工具将受益于一个机器可读的示例配置。
问题描述¶
所有部署工具都需要解决一个类似的问题：如何在部署时为每个服务生成配置文件。目前有各种方法，包括手动更新的模板、半自动生成的模板，以及使用 ini 文件工具更新每个项目的现有示例配置。
这些方法都存在各种缺点。模板方法通常需要一些繁琐的人工编辑来模板化部署工具需要设置的所有值。Ini 文件工具不了解示例配置格式，因此只能在正确的节中设置值，这通常将它们与选项的示例配置文档分隔开。这些方法中的任何一种都不能让部署工具轻松地为配置选项提供用户友好的界面。
在这种情况下，当前 ini 格式的示例配置的问题在于它不易于机器读取。内容全部以注释块的形式编写，部署工具需要解析这些注释块。由于该注释格式不能保证保持不变，因此使用这种方法的每个部署工具都需要进行持续维护。
提议的变更¶
该提案是编写机器可读的示例配置文件，输出与现有 ini 文件相同的数据，但采用 YAML 或 JSON 格式，以便部署工具更容易使用。
建议输出示例
generator_options:
args: --config-file=etc/nova/nova-config-generator.conf
output_file: etc/nova/nova.conf.yaml
wrap_width: 80
namespace:
- nova.conf
- oslo.log
...
summarize: False
# minimal intentionally omitted as I don't think it makes sense in
# this context
[more generator details can be added as desired]
options:
DEFAULT:
image_service:
# The list of parameters is for example only. The actual output
# can include anything deployment tools would find useful.
default: nova.image.glance.GlanceImageService
documentation: Service used to search for and retrieve images.
type: string
required: True
deprecated: False
deprecated_reason: blabla
deprecated_for_removal: False
deprecated_since: XXX
deprecated_name: old_parameter
[all other parameters passed to the opt constructor]
new_opt:
deprecated_name: old_opt
...
...
conductor:
workers: (...)
...
...
deprecated_options:
DEFAULT:
old_opt:
default: foo
documentation: Example deprecated opt
type: string
replacement_name: new_opt
replacement_group: DEFAULT
...
该结构将包含编写格式良好的配置文件所需的所有详细信息，并且由于我们将从实际的 opt 数据开始，而不是一个充满注释的 ini 文件，因此更容易在适当的位置注入值。由于它将从每个项目已经提供的示例配置数据生成，因此应该需要很少或不需要手动维护。
与现有生成的示例配置相比，此格式的另一个建议更改是将弃用的 opt 作为一等公民来编写，而不是仅仅作为新 opt 上的 deprecated_name/group。这样，该结构仍然与之前的配置保持一致，应该更容易从一个版本过渡到另一个版本。当然，这些 opt 将被标记为已弃用，以便清楚地表明不应再使用它们。上面的示例中包含一个示例。
关于实现：为了轻松支持 YAML 和 JSON 格式，我认为生成器应该使用嵌套字典，这些字典可以使用适当的模块简单地输出。由于 YAML 和 JSON 格式化程序已经存在，我们不需要重新发明这些轮子。
备选方案¶
以上问题部分讨论了实现此目的的一些现有方法及其缺点。这些方法有效，但所有部署项目都存在大量重复工作，因此不希望继续这样做。
每个项目都可以自动化其配置文件生成，类似于参考部分中的 OpenStack Helm 工具，但同样存在 oslo.config 可以解决的重复问题。
Impact on Existing APIs¶
我们需要向 oslo-config-generator 添加一个 –format 参数，以便用户可以使用新的格式生成示例配置。为了向后兼容，这将默认为现有的 ini 样式格式。
安全影响¶
应该没有。对于大多数情况，这只是已经生成的数据的新格式。一个可能的例外是捕获配置生成器的参数，但我认为其中没有任何内容应该是敏感的。
性能影响¶
生成新的文件格式将花费更多时间，但默认情况下只会创建现有格式，因此不应有任何更改。
Configuration Impact¶
除了 –format CLI 参数之外，没有提出新的配置选项。
开发人员影响¶
没有。开发人员已经将配置选项暴露给配置生成器，这只是为该配置添加了另一个用途。
Testing Impact¶
此功能将以与现有配置生成器相同的方式进行单元测试。我们需要向单元测试中添加 YAML/JSON 场景。
实现¶
负责人¶
- 主要负责人
bnemec
- 其他贡献者
emacchi
里程碑¶
完成目标里程碑：我们希望在 Pike 中完成这项工作，可能在 Queens 周期中供部署工具使用。
工作项¶
实现 YAML 输出
实现 JSON 输出
为新格式添加测试场景
孵化¶
未孵化。
采用¶
不适用
库¶
不适用
预计 API 稳定¶
不适用
文档影响¶
这项工作面向部署工具，因此应该不需要进行大量的用户界面文档更改。我们希望在 oslo.config 文档中引用这些新示例格式的存在。
输出文件的格式和结构需要记录下来，以便部署工具使用。
依赖项¶
无
参考资料¶
跨部署工具 PTG 会议，特别是问题 #1 部分。
https://github.com/alanmeadows/gen-oslo-openstack-helm
注意
本作品采用知识共享署名 3.0 非移植许可协议授权。 http://creativecommons.org/licenses/by/3.0/legalcode
