NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules · #2801 by repository stars
Last release 6 days ago
01 Oct 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
910 releases · first in 2020
One column per quarter.
Nothing published for this version
This minor release comes with various bug fixes and improvements.
Release date: 2025-02-19
This minor release comes with various bug fixes and improvements.
In addition, the Kubernetes dependencies have been updated to v1.32.1, Helm has been updated to v3.17.1 and various other controller dependencies have been updated to their latest version.
Fixes:
ValuesReference an alias for backwards compat
#1126Improvements:
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
This minor release comes with various bug fixes and improvements.
Release date: 2024-09-26
This minor release comes with various bug fixes and improvements.
The chart values schema
validation can now be disabled for install and upgrade actions by setting
disableSchemaValidation under .spec.install and .spec.upgrade of a
HelmRelease object.
HelmReleases that result in failure during uninstall will now be retried until the uninstall succeeds without any error. See handling failed uninstall docs for various remediations based on the cause of the failure.
helm-controller in sharded deployment configuration now supports cross-shard dependency check. This allows a HelmRelease to depend on other HelmReleases managed by different controller shards.
In addition, the Kubernetes dependencies have been updated to v1.31.1, Helm has been updated to v3.16.1 and various other controller dependencies have been updated to their latest version. The controller is now built with Go 1.23.
Fixes:
Improvements:
This patch release fixes a backwards compatibility issue that could occur when trying to move from the v2beta1 to v2 API while specifing .spec.chartRe
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Deprecated fields have been removed from the HelmRelease API:
Release date: 2024-05-08
This is the general availability release of helm-controller. From now on, this controller follows the Flux release cadence and support pledge.
This release promotes the HelmRelease API from v2beta2 to v2 (GA), and
comes with new features, improvements and bug fixes.
In addition, the controller has been updated to Kubernetes v1.30.0, Helm v3.14.4, and various other dependencies to their latest version to patch upstream CVEs.
The helm.toolkit.fluxcd.io/v2 API comes with a new field
.spec.chartRef
that adds support for referencing OCIRepository and HelmChart objects in a HelmRelease.
When using .spec.chartRef instead of .spec.chart, the controller allows the reuse
of a Helm chart version across multiple HelmRelease resources.
The notification mechanism has been improved to provide more detailed metadata
in the notification payload. The controller now annotates the Kubernetes events with
the appVersion and version of the Helm chart, and the oci digest of the
chart artifact when available.
Starting with this version, the recommended way of referencing Helm charts stored in container registries is through OCIRepository.
The OCIRepository provides more flexibility in managing Helm charts,
as it allows targeting a Helm chart version by tag, semver or OCI digest.
It also provides a way to
filter semver tags,
allowing targeting a specific version range e.g. pre-releases only, patch versions, etc.
Using OCIRepository objects instead of HelmRepository and HelmChart objects
improves the controller's performance and simplifies the debugging process.
If a chart version gets overwritten in the container registry, the controller
will detect the change in the upstream OCI digest and reconcile the HelmRelease
resources accordingly.
Promoting
a Helm chart version to production can be done by pinning the OCIRepository
to an immutable digest, ensuring that the chart version is not changed unintentionally.
Helm OCI example:
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: OCIRepository
metadata:
name: podinfo
namespace: default
spec:
interval: 10m
layerSelector:
mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
operation: copy
url: oci://ghcr.io/stefanprodan/charts/podinfo
ref:
semver: "*"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: podinfo
namespace: default
spec:
interval: 10m
chartRef:
kind: OCIRepository
name: podinfo
The helm.toolkit.fluxcd.io CRD contains the following versions:
New optional fields have been added to the HelmRelease API:
.spec.chartRef allows referencing chart artifacts from OCIRepository and HelmChart objects..spec.chart.spec.ignoreMissingValuesFiles allows ignoring missing values files instead of failing to reconcile.Deprecated fields have been removed from the HelmRelease API:
.spec.chart.spec.valuesFile replaced by .spec.chart.spec.valuesFiles.spec.postRenderers.kustomize.patchesJson6902 replaced by .spec.postRenderers.kustomize.patches.spec.postRenderers.kustomize.patchesStrategicMerge replaced by .spec.postRenderers.kustomize.patches.status.lastAppliedRevision replaced by .status.history.chartVersionHelmRelease v2beta2 manifests stored in Git
are not using the deprecated fields. Search for valuesFile and replace it with valuesFiles,
replace patchesJson6902 and patchesStrategicMerge with patches.
Commit and push the changes to the Git repository, then wait for Flux to reconcile the changes.apiVersion field of the HelmRelease resources to helm.toolkit.fluxcd.io/v2,
commit and push the changes to the Git repository.Bumping the API version in manifests can be done gradually. It is advised to not delay this procedure as the beta versions will be removed after 6 months.
Improvements:
.spec.ignoreMissingValuesFiles to HelmChartTemplate API
#942.spec.chartRef
#945.spec.chartRef
#905Fixes:
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
This prerelease comes with improvements in the HelmRelease status reporting. After recovering from a reconciliation failure, sometimes the status may
Release date: 2024-02-05
This prerelease comes with improvements in the HelmRelease status reporting. After recovering from a reconciliation failure, sometimes the status may show stale conditions which could be misleading. This has been fixed by ensuring that the stale failure conditions get updated after failure recovery.
Improvements:
Nothing published for this version
This prerelease comes with an update to the Kubernetes dependencies to v1.28.6 and various other dependencies have been updated to their latest versio
Release date: 2024-02-01
This prerelease comes with an update to the Kubernetes dependencies to v1.28.6 and various other dependencies have been updated to their latest version to patch upstream CVEs.
In addition, the controller is now built with Go 1.21.
Improvements:
Nothing published for this version
Nothing published for this version
This prerelease fixes a bug that resulted in the controller not being able to properly watch HelmRelease resources with specific labels.
This prerelease fixes a backwards compatibility issue that could occur when trying to move from the v2beta1 to v2beta2 API while enabling drift detect
This prerelease fixes a backwards compatibility issue that could occur when
trying to move from the v2beta1 to v2beta2 API while enabling drift
detection.
In addition, logging has been improved to provide faster feedback on any
HTTP errors encountered while fetching HelmChart artifacts, and the controller
will now set the Stalled condition as soon as it detects to be out of retries
without having to wait for the next reconciliation.
Lastly, Helm has been updated to v3.13.3.
Fixes:
Improvements:
Nothing published for this version
Nothing published for this version
The .patchesStrategicMerge and .patchesJson6902 Kustomize post-rendering fields have been deprecated in favor of .patches.
Release date: 2023-12-12
This prerelease promotes the HelmRelease API from v2beta1 to v2beta2.
The promotion of the API is accompanied by a number of new features and bug
fixes. Refer to the highlights section below for more information.
In addition to the API promotion, this prerelease updates the controller dependencies to their latest versions. Making the controller compatible with Kubernetes v1.28.x, while updating the Helm library to v3.13.2, and the builtin version of Kustomize used for post-rendering to v5.3.0.
Lastly, the base controller image has been updated to Alpine v3.19.
The upgrade is backwards compatible, and the controller will continue to
reconcile HelmRelease resources of the v2beta1 API without requiring any
changes. However, making use of the new features requires upgrading the API
version.
.spec.driftDetection.mode field. Refer to the drift detection section
in the v2beta2 specification for more information..spec.driftDetection.ignore field. Refer to the
ignore rules section
in the v2beta2 specification to learn more..spec.test.filters field.
Refer to the test filters section
in the v2beta2 specification for more details.kstatus
and sets Reconciling and Stalled conditions. See the Conditions section
in the v2beta2 specification to read more about the conditions..spec.maxHistory default value has been lowered from 10 to 5 to
increase the controller's performance..status.history field. This includes any Helm test
results when enabled..patchesStrategicMerge and .patchesJson6902 Kustomize post-rendering
fields have been deprecated in favor of .patches.status.lastAttemptedConfigDigest field has been introduced to track the
last attempted configuration digest using a hash of the composed values..status.lastAttemptedReleaseAction field has been introduced to accurately
determine the active remediation strategy..status.lastHandledForceAt and .status.lastHandledResetAt fields have
been introduced to track the last time a force upgrade or reset was handled.
This to accomadate newly introduced annotations to force upgrades and resets..status.lastAppliedRevision and .status.lastReleaseRevision fields
have been deprecated in favor of .status.history..status.lastAttemptedValuesChecksum has been deprecated in favor of
.status.lastAttemptedConfigDigest.Although the v2beta1 API is still supported, it is recommended to upgrade to
the v2beta2 API as soon as possible. The v2beta1 API will be removed after
6 months.
To upgrade to the v2beta2 API, update the apiVersion field of your
HelmRelease resources to helm.toolkit.fluxcd.io/v2beta2 after updating the
controller and Custom Resource Definitions.
deployed state already.pending-install, pending-upgrade
or pending-rollback state, and wil forcefully unlock the release (to a
failed state) to allow the controller to reattempt the release..spec which require a Helm uninstall for the
changes to be successfully applied are now detected. For example, a change in
.spec.targetNamespace or .spec.releaseName.- to ensure the
release name is unique.v2beta2 specification for more information.--snapshot-digest-algo
controller flag. The default value is sha256.HelmChart resource for a HelmRelease is not Ready, the
Conditions of the HelmRelease will now contain more detailed information
about the reason.To get a full overview of all changes, and see examples of the new features. Please refer to the v2beta2 specification.
Improvements:
HelmRelease reconciliation logic
#738
#816
#825
#829
#830
#833
#836HelmRelease
#815forceAt and resetAt annotations
#823v2beta2 API
#828Nothing published for this version
Nothing published for this version
This prerelease contains an improvement to retry the reconciliation of a HelmRelease as soon as the chart is available in storage, instead of waiting
Release date: 2023-10-11
This prerelease contains an improvement to retry the reconciliation of a
HelmRelease as soon as the chart is available in storage, instead of waiting
for the next reconciliation interval. Which is particularly useful when the
source-controller has just been upgraded.
In addition, it fixes a bug in which the controller would not properly label Custom Resource Definitions.
Fixes:
Improvements:
This prerelease addresses a regression in which the captured Helm logs used in a failure event would not include Helm's Kubernetes client logs, making
Release date: 2023-09-18
This prerelease addresses a regression in which the captured Helm logs used in a failure event would not include Helm's Kubernetes client logs, making it more difficult to reason about e.g. timeout errors.
In addition, it contains a fix for the default service account used for the (experimental) differ, and dependency updates of several dependencies.
Fixes:
DefaultServiceAccount in differ
#774Improvements:
This prerelease introduces a --interval-jitter-percentage flag to the controller to distribute the load more evenly when multiple objects are set up w
Release date: 2023-08-23
This prerelease introduces a --interval-jitter-percentage flag to the
controller to distribute the load more evenly when multiple objects are set up
with the same interval. The default of this flag is set to 5, which means
that the interval will be jittered by a +/- 5% random value (e.g. if the
interval is 10 minutes, the actual reconciliation interval will be between 9.5
and 10.5 minutes).
In addition, the controller now stops exporting an object's metrics as soon as it has been deleted.
Lastly, dependencies have been updated, such as an update of Helm to v3.12.3
and Kubernetes related dependencies to v0.27.4.
Improvements:
Fixes:
Nothing published for this version
Nothing published for this version
This prerelease adds support for configuring the deletion propagation policy to use when a Helm uninstall is performed using .spec.uninstall.deletionP
Release date: 2023-07-04
This prerelease adds support for configuring the deletion propagation policy to
use when a Helm uninstall is performed using .spec.uninstall.deletionPropagation,
which was added as a feature to Helm in v3.12.0.
Supported values are background, foreground and orphan (defaults to
background). See the Helm documentation
In addition, it offers support for Kubernetes v1.27.3 and includes updates to
the controller's dependencies, such as an upgrade of Helm to v3.12.1.
Starting with this version, the build, release and provenance portions of the Flux project supply chain provisionally meet SLSA Build Level 3.
Improvements:
Nothing published for this version
This prerelease fixes a regression bug for long-running reconciliations introduced in v0.34.0.
Release date: 2023-06-22
This prerelease fixes a regression bug for long-running reconciliations introduced in v0.34.0.
In addition, the controller release workflow was enhanced with SLSA level 3 generators. Starting with this version, provenance attestations are generated for the controller release assets and for the multi-arch container images.
Fixes:
Improvements:
Nothing published for this version
This prerelease comes with a bug fix for the event metadata revision, which was not included when a token was already present.
Release date: 2023-06-01
This prerelease comes with a bug fix for the event metadata revision, which was not included when a token was already present.
In addition, the source-controller dependency has been updated to v1.0.0-rc.5.
Fixes:
Improvements:
⚠️ Note that Kustomize v5 contains breaking changes, please consult their changelog for more details.
Release date: 2023-05-29
This prerelease comes with support for Helm 3.12.0 and Kustomize v5.0.3.
⚠️ Note that Kustomize v5 contains breaking changes, please consult their changelog for more details.
In addition, the controller dependencies have been updated to Kubernetes v1.27.2 and controller-runtime v0.15.0.
Lastly, the logic to forward events to notification-controller has been modified
to use .status.lastAttemptedValuesChecksum as an event metadata token to
prevent incorrect rate limiting.
Improvements:
In addition, the dependencies have been updated including a mitigation for CVE-2023-2253, and the controller base image has been updated to Alpine 3.1…
Release date: 2023-05-12
This prerelease comes with a change to the calculation of the release values checksum. Previously, the checksum was calculated based on the values as provided by the user, which could lead to an upgrade when the values changed order, but not content. This has been changed to calculate the checksum based on the values after stable sorting them by key. This means that the checksum will only change when the values actually change.
In addition, the dependencies have been updated including a mitigation for CVE-2023-2253, and the controller base image has been updated to Alpine 3.18.
Improvements:
This prerelease comes with a bug fix for a nil pointer deref that could occur when drift detection was enabled.
Release date: 2023-04-13
This prerelease comes with a bug fix for a nil pointer deref that could occur when drift detection was enabled.
In addition, it updates Helm to v3.11.3, which includes two fixes for Go
routine leaks.
Fixes:
This prerelease comes with a bug fix in HelmRelease related to the .spec.chart.metadata field which wasn't truly optional, leading to empty value assi
Release date: 2023-04-03
This prerelease comes with a bug fix in HelmRelease related to the
.spec.chart.metadata field which wasn't truly optional, leading to empty value
assignment even when it wasn't set.
Fixes:
This prerelease comes with a number of new features and improvements, and solves a long-standing issue with the patching of the HelmRelease status.
Release date: 2023-03-31
This prerelease comes with a number of new features and improvements, and solves a long-standing issue with the patching of the HelmRelease status.
The HelmRelease now supports the definition of a set of labels and annotations
using .spec.chart.metadata.labels and .spec.chart.metadata.annotations,
which will be applied to the HelmChart created by the controller.
The controller can now be configured with --watch-label-selector, after
which only HelmRelease objects with this label will be reconciled by the
controller.
This allows for horizontal scaling, where the controller can be deployed multiple times with a unique label selector which is used as the sharding key.
Note that if you want to ensure a HelmChart gets created for a specific
source-controller instance, you have to provide the labels for this controller
in .spec.chart.metadata.labels of the HelmRelease.
In addition, the source referenced (i.e. HelmRepository) in the HelmChart must be available to this same controller instance.
The HelmRelease now supports opting out of the persistent Kubernetes client
introduced in v0.31.0 by defining .spec.persistentClient: false (default
true).
This can be useful when a HelmRelease is used to manage a Helm chart that itself manages Custom Resource Definitions outside the Helm chart's CRD lifecycle (like OPA Gatekeeper), as the persistent client will not observe the creation of these resources.
Disabling this increases memory consumption, and should only be used when necessary.
The controller will now verify the Digest of the Artifact as advertised by
the HelmChart, introduced in source-controller v0.35.0.
Due to this, the controller will now require source-controller v0.35.0 or
higher (and ships with v1.0.0-rc.1 by default, which includes v1 of the
Artifact API).
Improvements:
controllers to internal/controllers
#653PersistentClient flag to allow control over Kubernetes client behavior
#659Fixes:
This prerelease extends the drift detection feature introduced in v0.31.0 with support for disabling the correction of drift using the CorrectDrift fe
Release date: 2023-03-20
This prerelease extends the drift detection feature introduced in v0.31.0
with support for disabling the correction of drift using the CorrectDrift
feature gate.
When disabled while DetectDrift is enabled (using --feature-gates=DetectDrift=true,CorrectDrift=false),
the controller will only emit events and log messages when drift is detected,
but will not attempt to correct it. This allows to transition to drift
detection and correction in a controlled manner.
In addition, the controller dependencies have been updated to their latest versions.
Fixes:
Improvements:
This prerelease extends the OOM watch feature introduced in v0.31.0 with support for automatic detection of cgroup v1 paths, and flags to configure al
Release date: 2023-03-10
This prerelease extends the OOM watch feature introduced in v0.31.0 with
support for automatic detection of cgroup v1 paths, and flags to configure
alternative paths using --oom-watch-max-memory-path and
--oom-watch-current-memory-path.
Fixes:
Nothing published for this version
This prerelease comes with a number of new features and improvements after a long period of non-substantial changes.
Release date: 2023-03-08
This prerelease comes with a number of new features and improvements after a long period of non-substantial changes.
The controller now supports experimental drift detection, which can be enabled
by configuring the Deployment with --feature-gates=DetectDrift=true. This
feature is still in its early stages, and lacks certain UX features. Diff
output is currently available in the controller logs when the --log-level=debug
flag is set.
The feature itself makes use of the same approach as kustomize-controller to detect drift using a dry-run Server Side Apply of the rendered manifests of a release. When drift is detected, the controller will emit an event and trigger a Helm upgrade.
When a specific object from a release causes spurious upgrades, it can be
excluded by annotating or labeling the object with
helm.toolkit.fluxcd.io/driftDetection: disabled. Refer to the drift detection
documentation
for more information.
When a SIGTERM signal is received by the controller, it will now propagate
this to any running Helm action, which will mark the release as failed. This
should prevent the controller from getting stuck in a pending state when
receiving a SIGTERM signal.
The controller can now be configured to detect when it is nearing an OOM kill.
This is enabled by configuring the Deployment with
--feature-gates=OOMWatch=true.
When enabled, the controller will monitor its memory usage as reported by
cgroups, and when it is nearing OOM, attempt to gracefully shutdown. Releases
that are currently being upgraded will be cancelled (resulting in a failed
release as opposed to a pending deadlock), and no new releases will be
started.
This is best combined with a thoughtful configuration of remediation strategies
on the HelmRelease resources, to ensure that the controller can recover from
the failed release.
To control the threshold at which the controller will attempt to shut down, use
the --oom-watch-memory-threshold (default 95) and --oom-watch-interval
(default 500ms) flags.
In a future release, we will add support for unlocking releases that are in a pending state as a different approach to handling OOM situations. But this is waiting for architectural changes to happen first.
We have made a number of improvements to the Kubernetes client used by the controller for Helm actions, which should reduce the memory usage of the controller and the number of API requests it makes when creating or replacing Custom Resource Definitions.
klog is now configured to log using the same logger as the rest of the
controller (providing a consistent log format).
In addition, the controller is now built with Go 1.20, and the dependencies have been updated.
Improvements:
logger.SetLogger to also configure klog
#633Nothing published for this version
This prerelease adds support for parsing the RFC-0005 revision format produced by source-controller >=v0.35.0.
Release date: 2023-02-17
This prerelease adds support for parsing the
RFC-0005
revision format produced by source-controller >=v0.35.0.
In addition, the controller dependencies have been updated to their latest
versions, including a security patch of Helm to v3.11.1.
Improvements:
Your coding agent can read these notes before it upgrades. Set up the MCP server →