Document Helm rendering behavior changes when upgrading to Argo CD 3.5
- Dominant language
- Go
- Stars
- 24.2k
- Forks
- 7.8k
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 233
Description
# Summary
Argo CD 3.5 switches to a newer Helm version with changed null/nil value coalescing behavior.
This can cause the exact same Helm chart and values to render different Kubernetes manifests after upgrading Argo CD from 3.4 to 3.5, even when neither the chart nor the user-provided values have changed.
I encountered this with the Loki Helm chart:
https://github.com/grafana-community/helm-charts/issues/716
With the Helm version used by current Argo CD 3.4, nullable chart defaults are omitted from the rendered manifest.
With Helm 4.2.0, used by Argo CD 3.5, the same values can result in explicit null fields being rendered instead.
For example, the same chart configuration can change from:
```
spec:
maxUnavailable: 1
```
to:
```
spec:
maxUnavailable: 1
minAvailable: null
unhealthyPodEvictionPolicy: null
```
without any change to the application source.
# Motivation
This is important for the Argo CD 3.5 upgrade path because Helm is not only an implementation detail of Argo CD: its rendering behavior directly determines the desired Kubernetes manifests.
An Argo CD upgrade can therefore introduce application manifest changes across existing Helm-based Applications solely because the bundled Helm version changed.
This has several consequences:
Applications that were previously synced can suddenly show diffs after upgrading Argo CD.
Previously valid chart rendering may become invalid or fail downstream schema/admission validation.
Users may attribute the changes to their Helm chart or values, although the actual trigger is the Argo CD upgrade.
The effect can potentially apply to many unrelated Helm charts because it originates from Helm value coalescing semantics rather than one specific chart.
Testing an application with the Helm version used by Argo CD 3.4 is not sufficient to predict how it will render after upgrading to Argo CD 3.5.
In my concrete case, the behavior differs depending on Helm version:
| Argo CD version | Bundled Helm version | `null` rendering behavior |
|---|---|---|
| Argo CD 3.4 | Helm 3.19.2 | `null` fields omitted |
| Argo CD 3.5 | Helm 4.2.0 | `null` fields preserved/rendered |
This means an Argo CD upgrade can effectively introduce a Helm rendering breaking change for existing Applications.
The underlying Helm behavior is related to changes in nil value coalescing, for example:
https://github.com/helm/helm/pull/31644
https://github.com/helm/helm/pull/13654
The Loki issue above is one concrete example, but the concern is broader than Loki itself.
# Proposal
Please document this explicitly as a potentially breaking change in the Argo CD 3.4 → 3.5 upgrade documentation.
The upgrade guide should mention that:
1. Argo CD 3.5 uses a different major Helm version and Helm's value coalescing behavior has changed.
2. Existing Helm Applications may render different manifests after the upgrade even when chart version and values stay unchanged.
3. Users should render/test their existing Helm Applications using the Helm version bundled with Argo CD 3.5 before upgrading production Argo CD instances.
4. Particular attention should be paid to charts that use explicit null values in their defaults or rely on null values being removed during Helm coalescing.
5. Users should review resulting Argo CD diffs carefully before rollout.
It may also be useful to provide a suggested pre-upgrade validation approach, for example rendering critical charts with Helm 4.2.0 and comparing those manifests with the output produced by the Helm version bundled with the currently installed Argo CD version.
The goal is not necessarily to change Argo CD's Helm version, but to make users aware that upgrading Argo CD 3.5 can change the rendered desired state of existing Helm Applications.
Contributor guide
Assessment
This issue has not been assessed yet.