skip to content

How do `--reuse-values` and `--reset-then-reuse-values` differ on a Helm upgrade to a newer chart version?

level: middleimportance: must knowfreq 58%

answer

  1. Two meanings of the old values
  2. Coalesced with old chart, or overrides only
  3. One of them pickles old chart defaults
  4. New chart defaults masked for ever
  5. Reset-then-reuse keeps only user-supplied entries

basics

~20 s

--reuse-values merges your new flags over the previous release's fully coalesced values, which include the old chart's defaults, so a default changed in the new chart is masked. --reset-then-reuse-values merges over only the old user-supplied overrides, letting new defaults through.

solid answer

~50 s

Both keep your old settings; they differ in what counts as "your old settings". `--reuse-values` rebuilds the previous release's **coalesced** values — its user-supplied overrides merged over the *old chart's* `values.yaml` — and merges this command's flags on top. Every default the old chart shipped is now an explicit entry, so when you upgrade a re-ranker chart from 4.9.2 to 4.11.0 and 4.11.0 raises a probe timeout default from 1 to 5 seconds to stop pods flapping, the release keeps 1 and keeps flapping. `--reset-then-reuse-values` resets to the *new* chart's defaults and then lays only the previous release's user-supplied overrides on top, so unoverridden keys pick up the new defaults while your deliberate choices survive. That is what most people mean when they reach for `--reuse-values`, and it is why chart-version upgrades should prefer it.

code

bash · 11 lines
bash
# Old chart 4.9.2 default: readinessProbe.timeoutSeconds = 1
# New chart 4.11.0 default: readinessProbe.timeoutSeconds = 5

# Keeps 1: the old default was folded in as if you had set it
helm upgrade rerank ./reranker-chart --version 4.11.0 --reuse-values

# Picks up 5: only the previous user-supplied overrides are re-applied
helm upgrade rerank ./reranker-chart --version 4.11.0 --reset-then-reuse-values

# Proof, either way
helm get values rerank

go deeper

for a junior

Learn the one-line difference: one of them re-applies the old chart's defaults too, the other re-applies only the values a human passed. Know that a chart upgrade is where the difference shows.

for a middle

Be able to say which map each flag rebuilds — coalesced values versus the user-supplied map — and walk through a changed chart default to show why one flag hides it and the other does not.

for a senior

Demonstrate the diagnosis: read the release's user-supplied values, recognise fossilised chart defaults, and explain how a schema that rejects unknown keys turns years of --reuse-values into a failed upgrade.

for a principal

Decide which flag your platform blesses and whether reuse is allowed in automation at all, knowing that every reuse run makes the release's stored values a second, undocumented source of truth.

### Two things are called "the old values" A release revision stores the **user-supplied values**: the map produced by the `-f` files and `--set` flags of the command that created it. Separately, rendering computes the **coalesced values**: that user-supplied map merged over the chart's `values.yaml` defaults, which is what `.Values` actually resolves against. The two reuse flags differ precisely in which of these they carry forward, and every consequence follows from that one distinction. ### `--reuse-values` Helm regenerates the previous release's coalesced values — old user-supplied map over the **old chart's** defaults — and merges this command's flags on top of it, with the new flags winning on conflict. The result becomes the new revision's user-supplied map. Read that last sentence again, because it is the whole footgun: defaults the old chart happened to ship are now recorded as though a human had set them. They are indistinguishable from deliberate overrides, and they mask whatever the new chart says. Take a recommendation re-ranker chart moving from 4.9.2 to 4.11.0, where 4.11.0's changelog says the readiness probe timeout default went from 1 second to 5 to stop the pods being cycled under load. Upgrade with `--reuse-values` and the release keeps 1: the old default was pickled into the values map. You upgraded to get the fix and did not get it, and `helm get values` will happily show you `timeoutSeconds: 1` as if you had asked for it. The effect is cumulative. Every upgrade run that way re-pickles the then-current defaults, so a release upgraded this way for two years carries a values map that is mostly ancient chart defaults. Two further consequences worth knowing: keys the chart has since *removed* from `values.yaml` linger in the map for ever, and if the chart ships a `values.schema.json` that rejects unknown properties, those fossils can start failing validation on an upgrade that changed nothing you wrote. ### `--reset-then-reuse-values` This one resets to the chart being installed now, then merges the previous release's **user-supplied** map on top, then this command's flags on top of that. Nothing from the old chart's defaults is carried, so every key nobody ever overrode picks up the new chart's default. The probe timeout above becomes 5. One subtlety survives: if someone previously wrote `timeoutSeconds: 1` explicitly — even though it merely matched the default at the time — it is in the user-supplied map and it still masks the new default. Reuse flags cannot distinguish a deliberate choice from a copy of a default; only a human reading the values file can. ### `--reset-values` and the default, for contrast `--reset-values` discards the previous overrides entirely: the revision is the chart's defaults plus exactly what this command passes. The plain default with no reuse flag behaves the same way whenever the command passes any values at all, and copies the previous user-supplied map forward when it passes none. ### Choosing * Pipelines that pass the complete values file every time should use the default, or `--reset-values` to say so out loud. The repository is the description of the release, and nothing needs to be inherited. * An interactive operator changing one thing on a release whose file is not to hand wants `--reset-then-reuse-values`. It is the closest thing to "keep what is there, change this". * `--reuse-values` is the one to justify rather than the one to reach for. Its only honest use is a same-chart-version upgrade where you deliberately want the entire previous computed configuration frozen, and even there the freezing is invisible to the next reader. ### Auditing which one was used Because both write their result into the new revision's user-supplied map, the evidence survives. Run `helm get values <release>` and look at the size and shape of the output: a map that contains whole blocks nobody on the team ever configured — full `resources`, `securityContext`, `podAnnotations` trees matching a chart's stock `values.yaml` — is the fingerprint of `--reuse-values`. Point the same command at `--revision <n>` to see when the map ballooned, which usually dates the run that introduced the habit.

  • Under `--reuse-values`, what happens to a key the new chart version deleted from its values.yaml?
    It stays in the release's values map, because that map was built from the old chart's defaults and Helm has no reason to prune it. Usually it is inert — no template reads it any more. It becomes a real problem when the chart ships a `values.schema.json` that forbids unknown properties, because the upgrade then fails validation over a key nobody wrote.
  • How can you tell after the fact that a past upgrade used --reuse-values?
    Look at `helm get values <release>`, which prints only the user-supplied map. If it contains entire blocks the team never configured — a full stock `resources` or `securityContext` tree — those are old chart defaults that got promoted into overrides, which is the signature of `--reuse-values`. Comparing the same output at an earlier `--revision` usually pinpoints the run where it happened.
  • Does `--reset-then-reuse-values` guarantee that new chart defaults take effect?
    Only for keys nobody ever overrode. If a previous operator explicitly set a key to what was then the default, that value sits in the user-supplied map and still masks the new default. Helm cannot tell a deliberate choice from a copied default, so periodically reading the values file and deleting entries that merely restate defaults is real maintenance work.

--reuse-values photocopies the previous version's entire settings screen and pastes it onto the new version, defaults and all. --reset-then-reuse-values copies over only the boxes a human actually ticked, and lets the new version fill in everything else.

saying these in an interview costs you the question

  • Treating --reuse-values and --reset-then-reuse-values as aliases
  • Expecting new chart defaults to apply under --reuse-values
  • Thinking --reuse-values keeps only keys you explicitly set
  • Saying --reset-then-reuse-values throws away your overrides
  • Calling --reuse-values the safe default for automated upgrades
  • Assuming a reuse flag can tell a deliberate override from a default

context

resolving links…