openstack/openstack-helm
Code Issues Proposed changes
f7c0e3aefa
openstack-helm/doc/source/specs/values-ordering.rst
Dae Seong Kim 72172aae5a 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
2018-10-05 02:59:37 +00:00

3.7 KiB
Raw Blame History

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.