H4HIP: Charts v3 Enablement

HIP	Title	Author(s)	Created	Type	Status
0020	H4HIP: Charts v3 Enablement	Matt Farina matt.farina@suse.com	2025-01-09	feature	accepted

Abstract

This HIP proposes the creation of charts v3, updating Helm to handle charts v2 and v3, and a timeline for the general availability of charts v3 that can happen after the release of Helm v4.0.0.

Motivation

Many of the proposed changes for Helm v4 affect charts. Layering these onto existing charts will sometimes cause chart installation and upgrade to happen differently in Helm v3 and Helm v4, as both will need to live side by side for a time. It also means that testing of charts for v3 can produce a different result when installed with Helm v4.

In addition to the affects of the changes, Helm v4 development has a fixed timeline and making changes to Helm in addition to reworking charts is not likely to fit within that fixed window. Enabling the development of charts v3 to happen as an experiment that becomes generally available after the release of Helm v4 provides more time to continue the work and get feedback.

The goal is to provide adequate time to work on chart changes while doing it in a way that enables trust in existing charts to run as they were tested.

Rationale

Charts v2 were created for Helm v3 and introduced minor changes. The code that handles the chart versions is the same with some checking to handle the differences. This handling ended up having numerous bugs that had to be worked out in patch releases.

The chart changes being proposed for Helm v4 are more significant. Mixing those in alongside the current chart version handling will have trouble limiting bugs will enabling the changes and keeping existing charts functioning properly.

The design specified here is meant to enable the current charts to work as expected while providing space for more radical changes.

Specification

Helm has numerous packages that do various things, from working with charts to storing release information. These packages all expect there to be one version of a particular thing. To support multiple versions of charts, the chart, chartutil, engine, and release packages will be made multi-version. (e.g., engine will have a v1 and v2 versions). In addition to enabling a new version of charts, this will enable the gotpl engine to evolve as needed to support the new version of charts. The chartutil may be combined with the chart package and the releaseutil package may be combined with the release package for simplification of the package structure.

The versioning of the packages will follow the same structure that Kubernetes does with its APIs. This means a thing will have a directory and within it will be sub-directories for the versions. The version specific implementation will be in the version specific sub-directory. For example,

chart
├── v2
└── v3

The version will not use a separate Git repository or Go modules. The reason for this is the added complexity of managing the repositories and modules is added work to manage changes which will slow down velocity, will make releases more complex, and make the Helm SDK more complicated to work with.

The existing versions of these packages will be externally facing while the new versions will be developed in internal as experiments until they are complete enough for release. When ready for release, these packages will be moved to the public locations.

To illustrate this, while in development the chart package will have the following structure:

internal/chart
└── v3
pkg/chart
└── v2

Once the new chart packages have (a) a stable API and (b) are feature complete the structure will be merged to look like:

pkg/chart
├── v2
└── v3

While in development, as an experiment, the pkg/gates package will be used to create an opt-in environment variable to enable a new chart version. This is how the OCI experimental feature was handled.

Backwards compatibility

This development and process is designed with backwards compatibility in mind. The package locations will change, which is ok in a major version of Helm. The existing charts will be preserved so that their installation process continues to work as expected from Helm v3. New features and changes to charts can be added in without impacting existing charts.

While the new chart version is being developed and is going through breaking changes, the chart will be an opt-in feature which will enable us to warn users about the state of it.

Security implications

N/A

How to teach this

There are a few ways to teach this:

1. Documentation: The chart documentation will be updated to teach both versions of charts.
2. Helm Create: Helm create will be updated to use the new chart version and provide an example.
3. Blog and Webinars: The marketing options open to Helm will be used to share details and teach about the new chart version.

Reference implementation

N/A

Rejected ideas

An option to detect the chart version within existing code was seen as an option. This is how charts apiVersion is handled for v1 and v2. This is problematic as large changes in charts will be difficult to work on and test to ensure nothing breaks across version.

Open issues

N/A

References

N/A