Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions hips/hip-0026.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ This will result in making Helm not only more extensible, but also more maintain

## Scope

This HIP will cover the overall vision for the new plugin system, and an [implementation plan](#Implementation-Plan) for initial plugin types introduced into this system. This will will allow more categories of Helm functionality to become extended through additional plugin types in the future.
This HIP will cover the overall vision for the new plugin system, and an [implementation plan](#Implementation-Plan) for initial plugin types introduced into this system. This will allow more categories of Helm functionality to become extended through additional plugin types in the future.

This HIP focuses primarily on CLI users.
SDK users will not be required to use Wasm plugin functionality—it is expected that they may instead prefer to directly include Go libraries exposed by authors of those plugins.
Expand All @@ -39,8 +39,8 @@ The [high-level goal](https://helm.sh/docs/topics/plugins/#an-overview) of the H

However, Helm 3 plugins had the following limitations:

- Because plugins are primarily intended to add new Helm CLI subcommands, the Helm 3 plugin architecure is not helpful for SDK users, nor Chart Authors, or for customizing the existing Helm core functionality.
- Helm 3 plugins call a user-specified arbitrary binary through a subprocess, which does not allow Helm to limit the scope of these commands (see Wasm sandboxing under [Security implications](#Security-implications) for how this will be resolved). Plugin maintainers must also be concerned about OS and architecture compatbility of pre-built binaries and scripts.
- Because plugins are primarily intended to add new Helm CLI subcommands, the Helm 3 plugin architecture is not helpful for SDK users, nor Chart Authors, or for customizing the existing Helm core functionality.
- Helm 3 plugins call a user-specified arbitrary binary through a subprocess, which does not allow Helm to limit the scope of these commands (see Wasm sandboxing under [Security implications](#Security-implications) for how this will be resolved). Plugin maintainers must also be concerned about OS and architecture compatibility of pre-built binaries and scripts.
- There is only one specialized type of Helm 3 plugin—**downloader plugins**—which comes closest to what Helm 4 is modeling its new plugin types after. Downloader plugins are called by Helm for a specific purpose and have a well-defined scope. The main limitation here is that it does not allow users to modify other default behaviors of Helm.

### Other Helm 3 customization options did not adequately address the problem this HIP solves either
Expand All @@ -65,7 +65,7 @@ This section outlines the Wasm based plugin system, and the plan to define a wid
- #### Plugin Type
Which Helm functionality the plugin can extend. Examples: `subcommand`, `downloader`, `postrender`
- #### Plugins
The individual, optionally intallable, plugins themselves
The individual, optionally installable, plugins themselves

### Directory Structure and Go Packages

Expand All @@ -80,7 +80,7 @@ pkg

### Plugin System specification

The [Plugin System](#plugin-system) is versioned becasue in order to not break Helm 3 plugins in Helm 4, while allowing the project to deprecate old versions and make future changes in a sane way.
The [Plugin System](#plugin-system) is versioned in order to not break Helm 3 plugins in Helm 4, while allowing the project to deprecate old versions and make future changes in a sane way.

* `v1`: The new Wasm Plugin System
* `legacy`: Legacy support for Helm 3 subprocess plugins; no new fields expected (deprecated in Helm 4, to be removed in Helm 5)
Expand Down Expand Up @@ -134,7 +134,7 @@ New fields:
- `helm plugin install` installs a plugin from a URL (see Distribution specification below)
- `helm plugin update` will check for updates, then follow the same behavior of `plugin install`
- `helm plugin sign` will use Helm 4's built-in provenance signing mechanisms as a convenience to sign a plugin
- `helm plugin verify` will use Helm 4's built-in provenance mechanisms as a conveniencce to verify a signed plugin
- `helm plugin verify` will use Helm 4's built-in provenance mechanisms as a convenience to verify a signed plugin

### Distribution specification

Expand All @@ -144,15 +144,15 @@ Helm will initially support installing plugins from http URLs, from version cont

The distribution format may either be discrete files (ie. filesystem or version control system), or packed tar archives (e.g. filesystem and URLs). Format described below.

Eventually, it is recommended that Helm supports plugin distribution via OCI artifacts. And further distribtion schemes e.g. S3 could be supported via plugins themselves.
Eventually, it is recommended that Helm supports plugin distribution via OCI artifacts. And further distribution schemes e.g. S3 could be supported via plugins themselves.

#### Plugin distribution format

A plugin comprises of the following filesystem structure (or a tar archive of):

```
.
├── [LICENSE] # Optional: plugin licence
├── [LICENSE] # Optional: plugin license
├── NAME.wasm # Wasm binary
└── plugin.yaml # Plugin manifest
```
Expand Down Expand Up @@ -195,28 +195,28 @@ For Wasm Plugin Interfacing, Helm 4 will be leveraging the Extism project. See <

Extism is the most mature and well-supported Wasm plugin system today, has a large and growing ecosystem of supported languages and libraries, is actively maintained by a team of core contributors with a solid backwards compatibility policy, has a strong security focus, and makes Wasm plugin interfacing easier to implement than other systems.

By chosing Extism, the new [XTP Bindgen](https://github.com/dylibso/xtp-bindgen) convenience tool will also be available for polyglot plugin developers to create bindings and codegen for their Extism Wasm host functions. See [additional information here](https://github.com/extism/go-pdk?tab=readme-ov-file#generating-bindings).
By choosing Extism, the new [XTP Bindgen](https://github.com/dylibso/xtp-bindgen) convenience tool will also be available for polyglot plugin developers to create bindings and codegen for their Extism Wasm host functions. See [additional information here](https://github.com/extism/go-pdk?tab=readme-ov-file#generating-bindings).

## Backwards compatibility

Requirements for the new plugin system and the initial default plugins:

- Helm 4 MUST continue to be as easy to install as Helm 3
- The default installation for Helm 4 MUST be "batteries-included". I.e., users will not need to take any additional installation steps for the new plugin system in order to use Helm's default functionality out of the box
- Plugins used by Helm MUST be explicitly chosen by the end-user, and be clearly discoverable by the end user that they will be in use. This is to follow the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) and make it easier for maintiners to support end users who may not be aware they or someone else has chosen to not use a certain portion of Helm's default behavior in their environment.
- Plugins used by Helm MUST be explicitly chosen by the end-user, and be clearly discoverable by the end user that they will be in use. This is to follow the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) and make it easier for maintainers to support end users who may not be aware they or someone else has chosen to not use a certain portion of Helm's default behavior in their environment.
- The new plugin system MUST NOT prevent SDK users from using the default functionality
- A security plan approved by Helm's security team MUST be adopted for developing and releasing this new architecture model

## Security implications

### Summary

The new plugins sytem will be based on Wasm for improved security over the previous subprocess plugin model in Helm 3, and for improved call and response options that allow extending more of Helm's functionality with plugins than was previously feasible.
The new plugins system will be based on Wasm for improved security over the previous subprocess plugin model in Helm 3, and for improved call and response options that allow extending more of Helm's functionality with plugins than was previously feasible.

Additional steps are also taken to improve security:
- Tools are added for signing and verifying plugins
- Plugin authors are encouraged to follow best security practices (Helm will surface when these are not followed), and users are encouraged to take advantage of these
- Helm will automaitcally attempt to verify the provenance signature of a plugin by default when it is first installed
- Helm will automatically attempt to verify the provenance signature of a plugin by default when it is first installed
- [Helm 3 post-renderers](https://helm.sh/docs/topics/advanced/#post-rendering) will now also become a plugin type in the new Wasm plugin system

### Details
Expand All @@ -237,7 +237,7 @@ Helm 4 will address this in the following ways:

For plugins that follow the above recommendations, end users are strongly encouraged to verify the provenance signature. Users may also inspect the source code before using plugins, and if they wish may build the Wasm plugin themselves.

When a plugin is first installed using `plugin install` the CLI will exit with an informative error if a plugin is unsigned, and the user has not explicitly passed a flag (eg, `--allow-insecure-plugins`) to bypass this. Plugins installed from the local filesystem (from source as opposed to a tarball) are excepted from signing requirements, to enable local plugin devlopment.
When a plugin is first installed using `plugin install` the CLI will exit with an informative error if a plugin is unsigned, and the user has not explicitly passed a flag (eg, `--allow-insecure-plugins`) to bypass this. Plugins installed from the local filesystem (from source as opposed to a tarball) are excepted from signing requirements, to enable local plugin development.

Assuming the plugin is signed (and not bypassed with the `--allow-insecure-plugins` flag), Helm will also attempt to verify the provenance signature BY DEFAULT when the plugin is first installed. If the signature is not found, or the signature is invalid, the user will be notified and the plugin will not be loaded. A user may pass a flag to bypass this verification check with an insecure flag too, but must explicitly do this to acknowledge they are bypassing the verification check.

Expand All @@ -247,7 +247,7 @@ Work for the plugin system will follow the [H4HIP: Helm 4 Development Process](h

1. Marking this HIP as accepted (including security plan in this HIP approved by Helm's security team)
1. May. 2025: Engineering on this feature begins
1. Aug. 2025: Have inital work on all features included in the initial implementation, adhering to Feature freeze for Helm 4 release preparation
1. Aug. 2025: Have initial work on all features included in the initial implementation, adhering to Feature freeze for Helm 4 release preparation
1. Nov. 2025: Initial offering feature complete by Helm v4.0.0 release
1. Post-release: Follow up HIPs for additional plugin types and features will match future Helm 4 Minor version release schedule

Expand Down Expand Up @@ -277,7 +277,7 @@ Work for the plugin system will follow the [H4HIP: Helm 4 Development Process](h
- `cli`: No default. Similarly we should write a simple example proving the host function works
- Write concise and easy to follow documentation for the new plugin system
- Write a blog post outlining how the community will benefit from the new plugin system, 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 the new plugin system
- Create a presentation to propose for conference talks as another communication channel to make the community aware of the new plugin system
- Reach out to authors of community plugin to encourage them to update to the new plugin types (examples could be moving the [s3 downloader plugin](https://artifacthub.io/packages/helm-plugin/s3/s3) to the new `download` type, and the [Helm Diff plugin](https://artifacthub.io/packages/helm-plugin/diff/helm-diff) to the new `cli` type)

## Reference implementation
Expand All @@ -298,7 +298,7 @@ The host functions are prototyped using Go testing, in `/testdriver/main_test.go

1. Helm 4 will not create a central repository for plugins.

This is a non-starter for the Helm project. Helm maintainers have learned from the experience of the formerly centralized charts repo that it does not scale well or enable eccosystem growth as much as a distributed community-managed model. See <https://github.com/helm/community/blob/main/hips/archives/helm/distributed-search.md>.
This is a non-starter for the Helm project. Helm maintainers have learned from the experience of the formerly centralized charts repo that it does not scale well or enable ecosystem growth as much as a distributed community-managed model. See <https://github.com/helm/community/blob/main/hips/archives/helm/distributed-search.md>.

1. Helm 4 have ruled out the following technologies for plugin interfacing in Helm 4:
- [WASI Preview 2](https://github.com/WebAssembly/WASI/tree/main/wasip2#readme) / [WIT IDL](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) / [Wasm Component Model](https://github.com/webassembly/component-model)
Expand All @@ -317,7 +317,7 @@ The host functions are prototyped using Go testing, in `/testdriver/main_test.go

- [Web Assembly for Proxies (Go SDK)](https://github.com/proxy-wasm/proxy-wasm-go-sdk)

Problem: This is largely Envoy-specific, used for their [Wasm HTTP filter plugin](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/wasm_filter), and does suit our use case well.
Problem: This is largely Envoy-specific, used for their [Wasm HTTP filter plugin](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/wasm_filter), and does not suit our use case well.

- [Go native plugin system](https://pkg.go.dev/plugin)

Expand All @@ -337,6 +337,6 @@ The host functions are prototyped using Go testing, in `/testdriver/main_test.go

Precedents:

Helm [2.1.0](https://v2.helm.sh/docs/plugins/#downloader-plugins) introduced the Helm plugin concept, mainly as a way to add additinal helm CLI subcommands that are not part of the built-in Helm codebase. This is helpful for adding new one-off functions, but does not allow users to extend the default behavior of Helm.
Helm [2.1.0](https://v2.helm.sh/docs/plugins/#downloader-plugins) introduced the Helm plugin concept, mainly as a way to add additional helm CLI subcommands that are not part of the built-in Helm codebase. This is helpful for adding new one-off functions, but does not allow users to extend the default behavior of Helm.

Later Helm [2.4.0](https://v2.helm.sh/docs/plugins/#downloader-plugins) introduced the downloader plugin, which did make Helm core functionality extensible—in this case allowing users to download a chart from other sources than HTTP/S repos by specifying any other protocols such as [s3](https://artifacthub.io/packages/helm-plugin/s3/s3) or [git](https://artifacthub.io/packages/helm-plugin/git/helm-git).