diff --git a/specs/rocky/handle-config-changes.rst b/specs/rocky/handle-config-changes.rst new file mode 100644 index 0000000..f8b44eb --- /dev/null +++ b/specs/rocky/handle-config-changes.rst @@ -0,0 +1,155 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +=========================================== +Configuration change handling over releases +=========================================== + +Problem description: +==================== + +When users perform upgrade their OpenStack system to new release, normally +they are required to update configuration files for adapting changes from +old release to new release. Basically, at that time they must read release +notes or change logs or even track source code changes for doing this. +But unfortunately, there could be some misunderstanding, lack of information +in release notes that cause users confuse. There should be some helper in +oslo.config for automatically adopt new changes and help users manage their +configuration files easily. + +Scenario: + +Below is the proposed workflow that users can perform on old system to generate +new configuration for preparing upgrading to new release:: + + +--------------+ + Old configuration +--------> | + | | + | Gen config +-------> New configuration + Mapping-file +--------> | + | | + +--------------+ + + Running on new environment + + +Proposed change: +================ + +Base on the CONF object then we can get the information of new options about +whether ``deprecated_name`` and ``deprecated_group`` or not. If yes, then it +is possible to implement a function to update from old configuration to new +configuration, so we call this case is "Mapping 1:1 without changing value. +In fact, not only this case but also other cases including: + +* *Case 1*: Mapping 1:1 without changing value. +* *Case 2*: Mapping 1:1 with changing value. +* *Case 3*: Mapping N:1. It means one option can replace a group of options. +* *Case 4*: Mapping M*N:1: Meaning that one option can replace a super group of options. + +The ``transport_url`` option is a good example. + +In order to solve case 1, case 2 and case 3 then it is necessary to update +one option to CONF object. It is called "mapping_value". It will be a string +value that is to map from old value to new value with a template like this: ``old1_value:new1_value,old2_value:new2_value``. + + +Problems: +========= + +Problem 1: Mapping M*N options to 1 option: +------------------------------------------- + +Currently, ``transport_url`` is a big example for this case. With M is the +number of options in a driver for message queue, N is the number of +drivers (N>1). + +For example: + +If RabbitMQ is used as backend for message queue then ``transport_url`` can +replace four options such as ``rabbit_host``, ``rabbit_port``, +``rabbit_userid`` and ``rabbit_password`` (M=4) by using a template like this: +``rabbit://rabbit_userid:rabbit_password@rabbit_host:rabbit_port``. + +If Kafka is backend for message queue then ``transport_url`` can replace +two options including ``kafka_default_host`` and ``kafka_default_port`` +(M=2) by using a template like this: +``kafka://kafka_default_host:kafka_default_port``. + +So operators have to update the change **manually**. + + +Problem 2: Dynamic section +-------------------------- + +One important thing that there is a dynamic section. For example, Cinder +has a dynamic section named ``enabled_backends`` [1]_, if this option is +declared like ``enabled_backends = lvmdriver-1``, then there will be a section +declared in cinder.conf like below. + +.. code-block:: ini + + [lvmdriver-1] + image_volume_cache_enabled = True + volume_clear = zero + lvm_type = default + iscsi_helper = tgtadm + volume_group = stack-volumes-lvmdriver-1 + volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver + volume_backend_name = lvmdriver-1 + + +So how can we understand all values in dynamic section? This can be done via +dynamic groups or driver groups[2] but we don't have any projects using +them, so each project should migrate to use those things instead of their +special ways to read dynamic sections. + + +Work Items: +=========== + +1. Implement one attribute: mapping_value. + +2. Implement a new function to render new configuration files based on codebase +and old configuration files. + + +Documentation Impact: +===================== + +Need to have two documentations: + +1. Having a docs to guide projects to update source-code if they want to have +this feature. + +2. Having a docs for Operators about step by step to use this feature. + + +Implementation: +=============== + +Assignee(s) +----------- + +Primary assignee: + + Dai Dang Van + + Nam Nguyen Hoai + + Hieu Le + +References: +=========== + +.. [1] https://github.com/openstack/cinder/blob/66b3a52794f9c2aa6652b28c0a8e67792e2f993b/cinder/common/config.py#L160 + +.. [2] https://docs.openstack.org/oslo.config/latest/reference/cfg.html#dynamic-groups + +.. [3] https://github.com/namptit307/Jump-Over-Release/blob/spec/jor/templates/ocata/oslo_messaging.yaml + https://github.com/namptit307/Jump-Over-Release/blob/spec/jor/templates/ocata/cinder.yaml + +.. [4] https://github.com/namptit307/Jump-Over-Release/blob/master/jor/mapconf/gen_conf.py#L14-L157