From cd184ef1b6ffa9d4ae6481a4ea9c3f9587a2a8ac Mon Sep 17 00:00:00 2001
From: Ralf Haferkamp <rhafer@suse.com>
Date: Tue, 17 Sep 2019 12:59:11 +0200
Subject: [PATCH] nova: Add missing README.config

Change-Id: Iad93c23d1f7da4c4d75a4b793829114da2618ae4
---
 openstack/nova/nova.spec.j2                 |  3 +++
 openstack/nova/openstack-nova.README.config | 30 +++++++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 openstack/nova/openstack-nova.README.config

diff --git a/openstack/nova/nova.spec.j2 b/openstack/nova/nova.spec.j2
index 28ac0c7e1..0abce97a1 100644
--- a/openstack/nova/nova.spec.j2
+++ b/openstack/nova/nova.spec.j2
@@ -31,6 +31,7 @@ Source22:       openstack-nova-novncproxy.service
 Source23:       openstack-nova-serialproxy.service
 Source24:       openstack-nova-api-os-compute.service
 Source27:       openstack-nova.tmpfiles
+Source50:       openstack-nova.README.config
 BuildRequires:  fdupes
 BuildRequires:  openstack-macros
 BuildRequires:  polkit
@@ -464,6 +465,7 @@ install -D -m 644 %{SOURCE27} %{buildroot}/%_tmpfilesdir/%name.conf
 # Install config files
 install -d -m 755 %{buildroot}%{_sysconfdir}/nova
 install -d -m 755 %{buildroot}%{_sysconfdir}/nova/nova.conf.d
+install -p -D -m 640 %{SOURCE50} %{buildroot}%{_sysconfdir}/nova/README.config
 install -p -D -m 640 %{SOURCE1} %{buildroot}%{_sysconfdir}/nova/nova.conf.d/010-nova.conf
 install -p -D -m 640 etc/nova/api-paste.ini %{buildroot}%{_sysconfdir}/nova/api-paste.ini
 install -p -D -m 640 etc/nova/logging_sample.conf %{buildroot}%{_sysconfdir}/nova/logging.conf
@@ -661,6 +663,7 @@ rm nova/tests/unit/test_hacking.py
 %{_sysconfdir}/nova/release
 %_tmpfilesdir/%name.conf
 %dir %{_sysconfdir}/nova/nova.conf.d/
+%{_sysconfdir}/nova/README.config
 %config(noreplace) %{_sysconfdir}/logrotate.d/%{name}
 %config(noreplace) %{_sysconfdir}/sudoers.d/%{name}
 %config(noreplace) %attr(-, root, nova) %{_sysconfdir}/nova/api-paste.ini
diff --git a/openstack/nova/openstack-nova.README.config b/openstack/nova/openstack-nova.README.config
new file mode 100644
index 000000000..d4733d9a0
--- /dev/null
+++ b/openstack/nova/openstack-nova.README.config
@@ -0,0 +1,30 @@
+The main service configuration (/etc/$project/$project.conf) can still be used
+for configuration but the preferred way is to add config file snippets into
+/etc/$project/$project.conf.d/ instead.
+
+As part of the packaging, the package itself installs a config snippet at
+/etc/$project/$project.conf.d/010-$project.conf with basic configuration. This
+file should not be modified. In case there is a need to overwrite or add
+settings, a XXX-$project.conf (XXX being a 3 digit number) should be created
+instead.
+
+Config directory file snippet naming should follow these conventions:
+- snippets should start with "XXX-" where "X" is a number
+- snippets must end with ".conf"
+- config management systems (Crowbar, Salt, ...) should use numbers
+  between 100 and 499
+- users should use numbers starting from 500
+
+Configuring just a single $program (eg for Nova, $project is "nova" and
+$program is "nova-api", "nova-compute", "nova-scheduler", ...) can be done
+in a similar way. The config snippets should be placed in
+/etc/$project/$program.conf.d/ . The same snippets rules apply here, too.
+
+$program reads the configuration files in the following order:
+- /etc/$project/$project.conf
+- /etc/$project/$project.conf.d/*.conf (lexically sorted)
+- /etc/$project/$program.conf.d/*.conf (lexically sorted)
+
+The last configured key overwrites all previous ones. In particular, settings
+in /etc/$project/$project.conf are overwritten by config values from any file
+in /etc/$project/$project.conf.d/XXX-$project.conf .