Helm

Every platform team hits the same wall at roughly the same size. Somewhere between service number 20 and service number 60, the Helm charts stop being “a few YAML files” and become a system of their own: dozens of copies of the same Deployment template, three different ways of declaring a ServiceAccount, ingress annotations that drifted apart eighteen months ago, and nobody who can say with confidence which services still run the old securityContext. The question that follows is always framed the same way — should we centralize all charts in one repo, or let every team own theirs? — and it is the wrong question, because the two answers it allows are both bad at scale.

This article is about the third option, the one most mature organisations converge on whether they planned to or not: a versioned library chart that owns the opinions, thin per-service charts that own the intent, and an OCI registry as the single distribution channel. It compares that model honestly against the two pure ones, shows the code, and ends with a decision framework and a migration path for teams currently sitting on a central chart monorepo.

The Short Answer

If you have more than a handful of services and a platform team of any size, do this:

• Put the how — Deployment shape, probes, security context, labels, pod disruption budgets, ServiceMonitor, HPA defaults — in one library chart (type: library) that is semantically versioned and published to an OCI registry.
• Give each service a thin application chart that lives next to its code, declares the library chart as a dependency with a range like ~1.4.0, and contains almost nothing but values.yaml and a couple of one-line templates that include the library’s named templates.
• Publish every packaged chart to the same OCI registry you already use for images, and point Argo CD or Flux at that registry, not at Git.

Centralize the opinions, distribute the ownership, unify the distribution. Everything below is the reasoning and the mechanics.

Model 1: The Centralized Chart Repository

One repository — usually platform/helm-charts — holds every chart in the organisation, and the platform team reviews every change. It is the natural first move for a team that just watched three application squads implement ingress three different ways, and it fixes that problem quickly.

What it gets right is standardisation: one CI pipeline runs helm lint --strict, helm unittest and kubeconform on every chart; a single CODEOWNERS line puts the platform team on every PR; and when a new cluster policy lands, the people who wrote the policy also write the fix. Discovery is trivial (there is only one place to look) and shared subcharts are just directories.

What it gets wrong only shows up later, and it is structural rather than fixable with more process:

• The platform team becomes the deploy queue. Every values tweak an application team needs — a new env var, a sidecar, a memory bump — is a PR into a repo they do not own, reviewed by people who do not know the service. The review is either rubber-stamped (so why require it?) or slow (so teams route around it).
• The chart drifts from the code. A service’s deployment definition lives in a different repository from the service, versioned on a different cadence, with a different release process. A feature branch that needs a new ConfigMap key cannot be tested end to end without a cross-repo change.
• Blast radius is the whole org. A change to a shared helper that is used by 200 charts is a change to 200 services, and the monorepo makes that easy to do by accident — one _helpers.tpl edit, one merge, and every next deploy picks it up.

The centralised model optimises for the platform team’s control at the exact moment the organisation needs the platform team to stop being the bottleneck.

Model 2: One Chart Per Service

The mirror image: each service repository contains charts/<service>/, the team that owns the code owns the chart, and the platform team publishes guidance rather than reviewing changes.

This is what most teams want culturally, and for good reasons. The chart is versioned with the application, a feature branch can change the manifest and the code in one PR, a single pipeline builds the image and packages the chart, and a broken chart breaks one service. Ownership is unambiguous.

The failure mode is drift, and it is inevitable rather than hypothetical. Charts are created by copying the last one, so the organisation ends up with forty forks of the same Deployment template, each frozen at whatever the copied chart looked like that quarter. When the platform team needs seccompProfile: RuntimeDefault on every pod, or a new mandatory label for cost allocation, or a probe timeout change, the work is forty PRs into forty repositories owned by forty teams with forty different priorities. Quality is a function of each team’s Helm skill, which varies enormously. Security review has to happen at admission time (Kyverno, Gatekeeper) because it cannot happen at chart time.

Per-service charts optimise for team autonomy at the cost of any ability to change the platform at scale.

Side-by-Side

The third column is the rest of this article.

Model 3: A Library Chart Plus Thin Per-Service Charts

Helm has had a first-class mechanism for exactly this split since Helm 3: the library chart. A chart with type: library in its Chart.yaml cannot be installed and renders no manifests of its own; it exists only to be pulled in as a dependency so other charts can include its named templates. Unlike a regular subchart, a library chart’s templates run with the parent’s .Values and .Files, which is what makes it usable as a template engine rather than as a bundled application.

The platform team publishes one such chart — call it mycompany/common — and it owns every opinion the organisation has about how a workload should look on its clusters. A service chart then becomes remarkably small.

Chart.yaml of a service:

apiVersion: v2
name: payments-api
description: Payments API
type: application
version: 3.12.0
appVersion: "2026.09.1"
dependencies:
  - name: common
    version: "~1.4.0"
    repository: "oci://registry.mycompany.io/charts"

templates/deployment.yaml of that service:

{{- include "common.deployment" . }}

templates/service.yaml, templates/hpa.yaml, templates/servicemonitor.yaml are each a single include line as well. The service’s values.yaml is where the team spends its time:

image:
  repository: registry.mycompany.io/payments/api
  tag: "2026.09.1"
replicas: 3
resources:
  requests: { cpu: 250m, memory: 512Mi }
  limits:   { memory: 512Mi }
env:
  PAYMENT_PROVIDER: stripe
ingress:
  host: payments.internal.mycompany.io

Inside the library, common.deployment is a named template that renders the Deployment with the security context, labels, probes and topology spread the platform team decided on, reading only the values the service exposes. The Helm docs’ pattern for this is a two-step merge — a _tpl template holding the defaults and a wrapper that merges the caller’s overrides on top — so a team that genuinely needs a non-standard field can set it in values without forking the template:

{{- define "common.deployment.tpl" -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "common.fullname" . }}
  labels: {{- include "common.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicas | default 2 }}
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        seccompProfile: { type: RuntimeDefault }
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
{{- end }}

{{- define "common.deployment.overrides" -}}
{{- /* empty by default; a service redefines this template to override fields */ -}}
{{- end }}

{{- define "common.deployment" -}}
{{- include "common.util.merge" (list . "common.deployment.overrides" "common.deployment.tpl") }}
{{- end }}

Template names are global in Helm and the parent chart’s templates are loaded after its dependencies, so a service that needs, say, a custom terminationGracePeriodSeconds redefines common.deployment.overrides in its own _helpers.tpl with just that fragment, and the merge lays it over the platform default. Services that need nothing leave it alone.

Two things fall out of this structure that neither pure model can offer.

Standard changes become a release, not a campaign. When the platform team needs every pod to carry a new cost-allocation label, they change one template, cut common 1.5.0, and every service picks it up on its next dependency bump. No forty PRs, no hunting through forks.

Breaking changes are contained by semver. If the platform team has to rename a value or drop a field, that is common 2.0.0, and no service declaring ~1.4.0 will ever pull it by accident. Teams migrate on their own schedule, and the platform team can support 1.x with patch releases while they do. The constraint syntax is doing real governance work here: ~1.4.0 allows 1.4.x patches only, ^1.4.0 allows any 1.x including new features, and a hard pin allows nothing — see Helm version constraints explained for the exact bounds of each operator and the 0.x caret trap that catches library charts still on a 0. major. The mechanics of Chart.lock and helm dependency update are covered in Helm dependencies.

Versioning the library honestly

The library chart is the one artifact in this model whose version number carries organisational weight, so be strict with it:

• Patch (1.4.3): a template fix that renders identically for every existing consumer, or a change to a default that no service could observe.
• Minor (1.5.0): a new optional value, a new named template, a new default that services can opt out of.
• Major (2.0.0): any renamed or removed value, any rendered output change that a consumer could not have opted out of, any change to the merge contract.

If you are not sure whether a change is minor or major, it is major. The cost of an unnecessary major is a version bump PR; the cost of a wrong minor is a fleet-wide surprise at deploy time.

Distribution: OCI Is the Default Now

Where charts are developed and where they are published are separate decisions, and conflating them is how teams end up serving index.yaml from a Git branch or a ChartMuseum nobody wants to run.

Since Helm 3.8 the oci:// scheme has been stable, and it is the right answer for almost everyone: charts go into the same registry as images (Harbor, ECR, ACR, GHCR, Artifact Registry), with the same authentication, replication, retention and vulnerability-scanning pipeline already in place. The classic HTTP repository with its regenerated index.yaml still works, but it is a second piece of infrastructure to run, its index can go stale relative to the packages, and it has no notion of immutable digests. New projects should not start there.

Publishing is two commands:

helm package charts/common          # → common-1.5.0.tgz
helm push common-1.5.0.tgz oci://registry.mycompany.io/charts

Note that helm push takes the namespace only — the chart name and tag are taken from Chart.yaml. Consumers reference it in dependencies: exactly as in the payments-api example above, and can install or template it directly:

helm install payments oci://registry.mycompany.io/charts/payments-api --version 3.12.0
# or pinned by digest for supply-chain guarantees
helm install payments oci://registry.mycompany.io/charts/payments-api@sha256:9f2c...

Helm 4 (released November 2025) does not change the OCI story — the commands and the oci:// dependency syntax are unchanged — but two of its features are relevant to chart management at scale. Reproducible chart archives mean helm package on the same tree produces the same bytes, which makes “has this chart actually changed?” answerable in CI. And content-addressed local caching of charts makes a pipeline that resolves a library dependency for 200 services materially cheaper. Neither is a reason to migrate on its own; both are nice once you are there.

Governance Without a Bottleneck

The library model moves the platform team’s review effort to where it has leverage: the library itself, and the CI templates every service runs.

On the library chart, be paranoid. It is the only chart whose bugs ship to everyone:

• helm lint --strict and helm unittest against a matrix of representative consumer values — the library has no values of its own, so tests must exercise it through a fixture chart.
• Render the fixture with helm template and validate with kubeconform against every Kubernetes minor you run.
• Ship a values.schema.json for the values the library expects consumers to provide, so a typo in a service’s values.yaml fails at helm install rather than at runtime; the pattern and its limits are in Helm values schema validation.
• CODEOWNERS on the library repo puts the platform team on every change. That is the one place where central review is worth the latency.

On service charts, keep the gate light and automated: a shared CI template that runs lint, helm template | kubeconform, and a diff against the currently deployed release. Helm chart testing best practices covers the tooling; the point here is that the service team owns the pipeline run and the platform team owns the pipeline template.

For fleet-wide changes, the mechanism is dependency automation, not PR campaigns. Renovate and Dependabot both understand Helm Chart.yaml dependencies, including oci:// repositories. Configure them to open a PR on every service repo whenever common cuts a release within the service’s declared range, with auto-merge for patch versions if the CI gate passes. A platform change then becomes: cut common 1.5.0, watch the bots do the rounds, chase the handful of repos whose CI failed. That is the difference between a two-day change and a two-quarter one.

Admission policy still belongs in the cluster. Kyverno or Gatekeeper is the safety net for the chart a team wrote without the library, or the Deployment somebody applied by hand. The library makes compliance the default; the admission controller makes non-compliance impossible. You want both.

How It Fits GitOps

Argo CD and Flux both consume charts from OCI registries directly, which is what makes the “publish everything to the registry” rule pay off — the GitOps repository holds which version of which chart with which values, not the chart source.

With Flux, the service’s HelmRelease points at an OCIRepository (or a HelmRepository with type: oci):

apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
  name: payments-api
  namespace: payments
spec:
  interval: 10m
  url: oci://registry.mycompany.io/charts/payments-api
  ref:
    semver: "~3.12.0"
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
  name: payments-api
  namespace: payments
spec:
  interval: 10m
  chartRef:
    kind: OCIRepository
    name: payments-api
  values:
    replicas: 5

Argo CD’s equivalent is an Application whose source.repoURL is the registry (no oci:// prefix in Argo’s case, and the repo must be registered with enableOCI: true) and whose source.chart and targetRevision select the chart and version.

Now separate the two decisions that are usually mashed together:

• *Where chart source lives* — monorepo or per-service repo — is a question about ownership and review, answered above: library in the platform repo, service charts next to the service.
• *Where charts are published*** is a question about distribution, and the answer is always “the one OCI registry”, regardless of where the source came from.

Teams that skip the publishing step and point Argo CD at chart directories in Git get a system where the deployed artifact has no version, no digest and no scan, and where “what is running in production?” is answered by a commit SHA in a repo that also contains the source of forty other charts. Publish the chart. It is one CI step.

Decision Framework

How many services deploy with Helm?
│
├── < 10, one team, no platform function
│   └── Per-service charts. Copy a good template, revisit at 15+.
│
├── 10–40, a platform team exists or is forming
│   ├── Is drift already hurting (security context, labels, probes)?
│   │   ├── YES → Library chart now; migrate the worst offenders first.
│   │   └── NO  → Per-service charts + a shared CI template; start the library
│   │             when the third team copies the second team's chart.
│   └── Never a central chart repo: it is a bottleneck at this size and
│       a migration at the next one.
│
├── 40+, multiple product teams
│   └── Library chart + thin service charts + OCI + Renovate. Not optional.
│       A central chart repo here is the platform team's entire backlog.
│
└── Regulated, or platform team must approve every deployment change
    └── Library chart with a strict values.schema.json + admission policy.
        Approval happens on the library and the policy, not on 200 PRs.

Migrating away from a central chart repo

Most teams reading this already have the monorepo. Do not big-bang it.

1. Extract the library first. Pull the shared _helpers.tpl and the most common Deployment shape into common 0.1.0 and publish it to the registry. Nothing consumes it yet.
2. Convert charts in the monorepo to consume the library — still in the monorepo. This is where you discover the forty subtle differences between “the same” Deployment templates. Each one is a decision: a library value, or a documented exception.
3. Cut common 1.0.0 once the converted charts render identically to what is deployed. helm template diffs against the live release are the acceptance test.
4. Move charts to their service repos one team at a time, in the order of who asks first. The chart is now three include lines and a values.yaml, so the move is small and the team is getting something (ownership) rather than being handed a chore.
5. Turn on Renovate for common across the moved repos, and leave the monorepo to shrink until it only contains the library and whatever genuinely shared subcharts remain.

Expect steps 2 and 3 to take most of the time. That is not migration overhead; it is the accumulated drift finally being paid down.

Frequently Asked Questions

Conclusion

The centralized-versus-per-service framing offers a choice between a platform team that cannot keep up and a fleet that cannot be changed. Neither is the destination. The model that scales puts the organisation’s opinions in one versioned library chart, gives each service a thin chart it genuinely owns, and publishes everything through the OCI registry it already runs. It is more work to set up than either pure model, and every large Helm estate ends up there anyway — the only question is whether you arrive by design or by migration.

If you have ever written a chart dependency as version: ~1.2.3 and wondered exactly which versions that will and will not pull in — or been surprised when ^0.2.3 refused to upgrade to 0.3.0 — you have run into Helm’s version constraint syntax. It is one of those features everybody uses and almost nobody reads the spec for, which is precisely why it bites.

Helm lets you pin chart versions with a small algebra of range operators: the tilde ~, the caret ^, wildcards (x, *), hyphen ranges, and boolean combinators. Get them right and your helm dependency update pulls exactly the patch releases you want and nothing that breaks you. Get them wrong and you either freeze on a stale sub-chart forever or let a breaking major slip into production.

This guide covers every operator with its exact bounds, the real-world use case for each, the two traps that catch most people (the 0.x caret behavior and silently-skipped pre-releases), and where these constraints are actually evaluated — not just in Chart.yaml dependencies, but on the helm install --version flag too. Everything here reflects current Helm 3 (and is unchanged in Helm 4).

The 30-Second Cheat Sheet

Before the details, here is every operator with its exact expansion. Pin this table.

The rest of this article is each of these in depth, with the use case and the gotchas.

Where Helm Actually Uses These Constraints

Before the operators, know the two places this syntax is evaluated — they behave identically because they call the same parser:

1. Chart.yaml dependencies

Each entry under dependencies has a version field that “should contain a semantic version or version range”:

apiVersion: v2
name: my-app
version: 1.0.0
dependencies:
  - name: postgresql
    version: "~15.5.0"
    repository: "https://charts.bitnami.com/bitnami"
  - name: redis
    version: "^20.0.0"
    repository: "https://charts.bitnami.com/bitnami"

2. The --version flag

The --version flag on helm install, upgrade, pull, template and friends. Straight from the CLI docs: “This constraint can be a specific tag (e.g. 1.1.1) or it may reference a valid range (e.g. ^2.0.0). If this is not specified, the latest version is used.”

# Latest patch of 15.5
helm install db bitnami/postgresql --version "~15.5.0"

# Any 20.x, resolved at install time
helm upgrade cache bitnami/redis --version "^20.0.0"

Under the hood, Helm 3 parses all of this with the Masterminds/semver v3 Go library (the same one Helm 4 ships). Every rule below comes from that library’s behavior, so it is consistent everywhere Helm accepts a version.

The Tilde ~: Patch Updates Only

The tilde is the conservative choice: allow patch releases, freeze the minor. It is the operator you want for a dependency you trust to follow SemVer but don’t want surprising you with new features (and new bugs) on a minor bump.

The rule: with a minor version specified, ~ allows patch-level changes; with only the major specified, it allows minor-level changes.

Use case: a stateful dependency like a database chart where minor bumps can change StatefulSet fields, default storage, or init logic. version: "~15.5.0" says “give me 15.5.4, 15.5.9 — the bug fixes — but never jump me to 15.6 automatically.” This is the pattern Helm’s own dependencies best-practices page recommends as the default: version: ~1.2.3.

The Caret ^: Minor + Patch (and the 0.x Trap)

The caret is the “trust SemVer” operator: allow anything that shouldn’t break you — new minors and patches, but not a new major. For a well-behaved dependency past 1.0.0, this is the sweet spot between staying current and staying safe.

Use case: a mature library chart (an ingress controller, a metrics exporter) that reliably reserves breaking changes for major bumps. version: "^20.0.0" keeps you on the latest 20.x without manual bumps, and stops cold at 21.0.0 so a breaking change never lands silently.

⚠️ The 0.x Caret Trap

Here is the single most misremembered rule in the whole system. Before a 1.0.0 release, the caret treats the minor number as the stability level, because in 0.x land every minor bump is allowed to break things. So:

If you write ^0.2.3 expecting it to track every 0.x release up to 1.0.0, you will be quietly stuck on the 0.2 line — 0.3.0 will never be pulled. On a 0.x dependency, caret behaves essentially like tilde. Given how many CNCF-adjacent charts sit at 0.x for years, this is a real-world footgun, not a trivia question. If you genuinely want to float across 0.x minors, use an explicit range: >= 0.2.3, < 1.0.0.

Wildcards: x, X and *

Wildcards let you leave a position open. They work with the comparison operators too, and on a bare = they fall back to tilde-style patch matching.

Use case: 1.2.x reads more explicitly than ~1.2.0 to some teams and means the same thing — pick whichever your reviewers parse faster. A bare * matches everything and should be treated as a code smell in a committed Chart.yaml; it defeats the entire point of a lock and invites a breaking major on the next helm dependency update.

Hyphen Ranges: Inclusive Both Ends

A hyphen range gives you an explicit, inclusive window on both ends — handy when you know a dependency is good from version A through version B and you want to say exactly that.

⚠️ The whitespace matters. The spaces around the hyphen are mandatory. Written without them, 1.2.3-1.4.5 is not a range at all — it parses as the single version 1.2.3 with the pre-release identifier 1.4.5. That is a completely different (and almost certainly unintended) constraint, and it will fail to match silently. Always keep the spaces: 1.2.3 - 1.4.5.

Boolean Logic: AND, OR and Comparisons

You can combine constraints. Within a group, space and comma both mean AND — they are interchangeable. Groups are then joined with || for OR.

# AND — a bounded window
version: ">= 1.2.0, < 1.5.0"

# equivalent (space instead of comma)
version: ">= 1.2.0 < 1.5.0"

# OR — support two major lines at once
version: "^1.0.0 || ^2.0.0"

# real-world: pin a window but exclude one bad release
version: ">= 1.2.0, < 2.0.0, != 1.4.2"

The full set of comparison operators is what you’d expect: =, !=, >, <, >=, <=. The != is underused and genuinely handy — when a specific patch ships a regression, != 1.4.2 skips exactly that one without abandoning your range.

Use case for ||: a chart that supports two major versions of a dependency during a migration window. ^1.0.0 || ^2.0.0 accepts either line, letting downstream users move at their own pace.

The Pre-Release Gotcha Nobody Reads

This one silently breaks CI pipelines. Ranges skip pre-release versions by default. A constraint like ~1.2.3 or >= 1.2.0 will not match 1.3.0-rc.1 or 1.2.5-beta.2, even though those versions are numerically inside the range.

The reason is deliberate: you rarely want a helm dependency update to pull a release candidate into a production chart. But it surprises people who tag pre-releases and wonder why Helm ignores them.

To opt in, add a pre-release comparator to the constraint itself — the idiomatic trick is appending -0:

# Ignores 1.2.4-rc.1 (default behavior)
version: "~1.2.3"

# Matches pre-releases too, e.g. 1.2.4-rc.1
version: "~1.2.3-0"

The -0 works because pre-release identifiers sort in ASCII order and 0 is the lowest possible, so it acts as “any pre-release or higher.” One more sharp edge from the same rule: comparisons are ASCII-cased, so >= 1.2.3-BETA will match 1.2.3-alpha, because uppercase B sorts before lowercase a. If you use pre-release channels, keep the casing consistent.

Chart.yaml Range vs Chart.lock Pin: What Actually Reproduces a Build

A constraint is a range, not a pin — and understanding the difference between Chart.yaml and Chart.lock is what separates reproducible builds from “works on my machine.”

• Chart.yaml holds the range (~15.5.0). It expresses intent: “acceptable versions.”
• Chart.lock holds the resolved, concrete versions plus a digest. It is generated, and it is what actually reproduces a build.

The two commands that interact with them do opposite things:

# Re-resolves the RANGE in Chart.yaml against the repo,
# picks concrete versions, and rewrites Chart.lock.
helm dependency update

# Ignores the range; rebuilds charts/ from the PIN in Chart.lock.
helm dependency build

The practical rule: commit your Chart.lock. In CI, use helm dependency build so every pipeline run installs the exact versions the lock pins — the range in Chart.yaml only governs re-resolution when you deliberately run update. Treating the range as if it were the pin is how teams end up with subtly different sub-chart versions across environments. If you’re formalizing chart quality more broadly, this pairs well with a proper chart testing setup.

Since Which Helm Version?

Two things people conflate here — the syntax and the location:

• The constraint syntax itself is not new. Helm 2 already parsed the same Masterminds/semver ranges; it just kept dependencies in a separate requirements.yaml file.
• What changed in Helm 3 is where dependencies live. With apiVersion: v2 charts (the Helm 3 format, released November 2019), dependencies moved into Chart.yaml. Helm’s docs are explicit: the change from v1 to v2 “added a dependencies field defining chart dependencies, which were located in a separate requirements.yaml file for v1 charts.”

So if you are on any modern Helm (3.x or the new Helm 4), the full operator set in this article is available in your Chart.yaml and on --version. If you still maintain an ancient apiVersion: v1 chart, the same operators work — they just live in requirements.yaml. Set apiVersion: v2 and move the block into Chart.yaml when you migrate.

Which Operator Should You Use? A Decision Guide

The honest default for most teams: use ~ (tilde) for stateful and infrastructure-critical dependencies where you want bug fixes and nothing else, use ^ (caret) for mature libraries you trust to respect SemVer, and always commit Chart.lock so the range never decides what actually deploys — the lock does.

Frequently Asked Questions

Wrapping Up

Helm’s version constraints are a small language, but the two traps — caret pinning the minor on 0.x, and ranges silently skipping pre-releases — cause an outsized share of “why won’t it upgrade?” and “why did that break?” incidents. Internalize the cheat-sheet table, prefer ~ and ^ over bare wildcards, and let Chart.lock be the source of truth for reproducible builds.

For more on getting Helm right in production, see the companion guides on Helm values JSON schema validation, loading external files into ConfigMaps and Secrets, and what’s new in Helm 4.

Sources

• Masterminds/semver — checking version constraints
• Helm docs — chart dependencies best practices
• Helm docs — charts (apiVersion v2, requirements.yaml → Chart.yaml)
• Helm docs — helm dependency (Chart.lock, build vs update)
• Helm docs — helm install --version range support

You override a chart’s default livenessProbe with an exec command, deploy, and Kubernetes rejects it: “may not specify more than one handler type.” The chart’s default httpGet probe is still there, merged underneath your override, and now the pod spec has two probe handlers. You didn’t add it. You can’t see it in your values file. And the fix is a single character: ~.

That ~ is YAML’s null, and in Helm it does something most people never learn: setting a key to null deletes it from the merged values entirely, instead of setting it to a null value. It’s the cleanest way to remove a default a chart baked in — and it’s the tip of a whole set of null-handling behaviors (absent vs null vs empty, --set foo=null, default, required, hasKey) that quietly decide whether your templates render valid YAML or foo: <no value>.

This guide covers the null-deletes-a-key trick in depth, where it works and where it bites (the --reuse-values trap, the Helm 4 regression), and the related functions you need to tell “the user didn’t set this” apart from “the user set this to empty.” Everything is verified against current Helm docs and behavior.

First: ~ is just YAML null

Before Helm, this is pure YAML. All of these mean the same thing — null:

a: ~        # canonical shorthand
b: null
c: Null
d: NULL
e:          # empty value is also null

~ is the canonical short form in the YAML spec; null/Null/NULL/empty are equivalent spellings. In a Helm values.yaml, writing foo: ~ is identical to foo: null. People reach for ~ because it’s terse and unmistakable — an empty value (foo:) is easy to misread as “I forgot to fill this in,” whereas foo: ~ reads as a deliberate null.

The Killer Trick: null Deletes a Default Key

Here is the behavior that makes ~ worth an article. When you override a chart’s values — with a -f values file, a parent chart overriding a subchart, or --set — Helm merges your values on top of the chart’s defaults. A normal override replaces a value. But a null override is special: Helm removes the key from the result.

Straight from the Helm docs (Chart Template Guide → Values Files):

“If you need to delete a key from the default values, you may override the value of the key to be null, in which case Helm will remove the key from the overridden values merge.”

The canonical example is the liveness-probe foot-gun from the intro. Say the chart defaults to:

# chart's values.yaml
livenessProbe:
  httpGet:
    path: /healthz
    port: 8080

You want an exec probe instead. If you just add your exec, the merge keeps the default httpGet — and a probe with both exec and httpGet is invalid. You delete the default with null:

# your override values.yaml
livenessProbe:
  httpGet: ~          # ← deletes the chart's default httpGet
  exec:
    command: [cat, docroot/CHANGELOG.txt]

Or on the command line, exactly as the Helm docs show it:

helm install stable/drupal \
  --set livenessProbe.exec.command='{cat,docroot/CHANGELOG.txt}' \
  --set livenessProbe.httpGet=null

The result has only the exec handler. Without the httpGet=null, both survive and Kubernetes rejects the manifest.

Why it works: Helm’s value coalescing walks the override tree onto the defaults. A present key with a real value overwrites; a present key with null is treated as an instruction to remove. This is the only way to subtract from a chart’s defaults — there’s no --unset flag (more on that below).

Where the null-delete works

The same mechanism applies anywhere Helm coalesces values:

• A -f override file on top of the chart’s values.yaml (the docs example above).
• A parent chart overriding a subchart. In the parent’s values.yaml, nulling a key under the subchart’s name deletes that subchart default:
• “`yaml
• # parent values.yaml
• mysubchart:
• someDefault: ~ # remove a default the subchart shipped
• “`
• --set key=null at install/upgrade time.

--set foo=null vs --set-string foo=null

On the CLI the distinction matters, and it’s a common source of “why didn’t it delete?”:

Helm’s --set parser does type conversion: the literal null (case-insensitive) is converted to a Go nil, which triggers the delete. --set-string forces everything to stay a string, so null is just the four-character word "null" — which is almost never what you want here. If your deletion isn’t happening, check you didn’t reach for --set-string.

Version Support (and the Helm 4 warning)

This is where “desde qué versión” gets interesting:

• Helm 2 introduced deleting a key by setting it to null, but only reliably for top-level keys. Nested null-deletion (like web.livenessProbe.httpGet: null) was buggy — it could emit Cannot overwrite table item ... with non table value and override with null instead of deleting.
• Helm 3 is where the documented behavior works as advertised, top-level and nested. If you’re on Helm 3, everything above is solid.
• ⚠️ Helm 4 — currently a regression. As of a still-open issue (filed March 2026), Helm 4 no longer reliably deletes keys via null: both foo: (blank) and foo: null can fail schema validation with errors like Invalid value: "null": ... must be of type string, especially against strict Kubernetes 1.34+ schemas. If you’ve moved to Helm 4, test null-deletion before relying on it — the behavior that was rock-solid in Helm 3 is in flux. This interacts directly with values JSON schema validation: a schema that types a field as string will reject a null, so schema and null-deletion can fight each other.

The --reuse-values Trap

The one place null-deletion does not do what you’d hope: helm upgrade --reuse-values.

--set foo=null deletes a key relative to the chart’s defaults. It does not cleanly “un-set” a value you previously set explicitly and are now carrying forward with --reuse-values — it overrides it with null rather than falling back to the chart default. There is a long-standing feature request for an explicit --unset flag precisely because this case has no clean answer today.

Practical rule: to genuinely reset a value back to the chart default on upgrade, prefer re-specifying your full intended values (-f) over leaning on --reuse-values plus --set x=null.

Absent vs null vs empty: The Trio That Trips Everyone

Deleting keys is half the story. The other half is reading optional values in templates — and Helm/Sprig blur three states that feel different: key absent, key present but null, and key present but empty (0, "", [], {}, false).

The critical thing to internalize: default, required, empty, and coalesce all treat nil, 0, "", empty list/map, and false as the same “empty.” They cannot tell “unset” from “set to zero.”

replicas: 0        # a DELIBERATE zero...
```
```gotemplate
{{ .Values.replicas | default 3 }}   # ...renders 3, not 0 — surprise!

Here’s what each tool actually does:

If you need to honor a deliberate 0 or false, default is wrong — use hasKey to check presence explicitly:

replicas: {{ if hasKey .Values "replicas" }}{{ .Values.replicas }}{{ else }}3{{ end }}

The Rendering Foot-gun: <no value> vs null vs ""

The nastiest null bug isn’t logic — it’s a null leaking into your YAML as a broken string. The same nil value renders three different ways:

foo: {{ .Values.foo }}            # → foo: <no value>   ❌ invalid YAML-ish garbage
foo: {{ .Values.foo | toYaml }}   # → foo: null         ✅ valid YAML null
foo: {{ .Values.foo | quote }}    # → foo: ""           ✅ valid empty string

Bare-printing an unset value gives you the literal text <no value> in the manifest — which is not null, not empty, just a string that will confuse Kubernetes or your reader. (You may also see <nil> in some contexts; the exact literal is a Go-template detail that has shifted across Helm 3 minor versions, so don’t hard-code assumptions about which one appears — the point is it’s not what you want.)

The fixes:

• Piping through toYaml turns nil into a proper null — use it for whole objects/maps: {{ .Values.config | toYaml | nindent 2 }}.
• Piping through quote turns nil into "" — use it for optional scalars that must be strings.
• Best of all, skip the key entirely when empty with with:
• “`gotemplate
• {{- with .Values.foo }}
• foo: {{ . | quote }}
• {{- end }}
• “`
• The with block is skipped for any empty/nil value, so an unset foo produces no line at all — the idiomatic Helm “omitempty.”

Switching Off a Subchart Block with null

One more practical use of ~. Because nil is “empty,” setting a value to null makes an {{ if }} guard fall through:

# subchart default turns something on
metrics:
  serviceMonitor:
    enabled: true
```
```yaml
# parent override switches it off cleanly
metrics:
  serviceMonitor: ~     # or: enabled: false

Nulling the whole block (or the flag) makes {{ if .Values.metrics.serviceMonitor }} evaluate false — a tidy way for a parent chart or an environment override to disable a section a subchart enabled by default, using the same empty-semantics as everything above.

Cheat Sheet

Wrapping Up

~ in Helm is a two-job character: it writes a YAML null, and — the part almost nobody documents in their own charts — it deletes a default key from the merged values, which is the only clean way to subtract a probe, an annotation, or a whole block that a chart shipped by default. Around it sits a set of null rules worth memorizing: default/required/empty can’t tell unset from zero (use hasKey when that matters), and an unset value bare-printed becomes <no value> unless you route it through toYaml, quote, or with.

Two warnings to carry: --reuse-values doesn’t cleanly un-set values, and Helm 4’s null-deletion is currently a regression — so if you’re on 4.x, verify before you rely on it.

For more Helm depth, see the companion guides on values JSON schema validation (which interacts directly with null handling), loading external files into ConfigMaps and Secrets, and what’s new in Helm 4.

Sources

• Helm docs — Values Files (“Deleting a default key”)
• Helm docs — Using Helm (--set format and limitations)
• Helm docs — Template Function List (default, required, coalesce, ternary, dig, hasKey)
• Sprig — default / empty / coalesce
• YAML null spec
• Helm 4 null-handling regression (issue #31943)
• Feature request: --unset for --reuse-values (issue #12307)

Helm is one of the main utilities within the Kubernetes ecosystem, and therefore the release of a new major version, such as Helm 4.0, is something to consider because it is undoubtedly something that will need to be analyzed, evaluated, and managed in the coming months.

Related reading: Helm version constraints explained.

Related reading: Helm hooks: lifecycle, weights and deletion policies.

Helm 4.0 represents a major milestone in Kubernetes package management. For a complete understanding of Helm from basics to advanced features, explore our .

Due to this, we will see many comments and articles around this topic, so we will try to shed some light.

Helm 4.0 Key Features and Improvements

According to the project itself in its announcement, Helm 4 introduces three major blocks of changes: new plugin system, better integration with Kubernetes ** and internal modernization of SDK and performance**.

New Plugin System (includes WebAssembly)

The plugin system has been completely redesigned, with a special focus on security through the introduction of a new WebAssembly runtime that, while optional, is recommended as it runs in a “sandbox” mode that offers limits and guarantees from a security perspective.

In any case, there is no need to worry excessively, as the “classic” plugins continue to work, but the message is clear: for security and extensibility, the direction is Wasm.

Server-Side Apply and Better Integration with Other Controllers

From this version, Helm 4 supports Server-Side Apply (SSA) through the --server-side flag, which has already become stable since Kubernetes version v1.22 and allows updates on objects to be handled server-side to avoid conflicts between different controllers managing the same resources.

It also incorporates integration with kstatus to ensure the state of a component in a more reliable way than what currently happens with the use of the --wait parameter.

Other Additional Improvements

Additionally, there is another list of improvements that, while of lesser scope, are important qualitative leaps, such as the following:

• Installation by digest in OCI registries: (helm install myapp oci://...@sha256:<digest>)
• Multi-document values: you can pass multiple YAML values in a single multi-doc file, facilitating complex environments/overlays.
• New --set-json argument that allows for easily passing complex structures compared to the current solution using the --set parameter

Why a Major (v4) and Not Another Minor of 3.x?

As explained in the official release post, there were features that the team could not introduce in v3 without breaking public SDK APIs and internal architecture:

• Strong change in the plugin system (WebAssembly, new types, deep integration with the core).
• Restructuring of Go packages and establishment of a stable SDK at helm.sh/helm/v4, code-incompatible with v3.
• Introduction and future evolution of Charts v3, which require the SDK to support multiple versions of chart APIs.

With all this, continuing in the 3.x branch would have violated SemVer: the major number change is basically “paying” the accumulated technical debt to be able to move forward.

Additionally, a new evolution of the charts is expected in the future, moving from v2 to a future v3 that is not yet fully defined, and currently, v2 charts run correctly in this new version.

Is Helm 4.0 Migration Required?

The short answer is: yes. And possibly the long answer is: yes, and quickly. In the official Helm 4 announcement, they specify the support schedule for Helm 3:

• Helm 3 bug fixes until July 8, 2026.
• Helm 3 security fixes until November 11, 2026.
• No new features will be backported to Helm 3 during this period; only Kubernetes client libraries will be updated to support new K8s versions.

Practical translation:

• Organizations have approximately 1 year to plan a smooth Helm 4.0 migration with continued bug support for Helm 3.
• After November 2026, continuing to use Helm 3 will become increasingly risky from a security and compatibility standpoint.

Best Practices for Migration

To carry out the migration, it is important to remember that it is perfectly possible and feasible to have both versions installed on the same machine or agent, so a “gradual” migration can be done to ensure that the end of support for version v3 is reached with everything migrated correctly, and for that, the following steps are recommended:

• Conduct an analysis of all Helm commands and usage from the perspective of integration pipelines, upgrade scripts, or even the import of Helm client libraries in Helm-based developments.
• Especially carefully review all uses of --post-renderer, helm registry login, --atomic, --force.
• After the analysis, start testing Helm 4 first in non-production environments, reusing the same charts and values, reverting to Helm 3 if a problem is detected until it is resolved.
• If you have critical plugins, explicitly test them with Helm 4 before making the global change.

Frequently Asked Questions

Helm has long been the standard for managing Kubernetes applications using packaged charts, bringing a level of reproducibility and automation to the deployment process. However, some operational tasks, such as renaming a release or migrating objects between charts, have traditionally required cumbersome workarounds. With the introduction of the --take-ownership flag in Helm v3.17 (released in January 2025), a long-standing pain point is finally addressed—at least partially.

Related reading: Helm dependencies: condition, alias and version rules.

The take-ownership feature represents the continuing evolution of Helm. Learn about this and other cutting-edge capabilities in our Helm Charts Package Management Guide

In this post, we will explore:

• What the --take-ownership flag does
• Why it was needed
• The caveats and limitations
• Real-world use cases where it helps
• When not to use it
  

Understanding Helm Release Ownership and Object Management

When Helm installs or upgrades a chart, it injects metadata—labels and annotations—into every managed Kubernetes object. These include:

app.kubernetes.io/managed-by: Helm
meta.helm.sh/release-name: my-release
meta.helm.sh/release-namespace: default

This metadata serves an important role: Helm uses it to track and manage resources associated with each release. As a safeguard, Helm does not allow another release to modify objects it does not own and when you trying that you will see messages like the one below:

Error: Unable to continue with install: Service "provisioner-agent" in namespace "test-my-ns" exists and cannot be imported into the current release: invalid ownership metadata; annotation validation error: key "meta.helm.sh/release-name" must equal "dp-core-infrastructure11": current value is "dp-core-infrastructure"

While this protects users from accidental overwrites, it creates limitations for advanced use cases.

Why --take-ownership Was Needed

Let’s say you want to:

• Rename an existing Helm release from api-v1 to api.
• Move a ConfigMap or Service from one chart to another.
• Rebuild state during GitOps reconciliation when previous Helm metadata has drifted.
  

Previously, your only option was to:

1. Uninstall the existing release.
2. Reinstall under the new name.
   

This approach introduces downtime, and in production systems, that’s often not acceptable.

What the Flag Does

helm upgrade my-release ./my-chart --take-ownership

When this flag is passed, Helm will:

• Skip the ownership validation for existing objects.
• Override the labels and annotations to associate the object with the current release.
  

In practice, this allows you to claim ownership of resources that previously belonged to another release, enabling seamless handovers.

⚠️ What It Doesn’t Do

This flag does not:

• Clean up references from the previous release.
• Protect you from future uninstalls of the original release (which might still remove shared resources).
• Allow you to adopt completely unmanaged Kubernetes resources (those not initially created by Helm).
  

In short, it’s a mechanism for bypassing Helm’s ownership checks, not a full lifecycle manager.

Real-World Helm Take Ownership Use Cases

Let’s go through common scenarios where this feature is useful.

✅ 1. Renaming a Release Without Downtime

Before:

helm uninstall old-name
helm install new-name ./chart

Now:

helm upgrade new-name ./chart --take-ownership

✅ 2. Migrating Objects Between Charts

You’re refactoring a large chart into smaller, modular ones and need to reassign certain Service or Secret objects.

This flag allows the new release to take control of the object without deleting or recreating it.

✅ 3. GitOps Drift Reconciliation

If objects were deployed out-of-band or their metadata changed unintentionally, GitOps tooling using Helm can recover without manual intervention using --take-ownership.

Best Practices and Recommendations

• Use this flag intentionally, and document where it’s applied.
• If possible, remove the previous release after migration to avoid confusion.
• Monitor Helm’s behavior closely when managing shared objects.
• For non-Helm-managed resources, continue to use kubectl annotate or kubectl label to manually align metadata.
  

Conclusion

The --take-ownership flag is a welcomed addition to Helm’s CLI arsenal. While not a universal solution, it smooths over many of the rough edges developers and SREs face during release evolution and GitOps adoption.

It brings a subtle but powerful improvement—especially in complex environments where resource ownership isn’t static.

Stay updated with Helm releases, and consider this flag your new ally in advanced release engineering.

The Modern Way: helm upgrade –take-ownership

Since Helm 3.17, most of the manual adoption workflow below is one flag:

helm upgrade --install myrelease ./mychart --take-ownership

With --take-ownership, Helm skips the ownership check that normally fails with “invalid ownership metadata; annotation validation error” and rewrites the ownership metadata to point at the new release. The resources’ spec is untouched — only the Helm bookkeeping changes. Two caveats: it applies to every conflicting resource in the chart (there is no per-resource opt-in), and it will happily steal resources from another Helm release, not just from kubectl-created objects — so run it with --dry-run first in anything shared.

Manual Adoption: The Three Ownership Markers

On older Helm versions (or when you want per-resource control), adoption means setting the three markers Helm checks before managing a resource:

kubectl label   deployment myapp "app.kubernetes.io/managed-by=Helm"
kubectl annotate deployment myapp "meta.helm.sh/release-name=myrelease"
kubectl annotate deployment myapp "meta.helm.sh/release-namespace=default"

After those three, the next helm upgrade treats the resource as its own and reconciles it against the chart template. This is the route to migrate kubectl-managed or kustomize-managed infrastructure into a chart incrementally, one resource at a time, without deleting anything.

Frequently Asked Questions