diff --git a/doc/source/index.rst b/doc/source/index.rst index cae9200..077895f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,6 +36,14 @@ Liberty approved specs: specs/liberty/* +Mitaka approved specs: + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/mitaka/* + ================== Indices and tables ================== diff --git a/specs/mitaka/config-deprecation-for-inifile-provider.rst b/specs/mitaka/config-deprecation-for-inifile-provider.rst new file mode 100644 index 0000000..9d2cddf --- /dev/null +++ b/specs/mitaka/config-deprecation-for-inifile-provider.rst @@ -0,0 +1,172 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +========================================== +Configuration File Deprecation Support +========================================== + +`Launchpad blueprint `_ + +Allow the inifile (config file) providers to handle deprecated options. This +should include cleaning up old deprecated names from config files and also +allow using the deprecated name instead of the new name. + +Problem description +=================== + +When moving to new releases of OpenStack, config file options are frequently +deprecated because they're no longer needed, or they've been renamed. + +After an upgrade this means that operators will frequently have the old and new +config option in place, but the old option is no longer used or maintained. + +Additionally, when upgrading it can be useful to update the Puppet modules +before actually upgrading the service. A frequent problem when doing this is +that the newer module only supports the new names for options instead of the +older deprecated names. + +Proposed change +=============== + +Add additional parameters to the openstacklib inifile provider help manage +cleanup removed and renamed configuration options. All inifile providers in +other OpenStack Puppet modules that derive from this provider would inherit the +new behavior. The syntax would allow specifying the old name for options which +could be used to purge the old names or to use them in preference to the new +names. For example:: + + cinder_config { 'oslo_logging/new_option': + deprecated_name => 'DEFAULT/old_option_name', + value => $value, + } + +In this case, it would populate the ``oslo_logging/new_option`` key in the +Cinder config file with the contents of ``$value`` as normally expected. +However, it would also purge the old name ``DEFAULT/old_option_name`` as given +by ``deprecated_name``. + +The following new parameters would be supported: + +``deprecated_name`` + This is a string or array of old names that have been deprecated. Array + should be supported because there are sometimes multiple names that have been + deprecated in a single release. Defaults to an empty array. + +``purge_deprecated`` + If true, and if ``use_deprecated`` is false, then any ``deprecated_name`` + values provided will be treated as if they had been specified separately with + an ensure value of ``absent``. Defaults to true. + +``use_deprecated`` + If true, then the inifile provider will act as if additional resources of the + same type were specified for each ``deprecated_name`` with the same + ``value`` and ``ensure`` parameters. Defaults to false. + +It's expected that both ``use_deprecated`` and ``purge_deprecated`` would be +set globally for each config provider as needed, either using resource defaults +or resource collectors. + +Alternatives +------------ + +Currently the old deprecated options left behind cause no harm. We could +ignore this issue. This has the downside that it is not clear which value is +currently used. + +The inifile provider could be set to purge unmanaged options. Currently we +depend on distributions to provide a base configuration file. In the past +there have been issues with the OpenStack Puppet modules not managing all +required options and depending on values provided in the base configuration +files. This approach would require testing all of the existing modules to +ensure they manage all needed options and also changing acceptance tests to use +the purge functionality to prevent regressions. + +Data model impact +----------------- + +None + +Module API impact +----------------- + +Everything has been already mentioned in Proposed change. + +End user impact +--------------------- + +None + +Performance Impact +------------------ + +Potential implementations might create additional resources to ensure the +deprecated config value state. This could increase the number of resources +being managed and the Puppet catalog size. + +A small amount of additional overhead may be incurred to find and remove the +deprecated names. + + +Deployer impact +--------------------- + +Existing configuration files with deprecated options would be removed as +described. When this occurs, services will be restarted. Impact of this is +expected to be minimal since most of these changes would occur between major +releases of the modules. In that case, the deployer is expected to be +upgrading services and restarting them already. + +It is expected that deployers may set ``use_deprecated`` to true in +preparation to for upgrades, allowing upgrading the Puppet modules in some +cases before upgrading the services they manage. + +Deployers that wish to disable the new behavior could set the +``purge_deprecated`` parameter to false. + + +Developer impact +---------------- + +Developers would need to populate the ``deprecated_names`` parameter when +renaming configuration options. + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + clayton-oneill (IRC nick clayton) + +Work Items +---------- + +* Identify existing option with deprecation as test candidate +* Create a unit rspec in openstacklib and child module +* Create a functional test in openstacklib and child module +* Add implementation to openstacklib inifile provider + +Dependencies +============ + +None + +Testing +======= + +Unit and functional should be added to ensure base functionality and prevent +regressions. + +Documentation Impact +==================== + +Currently documentation of inifile providers is spotty. This may be an +opportunity to move that documentation into the ``openstacklib`` module. + +References +========== +None