Merge "Variable Substitution Initial Specification"

specs/2019.03/approved/multi-os-2004039-variable-substitution.rst

@@ -0,0 +1,176 @@
+..
+  This work is licensed under a Creative Commons Attribution 3.0 Unported
+  License. http://creativecommons.org/licenses/by/3.0/legalcode
+
+===============================================
+StarlingX: Variable Subsitution of System Paths
+===============================================
+
+Storyboard:
+https://storyboard.openstack.org/#!/story/2004039
+
+The Multi-OS effort requires that we can modify the locations that some
+files might be found during installation and later for configuration. While
+the Linux Standard Base (LSB) includes the Filesystem Hierarchy Standard
+(FHS) not all Linux distributions follow it exactly, therefore there can be
+differences.
+
+Problem description
+===================
+
+Many scripts and configuration files hardcode certain paths and filenames,
+depending on the Linux distribution these may not be accurate from one
+distribution to the next. By providing a mechanism for variable substitution
+during build, installation or update, this problem can be addressed.
+
+Use Cases
+=========
+
+This is for the Developer and system level engineer working on implementing
+changes to support OS independence in the StarlingX service (Flock) and
+system level configuration files contained within StarlingX stx repos.
+
+Proposed change
+===============
+
+Using the existing naming conventions, change the existing hardcode paths
+to the common naming convention and then do substitution via sed or other
+tool as appropriate. This renaming could occur in any source or configuration
+file, not limited to Makefiles, .ini, .config, or scripts.
+
+Examples:
+
+RPM Variable      Make Variable  Substitution Variable
+%{_sysconfdir}     SYSCONFDIR       @SYSCONFDIR@
+%{_buildroot}      DESTDIR          @DESTDIR@
+%{pythonroot}      PYTHONROOT       @PYTHONROOT@
+
+Posting to get preliminary feedback on the scope of this spec.
+
+Alternatives
+============
+
+None
+
+Data model impact
+=================
+
+None
+
+REST API impact
+===============
+
+None
+
+Security impact
+===============
+
+None
+
+Other end user impact
+=====================
+
+None
+
+Performance Impact
+==================
+
+None
+
+Other deployer impact
+=====================
+
+No additional configuration options are being added, but existing ones may
+change based on how the variables are substituted.
+
+Developer impact
+=================
+
+Developers will need to be aware of the variables and how they get substituted
+and added. This can be addressed in the Developer Guide Wiki.
+
+Upgrade impact
+===============
+
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+===========
+
+Primary assignee:
+  Shuicheng Lin (shuicheng)
+
+Other contributors:
+  Mingyuan Qi
+  Zhipeng Liu
+  Saul Wold (sgw-starlingx)
+
+
+Repos Impacted
+==============
+
+stx-clients
+stx-config
+stx-fault
+stx-gui
+stx-ha
+stx-integ
+stx-metal
+stx-nfv
+stx-update
+stx-upstream
+
+
+Work Items
+===========
+
+Initial work:
+ * https://storyboard.openstack.org/#!/story/2004039
+
+   #. Task: 27043 stx-nfv: contains hardcoded path to /etc and
+      /usr/lib64/python2.7
+
+Ongoing Discovery
+ * Create additional tasks in the 2004039 Story as we discover additional
+   hardcoded paths that need substitution.
+ * Ensure that the StarlingX services are using the correct LSB/FHS directory
+   structure as implemented by the upstream distribution (this can still vary
+   slightly).
+
+Dependencies
+============
+
+None
+
+Testing
+=======
+
+Verify configuration is correct before and after the change and test that the
+resulting system boots correctly and has the correct configuration.
+
+Documentation Impact
+====================
+
+Developer Guide Wiki will need to be updated to list the canonical variables
+and their default paths.
+
+References
+==========
+
+Linux Standard Base: https://wiki.linuxfoundation.org/lsb/start
+Hierarchy Filesystem Standard: https://wiki.linuxfoundation.org/lsb/fhs
+
+History
+=======
+
+.. list-table:: Revisions
+   :header-rows: 1
+
+   * - Release Name
+     - Description
+   * - 2019.03
+     - Introduced