Merge pull request #242 from sap-contributions/hip-export-values-revi…

…ewed

hip introducing  `export-values` for better composability

hips/hip-0016.md

@@ -0,0 +1,119 @@
+---
+hip: "0016"
+title: "Add export-values directive (similar to import-values)"
+authors: [ "Jan von Loewenstein <[email protected]>", "Johannes Dillmann <[email protected]>", "Pavel Busko <[email protected]>", "Philipp Stehle <[email protected]>", "Ralf Pannemans <[email protected]>", "Sumit Kulhadia <[email protected]>" ]
+created: "2022-02-01"
+type: "feature"
+status: "draft"
+---
+
+## Abstract
+
+Composing Helm charts using dependencies is currently limited because it is not possible to create a chart with a defined set of values and distribute them to subcharts.
+
+With the `import-values` directive, there is a mechanism in Helm to use the default values of a subchart as a value in the parent chart and define the name under which the subchart value is available in the parent chart.
+This HIP proposes an `export-values` directive which is similar to the [`import-values`][import-values] directive, and allows exporting values from the parent chart to the subchart and defining the name under which it should be available.
+With that the values of the parent chart and the values of the subcharts can be defined independently. Subcharts can use their local values exclusively and don't have to be aware of the usage as a subchart. Parent charts on the other hand, can provide a consistent configuration api to their users and orchestrate the exchange of values between the subcharts using `export-values`, `import-values` or a combination thereof.
+
+This change was discussed in [helm/#3242]. There were several attempts to implement this: [helm/#7477], [helm/#10059].
+
+## Specification
+
+With the proposed `export-values` directive, users are able to specify in the **parent** chart (snippet below) which and where values should be exported to the **subchart**.
+
+```yaml
+# Chart.yaml:
+dependencies:
+  - name: client
+    version: 1.0.0
+    export-values:
+    - parent: "port"
+      child: "serverPort"
+  - name: server
+    version: 1.0.0
+    export-values:
+    - parent: "port"
+      child: "exposePort"
+    - "server-config"
+```
+
+```yaml
+# values.yaml
+port: 8080
+exports:
+  server-config:
+    debug: true
+```
+
+```yaml
+# charts/client/values.yaml
+serverPort: 9090
+```
+
+```yaml
+# charts/server/values.yaml
+exposePort: 80
+debug: false
+```
+
+### Value Precedence
+
+Because later changing the order of precedence between value-sources would be a breaking change (same input, but potentially different output), we should agree on an intuitive and user-friendly order of precedence before implementing this HIP.
+
+Suggested precedence:
+
+1. Explicitly set for subchart value (`client.port`)
+1. Explicitly set for parent chart's value (`port`)
+1. default for parent chart's value (`values.yaml` in parent chart)
+1. default for subchart value (`values.yaml` in subchart)
+
+For the example above, this would mean that `.Values.port`, `.Values.client.serverPort` and `.Values.server.exposePort` will default to `8080` unless e.g. `--set port=1234` is provided via flags, which would overwrite all these values.
+In contrast using e.g. `--set client.serverPort=42` would only overwrite the `.Values.client.serverPort` value.
+
+### Combination with `import-values`
+
+It should be able to use both, `export-values` and `import-values` independently and in combination. It should also be possible to export a value which was imported from a third chart.
+
+## Motivation
+
+Currently, it is not possible to compose charts using dependencies without leaking the structure of the values of the subcharts used.
+Users of a parent chart instead have to provide values to the subcharts directly. Alternatively, users can provide `global` values, but in that case the subcharts need to be aware of the fact that they are used as a dependency. In addition, `global` values are available globally as the name suggests and hence multiple subcharts have to have aligned value keys. As a result, the parent chart and its dependencies are rather tightly coupled.
+
+This HIP would allow to freely structure the values the user interacts with.
+
+The problem described above is less severe, if the subchart author, parent chart author and consumer are the same person or team.
+It becomes much more relevant for parent chart authors, that want to consume existing charts and provide it to a number of users without leaking the internal structure (i.e. the fact that it is using subcharts and how many) to the users.
+
+## Rationale
+
+Using the same parent chart as in the [specification](#specification) without `export-value`, the `port` value must match and must be specified twice by the user.
+
+```yaml
+# values.yaml
+client:
+  serverPort: 8080
+
+server:
+  exposePort: 8080
+```
+
+The proposed structure is not only cleaner for the user, but also less error prone since the port value is only maintained once.
+
+## Backwards Compatibility
+
+On one hand this change won't break any existing Helm chart since it only adds new mechanisms.
+On the other hand installing a chart which requires this feature with older versions of Helm make it fail silently, as values won't be passed to the child.
+There is currently no way to specify a minimum Helm version.
+The current workaround is to add this to a parent chart template, which will fix the otherwise silent failure:
+`{{- if semverCompare ">3.10.0" .Capabilities.HelmVersion.Version }} {{- fail "This chart requires helm version 3.10.0 or higher" }} {{- end }}`.
+A built-in mechanism to specify a minimum Helm version for a chart could be introduced in a separate HIP.
+Until such time, the introduction of this `export-values` functionality would require documenting this workaround for chart authors who wish to make their parent charts depend on the Helm version that introduced this functionality.
+
+## Reference Implementation
+
+TBD
+
+[helm/#3242]: https://github.com/helm/helm/issues/3242
+[helm/#7477]: https://github.com/helm/helm/pull/7477
+[helm/#10059]: https://github.com/helm/helm/pull/10059
+[import-values]: https://helm.sh/docs/topics/charts/#importing-child-values-via-dependencies