From 90563c44d03d00dc6de6a6d7f203d5ac6961ec4e Mon Sep 17 00:00:00 2001 From: Scott Rigby Date: Mon, 12 May 2025 16:35:01 -0400 Subject: [PATCH] Moved chart-defined plugins to this follow-up HIP from #388 Co-authored-by: George Jenkins Signed-off-by: Scott Rigby --- hips/hip-9999.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 hips/hip-9999.md diff --git a/hips/hip-9999.md b/hips/hip-9999.md new file mode 100644 index 00000000..8aac106b --- /dev/null +++ b/hips/hip-9999.md @@ -0,0 +1,134 @@ +--- +hip: 9999 +title: "H4HIP: Chart-defined plugins" +authors: [ "Scott Rigby ", "George Jenkins " ] +created: "2025-04-11" +type: "feature" +status: "draft" +helm-version: "4" +--- + +## Abstract + +This HIP builds upon [H4HIP: Improve and extend plugin system](./hip-9999.md) to define how charts can specify and use plugins in Helm 4. It enables chart authors to define plugins that are required for their charts to function, such as alternative render engines or download protocols for dependencies. + +## Motivation + +While the main plugin system HIP enables users to extend Helm's functionality, chart authors ([Application Distributors](https://github.com/helm/community/blob/main/user-profiles.md#2-application-distributor)) need a way to specify which plugins their charts require. This allows charts to use alternative render engines, download protocols, and other plugin-based functionality while ensuring users have the necessary plugins installed. + +## Specification + +Support for Chart-defined plugins will be added starting in Chart API v3. `Chart.yaml` will define a top-level `plugins` key, and `Chart.lock` capturing specific plugin versions and checksums. + +For the initial release of the new plugin system, chart authors will be able to define custom plugins for the following categories: + +- **Download** (to allow chart authors to specify plugins for downloading subcharts with different protocols than the default) +- **Manifest render** (for rendering a chart's templates into a set of Kubernetes resources using some other engine than gotemplate) + +After the initial plugin system release, the intention is to make it easy to continue adding new chart-defined plugin types to extend additional categories of non-default chart behavior as this becomes desirable. Some examples may be: + +- Values schema validation (for validating the chart's `values.yaml` file using something other than JSON Schema) +- Dependency resolution (for using a different subchart dependency resolver than the one currently used by Helm) + +To plan for forward compatibility, a `minimumHelmVersion` field may be added to allow future plugins to specify the minimum version of Helm that must be used for the chart (or since this is the version of Helm that introduced the new plugin, perhaps this can be auto-detected). + +A first pass for Chart-defined plugin syntax in `Chart.yaml`: + +```yaml +# made up URLs—these are not actual Helm 4 plugins yet +plugins: + - name: pkl + type: render.plugins.helm.sh/v1 + url: https://github.com/pkl-community/helm-pkl + version: 0.1.0 + - name: helmys + type: render.plugins.helm.sh/v1 + url: https://github.com/kubeys/helmys + version: 0.1.4 + - name: s3 + type: download.plugins.helm.sh/v1 + url: https://github.com/hypnoglow/helm-s3 + version: 0.16.3 + - name: git + type: download.plugins.helm.sh/v1 + url: https://github.com/aslafy-z/helm-git + version: 1.3.0 +``` + +### Helm plugin commands + +Commands will be added to allow packaging Chart-defined plugins within the chart: + +- `helm chart plugin build` similar to `helm dependency build` but for plugins +- `helm chart plugin update` similar to `helm dependency update` but for plugins + +### Distribution + +To enable airgapped installations and other use cases where downloading Chart-defined plugins is not feasible, plugins may be packaged and distributed with the chart itself, similar to how Helm 3 allows this for a chart's subchart dependencies. A command will be added to enable this (see H4HIP 9999: Improve and extend plugin system [Helm plugin commands specification](./hip-9999.md#Helm-plugin-commands-specification)). + +## Backwards compatibility + +Requirements for chart-defined plugins: + +- Chart-defined plugins, which are required to use the chart, MUST be made easily available to the end user. +- Any plugin functionality that affect Chart apiVersion 3 after it's inclusion in a full release of Helm 4 MUST follow the standard backwards compatibility contract within the same MAJOR version (ie, charts made previous to new plugins should "just work". New charts using initial or future plugins however may require a Helm minimum version for forward compatibility). + +## Security implications + +In Helm 4, users may still manually install plugins, but chart-defined plugins can also be either downloaded automatically or pre-packaged within a chart if not already downloaded. This could surprise a user if they are not made aware of this. + +Helm 4 will address this in the following ways: + +- Notify the user: + + To ensure Helm does not run third-party code without a user's knowledge, any chart-defined plugins not loaded as part of Helm's default distribution will notify the user when commands are run that would make use of those plugins. + +- Opt-in flags: + + The user will need to pass flags to explicitly acknowledge and opt-in to downloading (if not present) and running these third-party chart plugins. They will also need to pass a flag to opt-in when installing an unsigned plugin (see below). + +## Implementation Plan + +This work is dependent on, and will be in conjunction with, [H4HIP: Charts v3 Enablement](https://github.com/helm/community/blob/main/hips/hip-0020.md): + +- [ ] add Chart-defined `plugins` to Charts v3 schema + - [ ] `render`: allow chart authors to specify alternative render plugins + - [ ] `download`: allow chart authors to specify alternative download plugins (for non-default chart dependency schemes) +- [ ] allow Chart-defined plugins to be packaged within a chart's `plugins` directory. Particularly useful for airgap: + - [ ] update `pkg/action/package` to apply to Chart-defined plugins as well as subchart dependencies + - [ ] add CLI command to package these within the chart. Similar to `helm dependency update`, `dependency build` +- [ ] update other helm CLI commands that will invoke Chart-defined plugins (`helm template`, `install`, `upgrade`) + - [ ] add flags described in [Security implications](#Security-implications) + - [ ] automatically attempt to download chart-defined plugins, if they don't already exist locally + - [ ] automatically attempt to verify plugin signature (unless bypass flags are passed) + - [ ] automatically install the plugin if it is signed, and if the signature verifies (unless bypass flags are passed) + +## How to teach this + +- Create examples of Chart-defined plugins for the new plugin system that contributors can use as a model for their own plugins + - Chart-defined plugin example. The Gotemplate `render` plugin will have already created +- Write concise and easy to follow documentation for chart-defined plugins +- Write a blog post outlining how chart authors will benefit from chart-defined plugins, which can link to the documentation and these examples +- Create a presentation to propose for conference talks as another communition channel to make the community aware of chart-defined plugins + +## Open issues + +*Any points that are still being decided/discussed.* + +1. Chart-defined plugins will be required to use the chart. How will these plugins be made available to the end user? + - The chart will need to include a `plugins` section that lists the plugins that should be installed for the chart. + - Previously, users needed to opt-in to any non-Helm core code by installing plugins manually, but now the chart will include CHart-defined non-Helm core plugins by default. Is it enough for these plugins to be discoverable by the user with a new command `helm chart plugins list`? Or should an explicit flag be added to any Helm commands that use custom plugins (such as `install`, `template`, etc.) to require the user to opt-in to non-Helm core plugins before commands run them? + +## Rejected ideas + +*Why certain ideas that were brought while discussing this HIP were not ultimately pursued.* + +1. Helm 4 will not support chart-defined required plugins for Chart API v2. + + While Helm 3 currently allows additional keys to be added to the Chart struct while retaining backwards-compatibility, any keys that add *required* functionality for new charts to install would not be forwards compatible with older versions of Helm (such as renderer plugins). Therefore, for practical reasons, a top level `plugins` key to `Chart.yaml` will wait for Chart API v3. See [Specification](#Specification). + +1. Helm 4 will not continue to only support gotemplate for rendering manifests as Helm 3 did. + + By allowing alternative rendering engines, the Helm project accepts the additional complexity for users to troubleshoot or contribute to charts that may require learning new rendering engines other than gotemplate. This is a trade-off that Helm maintainers are willing to make in order to satisfy the many requests from the community for this feature. + + It also means the Helm project will not be able to write a comprehensive guide covering all the different template engines, since there will be many different rendering engines to choose from.