From 47c276bcb511359bbabcd8f147a49f8cee28cdd7 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Mon, 18 Nov 2024 21:42:44 -0800 Subject: [PATCH 01/10] Forward compatibility HIP Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 hips/hip-XXXX.md diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md new file mode 100644 index 00000000..3b45ab3d --- /dev/null +++ b/hips/hip-XXXX.md @@ -0,0 +1,134 @@ +--- +hip: 9999 +title: "Forward compatibility: Chart.yaml minimumHelmVersion" +authors: [ "George Jenkins " ] +created: "2024-11-18" +type: "feature" +status: "draft" +--- + +## Abstract + +This HIP proposes supporting a `minimumHelmVersion` field in `Chart.yaml`. +That will allow Helm to directly error if the Helm version used to operate on the chart is below this version. +Allowing Helm to provide forward compatibility guarantees for Helm features/functionality over time. + + +## Motivation + +Helm has no mechanism for a chart to declare the minimal version of Helm required for the chart to install/update correctly. +As such, it is invalid to release a chart that utilizes features/fixes included in newer versions of Helm. + +At best, any incompatibility will be detected and there will an explicit failure (and the user will be notified as an error). +But potentially an incompatibility may go undetected, and no hard error will be presented. + +While the hard-failure case is better, it still requires the user to debug and conclude the failure is due to a version mismatch. +The second "soft-failure" case is much worse, as it could lead to unexpected behavior in the deployed chart application. +Likely requiring a much more involved debugging requirement and confusing user experience. + +Providing a mechanism for a chart to prescribe the minimum versions of Helm for the chart's feature set will enable chart developers to prevent indirect errors for chart consumers/operators. + +Supporting a simple SemVer based `minimumHelmVersion` field in chart's `Chart.yaml` is thought to be a simple way to provide forward compatibility guarantees. + + +## Rationale + +It is thought that over time, as Helm extends its functionality, there will be greater scope for forward compatibility errors to present themselves. + +And in particular, the mechanism that describes the minimum feature set must be built into and understood by prior versions of Helm. + +Utilizing a simple minimum version SemVer field in a chart is thought to be a simple and succinct way to enable forward compatibility guarantees for future versions of Helm. + +Similar to the way the Go toolchains allow forward compatibility guarentees via [`go.mod`][1]. + + +## Specification + +`Chart.yaml` will include an optional field `minimumHelmVersion`, which is a [SemVer][2] string for the version of Helm required for the chart to operate: + +``` +minimumHelmVersion: [.[.PATCH]] +``` + +The minor and patch fields are optional. +And will be inferred as zeros if not specified. + +When loading a chart, iff the `minimumHelmVersion` exists, Helm will verify its version exceeds or equals the version constraint specified in the field. + +When "strict" loading of `Chart.yaml` is used: ie. the loading of `Chart.yaml` errors when unknown fields are present, Helm will first 'peek' into `Chart.yaml` and extract the `minimumHelmVersion` field (iff it exists) and perform the version constraint check at this point. +This is to provide better UX that simply erroring on any potential new fields in `Chart.yaml` that are unknown to the current version of Helm. + +`helm create` will pre-fill Chart.yaml's `minimumHelmVersion` field with the current version of Helm. +While this may not be strictly necessary, it will provide a backstop for features that may be included in the chart by the user for their current Helm version or `helm create`. +The user can remove/reduce the specified `minimumHelmVersion` if desired. + +`helm lint` will produce a warning, if the current version of Helm is newer than the minimum version constraint. +This is to encourage users to update the minimum version to currently utilized version of Helm (that the user is using to develop the chart). + + +## Backwards compatibility + +As `minimumHelmVersion` is an optional field, it will be inferred to be unset in existing charts. +And when unset, Helm will retain existing behavior (won't implement any checks) + +Older versions of Helm which don't understand the `minimumHelmVersion` field will actually ignore the field even if set (as they load `Chart.yaml` ignoring unknown fields). +However, there isn't anything that can practically be done to address this encoded behavior. +Also see [HIP-9999 (Default to strict `Chart.yaml` loading)](./hip-9999.md) for a fix for this going forward. + +Operations that utilize strict yaml loaded (such as `helm lint` in newer versions of Helm v3) will outright fail to load a `Chart.yaml` with `minimumHelmVersion` set (with a generic "unknown field" error). However, while this error isn't as specific as desirable, an error is appropriate. + + +## Security implications + +None + + +## How to teach this + +Update docs for `Chart.yaml` + + +## Reference implementation + +N/A + + +## Rejected ideas + +**Generic version contraints:** +It is thought a "minimum" constraint is preferred over a generic "constraint" system. +ie. where a user could list multiple version constraints to be satisfied +Similar to e.g. [pip's requirement-specifiers][3]. +This is because Helm makes great effort to remain [backwards compatible][4]. +And so it is presumed unnecessary that a user would need to specify anything but a single minimum version constraint. +And in the future when Helm does make breaking changes to charts, it is expected the chart API version will be incremented to explicitly signify this new incompatiblity. + +**Capabilities:** +Providing a capabilities based system. +Rather than just directly inferring Helm capabilities from its version. + +A `Chart.yaml` could describe its required features ie. capabilities it expects/requires the Helm version to provide. +From which Helm could inspect and matches against features/capabilities the in use version does provide. +However, since core Helm capabilities are only every additive due to Helm's [backwards-compatibility rules][4], a capabilities based system is redundant. + +*NB: at the time of writing, plugins for extending Helm's functionality are being heavily discussed. +And while plugins will likely allow extending capabilities independent of the Helm version. +It is presumed plugins will include their own version constraint specifier system. +That will ensure conditions for valid plugin versions are met* + +### Future ideas + +Extending Helm lint to detect incompatible chart features for the currently specified `minimumHelmVersion`. + + +## Open issues + +N/A + + +## References + +[1]: "Golang forward compatibility" +[2]: "Semantic versioning" +[3]: "Pip request-specifiers" +[4]: "hip-0004: Document backwards-compatibility rules" From 832292017e92636823cb1bc02e83311f9735d30e Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Tue, 19 Nov 2024 09:34:45 -0800 Subject: [PATCH 02/10] grammar Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 3b45ab3d..6a40d539 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -11,7 +11,7 @@ status: "draft" This HIP proposes supporting a `minimumHelmVersion` field in `Chart.yaml`. That will allow Helm to directly error if the Helm version used to operate on the chart is below this version. -Allowing Helm to provide forward compatibility guarantees for Helm features/functionality over time. +This allows Helm Helm to provide forward compatibility guarantees for Helm features/functionality over time. ## Motivation @@ -19,12 +19,11 @@ Allowing Helm to provide forward compatibility guarantees for Helm features/func Helm has no mechanism for a chart to declare the minimal version of Helm required for the chart to install/update correctly. As such, it is invalid to release a chart that utilizes features/fixes included in newer versions of Helm. -At best, any incompatibility will be detected and there will an explicit failure (and the user will be notified as an error). +At best, any incompatibility will be detected and there will be an explicit failure (and the user will be notified as an error). But potentially an incompatibility may go undetected, and no hard error will be presented. -While the hard-failure case is better, it still requires the user to debug and conclude the failure is due to a version mismatch. -The second "soft-failure" case is much worse, as it could lead to unexpected behavior in the deployed chart application. -Likely requiring a much more involved debugging requirement and confusing user experience. +While the hard-failure case is better, it still requires the user to debug and realize the failure is due to a version mismatch. +The second "soft-failure" case is much worse, as it could lead to unexpected behavior in the deployed chart application, likely requiring a much more involved debugging requirement and confusing user experience. Providing a mechanism for a chart to prescribe the minimum versions of Helm for the chart's feature set will enable chart developers to prevent indirect errors for chart consumers/operators. From ed5860a0e596881efee42831ea1f0ae06c6cdbf8 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Tue, 19 Nov 2024 10:02:36 -0800 Subject: [PATCH 03/10] tidy up a little Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 6a40d539..94ede0c6 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -62,6 +62,7 @@ While this may not be strictly necessary, it will provide a backstop for feature The user can remove/reduce the specified `minimumHelmVersion` if desired. `helm lint` will produce a warning, if the current version of Helm is newer than the minimum version constraint. +Or the `minimumHelmVersion` field is unset for the given chart. This is to encourage users to update the minimum version to currently utilized version of Helm (that the user is using to develop the chart). @@ -72,9 +73,6 @@ And when unset, Helm will retain existing behavior (won't implement any checks) Older versions of Helm which don't understand the `minimumHelmVersion` field will actually ignore the field even if set (as they load `Chart.yaml` ignoring unknown fields). However, there isn't anything that can practically be done to address this encoded behavior. -Also see [HIP-9999 (Default to strict `Chart.yaml` loading)](./hip-9999.md) for a fix for this going forward. - -Operations that utilize strict yaml loaded (such as `helm lint` in newer versions of Helm v3) will outright fail to load a `Chart.yaml` with `minimumHelmVersion` set (with a generic "unknown field" error). However, while this error isn't as specific as desirable, an error is appropriate. ## Security implications From 9c88194b2dea983f5721af46ce7a51a141c14523 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Wed, 20 Nov 2024 09:52:32 -0800 Subject: [PATCH 04/10] typoi Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 94ede0c6..2c07a633 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -11,7 +11,7 @@ status: "draft" This HIP proposes supporting a `minimumHelmVersion` field in `Chart.yaml`. That will allow Helm to directly error if the Helm version used to operate on the chart is below this version. -This allows Helm Helm to provide forward compatibility guarantees for Helm features/functionality over time. +This allows Helm to provide forward compatibility guarantees for Helm features/functionality over time. ## Motivation From aaa97599d2039e2d0a9c6458ae9da470a043856a Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:35:56 -0800 Subject: [PATCH 05/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 2c07a633..f2e2c75c 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -71,7 +71,7 @@ This is to encourage users to update the minimum version to currently utilized v As `minimumHelmVersion` is an optional field, it will be inferred to be unset in existing charts. And when unset, Helm will retain existing behavior (won't implement any checks) -Older versions of Helm which don't understand the `minimumHelmVersion` field will actually ignore the field even if set (as they load `Chart.yaml` ignoring unknown fields). +Older versions of Helm which do not understand the `minimumHelmVersion` field will ignore the field even if set (as they load `Chart.yaml` ignoring unknown fields). However, there isn't anything that can practically be done to address this encoded behavior. From 395980cc4042144d2804796d29e855828e3edd73 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:36:40 -0800 Subject: [PATCH 06/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index f2e2c75c..84661c1a 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -105,7 +105,7 @@ Providing a capabilities based system. Rather than just directly inferring Helm capabilities from its version. A `Chart.yaml` could describe its required features ie. capabilities it expects/requires the Helm version to provide. -From which Helm could inspect and matches against features/capabilities the in use version does provide. +Helm could inspect and match against features/capabilities that the specific version does provide. However, since core Helm capabilities are only every additive due to Helm's [backwards-compatibility rules][4], a capabilities based system is redundant. *NB: at the time of writing, plugins for extending Helm's functionality are being heavily discussed. From 16aaa968ecc6ae66e8f93ee757aad646dad244d7 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:40:08 -0800 Subject: [PATCH 07/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 84661c1a..60a0a33e 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -19,7 +19,7 @@ This allows Helm to provide forward compatibility guarantees for Helm features/f Helm has no mechanism for a chart to declare the minimal version of Helm required for the chart to install/update correctly. As such, it is invalid to release a chart that utilizes features/fixes included in newer versions of Helm. -At best, any incompatibility will be detected and there will be an explicit failure (and the user will be notified as an error). +At best, any incompatibility will be detected and there will be an explicit failure (and the user will be notified with an error). But potentially an incompatibility may go undetected, and no hard error will be presented. While the hard-failure case is better, it still requires the user to debug and realize the failure is due to a version mismatch. From 32fbf22cac5d7ff0cac13d940be1564fbd4255de Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:40:33 -0800 Subject: [PATCH 08/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 60a0a33e..4dbae736 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -10,7 +10,7 @@ status: "draft" ## Abstract This HIP proposes supporting a `minimumHelmVersion` field in `Chart.yaml`. -That will allow Helm to directly error if the Helm version used to operate on the chart is below this version. +By enabling this feature, an error can be raised if the Helm version used to operate on the chart is below the declared version. This allows Helm to provide forward compatibility guarantees for Helm features/functionality over time. From c46f37a1c5be08141e4d73d73e0c4676cadb6e4a Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:41:03 -0800 Subject: [PATCH 09/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 4dbae736..9636e5f1 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -55,7 +55,7 @@ And will be inferred as zeros if not specified. When loading a chart, iff the `minimumHelmVersion` exists, Helm will verify its version exceeds or equals the version constraint specified in the field. When "strict" loading of `Chart.yaml` is used: ie. the loading of `Chart.yaml` errors when unknown fields are present, Helm will first 'peek' into `Chart.yaml` and extract the `minimumHelmVersion` field (iff it exists) and perform the version constraint check at this point. -This is to provide better UX that simply erroring on any potential new fields in `Chart.yaml` that are unknown to the current version of Helm. +This is to provide better UX than simply raising an error on any potential new fields in `Chart.yaml` that are unknown to the current version of Helm. `helm create` will pre-fill Chart.yaml's `minimumHelmVersion` field with the current version of Helm. While this may not be strictly necessary, it will provide a backstop for features that may be included in the chart by the user for their current Helm version or `helm create`. From 65777bba19d40bff0b8f3884e3808418b9a02e22 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 24 Nov 2024 10:41:27 -0800 Subject: [PATCH 10/10] Update hips/hip-XXXX.md Co-authored-by: Andrew Block Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 9636e5f1..3c2bc3ad 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -69,7 +69,7 @@ This is to encourage users to update the minimum version to currently utilized v ## Backwards compatibility As `minimumHelmVersion` is an optional field, it will be inferred to be unset in existing charts. -And when unset, Helm will retain existing behavior (won't implement any checks) +And when unset, Helm will retain existing behavior (no check will be implemented) Older versions of Helm which do not understand the `minimumHelmVersion` field will ignore the field even if set (as they load `Chart.yaml` ignoring unknown fields). However, there isn't anything that can practically be done to address this encoded behavior.