Specification: Value File Ordering

This specification proposes a value file ordering guideline
to enforce uniformity across all the charts in openstack-helm
project.

Story: 2002206
Task: 21742

Change-Id: I55691f4fb1c1e6aa5b430f5c287fd3f94e12f071
This commit is contained in:
Dae Seong Kim 2018-03-13 20:47:38 +09:00 committed by Tin Lam
parent f97e644aa6
commit 72172aae5a
2 changed files with 118 additions and 0 deletions

View File

@ -15,3 +15,4 @@ Contents:
support-linux-bridge-on-neutron.rst
fluentbit-fluentd-architecture.rst
osh-1.0-requirements.rst
values-ordering.rst

View File

@ -0,0 +1,117 @@
====================
Values File Ordering
====================
Problem Description
===================
Each chart's values.yaml file contains various settings such as docker
image definition, chart structure setting, form of the resources being
distributed, and process configuration. Currently, the structure of the yaml
file is complicated, and finding keys between charts proves difficult due to the
lack of uniform values organization across charts.
This specification proposes introducing a uniform values.yaml structure across
all charts in openstack-helm, openstack-helm-infra, and openstack-helm-addons,
with the goal of reducing the complexities of working across multiple charts and
reducing the effort for creating new charts.
Proposed Change
===============
This specification proposes defining entries in the values.yaml file into two
categories: top-level keys, and their children (sub-level) keys.
* The top-level keys are based on the organizational keys common to all charts
in the openstack-helm repositories. The top-level keys are strictly ordered
according to function, which creates a common organization pattern between all
charts.
* All keys under top-level keys are listed in alphabetical order, with the
exception of the conf key. As some configuration files require a strict
ordering of their content, excluding this key from any alphabetical
organization is required.
This specification also proposes to restrict the addition of any new top-level
keys in charts across all OpenStack-Helm repositories, in order to maintain the
common structure the ordering creates. The addition of a new top-level key
shall be agreed upon by the OpenStack-Helm team on a case-by-case basis. The
addition of any new top-level keys should be documented, and this specification
shall be amended to account for any added keys.
Top-level keys are placed in this order:
* images
* sub-keys (alphabetical order)
* labels
* sub-keys (alphabetical order)
* dependencies
* sub-keys (alphabetical order)
* pod
* sub-keys (alphabetical order)
* secrets
* sub-keys (alphabetical order)
* endpoints
* sub-keys (alphabetical order)
* bootstrap
* sub-keys (alphabetical order)
* network
* sub-keys (alphabetical order)
* manifests
* sub-keys (alphabetical order)
* monitoring
* sub-keys (alphabetical order)
* conf
* sub-keys (up-to-chart-developer)
Security Impact
---------------
No security impact.
Performance Impact
------------------
This feature will not affect the performance of OpenStack-Helm.
Alternatives
------------
The alternative is to provide no organization layout for charts across all
openstack-helm repositories.
Implementation
==============
Assignee(s)
-----------
Primary assignees:
powerds0111 (DaeSeong Kim <daeseong.kim@sk.com>)
srwilkers (Steve Wilkerson <sw5822@att.com>)
Work Items
----------
The following work items need to be completed for this specification to be
implemented.
* Update of developer documentation
* Add a template highlighting the updated values ordering for use in chart
development
* Change ordering of keys across all charts in openstack-helm,
openstack-helm-infra, and openstack-helm-addons
Testing
=======
To successfully enforce the ordering defined here, our gates need a method for
validating the ordering and the schema of all values.yaml files. Without such
a mechanism, the overhead associated with properly reviewing and validating any
changes to the structure will be substantial. A tool, such as yamllint, would
provide this functionality and remove the need to write a custom validation tool
Documentation Impact
====================
The developer documentation in OpenStack-Helm should be updated to guide key
ordering on value files.