skip to content

What does `helm upgrade --force-replace` actually do to an object, and what does it cost?

level: middleimportance: must knowfreq 52%

answer

  1. It changes the write path, not the chart
  2. Removed and created, not updated
  3. The object comes back with a new identity
  4. Set on the upgrade, not on one resource
  5. --force is only its deprecated alias

basics

~20 s

It stops Helm patching the existing object and has it removed and created again from the rendered manifest, which is how a change to a write-once field such as a selector lands. Everything the object manages is torn down and rebuilt, so it means an outage.

solid answer

~50 s

`--force-replace` changes how Helm writes a resource: instead of updating what is there, the object is removed and created fresh from the rendered manifest. That is the only way a chart change to a field the API server treats as write-once — a workload's `spec.selector`, a Job's pod template — actually reaches the cluster. The cost is that the object is genuinely new: everything it was managing goes away and comes back, there is no rolling replacement, and whatever the cluster tracked about the old object is gone with it. In Helm 4 the flag is `--force-replace` and `--force` is kept as its deprecated alias; it is **not** `--force-conflicts`, and Helm refuses the two together. Treat it as a planned maintenance action on a workload that tolerates a restart, not as a retry for a failed upgrade.

code

bash · 8 lines
bash
# See which objects the API server would refuse, without committing anything
helm upgrade edge-ingress vendor-repo/ingress-controller \
  --version 4.12.0 -n edge --dry-run=server

# Land the change by replacing the object, and wait for it to come back up
helm upgrade edge-ingress vendor-repo/ingress-controller \
  --version 4.12.0 -n edge \
  --force-replace --wait=watcher --timeout 5m

go deeper

for a junior

Recall that this flag makes Helm remove and recreate the object instead of updating it, and that the workload therefore goes down and comes back. Knowing that --force is now just an old name for --force-replace is enough at this level.

for a middle

Explain why replacing sidesteps the immutable-field refusal at all — a new object has no previous value to conflict with — and describe the costs: no rolling replacement, a new object identity, and a flag that is set on the whole upgrade.

for a senior

Show the judgement: decide from the workload whether a hard gap is acceptable, reach for a second release and a traffic cutover when it is not, and pair the replacement with a wait strategy and a change record so the outage is planned rather than discovered.

for a principal

Own the rule for the organisation: which classes of workload may ever be replaced in place, what evidence a team must produce before doing so in production, and whether the platform makes the safer cutover path cheap enough that nobody reaches for the flag by default.

### What the flag changes In its normal mode Helm updates an existing object: it sends the rendered manifest to the API server and lets the server merge it with what is already there. `--force-replace` swaps that for a replacement — the existing object is removed and created again from the rendered manifest. Nothing about the chart changes; only the write path does. That distinction is the whole point of the flag. Fields such as a workload's `spec.selector`, a Job's pod template and a StatefulSet's `volumeClaimTemplates` may be set once and never updated, so an ordinary upgrade that changes one of them is refused by the API server. A replacement is not an update, so the new value is simply the value of a new object, and the refusal never arises. ### The naming, and the flag it is not Helm 4 renamed this flag. `--force-replace` is the current name; `--force` still works as a deprecated alias, which is exactly why muscle memory is dangerous here. Helm 4 also has `--force-conflicts`, a different flag that concerns which field manager owns a field under server-side apply. The two are mutually exclusive — Helm refuses an upgrade that passes both — and that mutual exclusion is a useful signal that they solve different problems. An engineer who types `--force` intending to override a conflict gets a destructive replacement instead. ### What it costs Because the object is removed and recreated, it is a new object as far as the cluster is concerned. Concretely: - **Everything it manages goes at once.** A Deployment replaced this way does not roll — its pods disappear with it and are created again from scratch by the new object. For a service behind it, that is a hard gap, not a rolling one. - **The old object's identity is gone.** Its UID is new, and anything the cluster tracked against the old object — its rollout history, its status, references keyed to its identity — goes with it. - **The flag is set on the upgrade, not on a resource.** It is not an annotation you attach to the one object that was rejected; it changes how Helm writes the release. Assume every object in the release is in scope, and check what else is in there before you use it. - **It only fixes what recreating fixes.** Replacing a StatefulSet gives it new `volumeClaimTemplates`, but claims that already exist were created earlier and keep the size they had; the template governs claims made afterwards. Replacement is not a migration. ### A worked case Take a third-party ingress-controller chart moving from 4.11.3 to 4.12.0, where the vendor reworked the label helper that feeds the selector. Every release of that chart now fails to upgrade. Two of the releases run behind a maintenance window and nobody notices a forty-second gap; there, `--force-replace` during the window is the cheap answer, and you note in the change record that the controller pods were recreated rather than rolled. A third release fronts a PDF-signing service whose in-flight requests take up to thirty seconds; there, a hard gap is not acceptable and the answer is a cutover — install the new chart version under a second release name, shift traffic, then remove the old one — even though it is more work. That is the decision the flag really presents: it is not "how do I make the upgrade pass", it is "can this object be absent for a moment". ### Using it deliberately A few habits keep it honest. Run the upgrade first as a server-side dry run so you know which objects were going to be rejected and why. Know what else is in the release before you replace anything. Pair it with a wait strategy so the command does not return before the recreated object is actually up — in Helm 4 `--wait` takes a strategy value and, when the flag is omitted, Helm does not wait for workloads at all, so `--wait=watcher` with a timeout is what makes the command's success mean something. And say out loud, in the change ticket, that this is a delete-and-recreate: the cost is invisible in the command line and obvious in the graphs. ### When not to use it If the rejected field changed because a chart bump rewrote a helper you did not intend to change, the cheaper fix is usually to stop the change — pin the values that feed the selector, or stay on the previous chart version until you can plan the cutover. Replacement is the answer when the new shape is genuinely wanted; it is never the answer to "the upgrade failed and I want it to pass".

  • Why does Helm refuse `--force-replace` and `--force-conflicts` in the same command?
    They act at different points. `--force-replace` abandons updating the object at all and recreates it, while `--force-conflicts` tunes how an apply resolves field ownership between managers. Asking for both is asking Helm to both perform an apply and skip it, so Helm rejects the combination rather than silently picking one. The exclusivity is a good reminder that only one of them addresses an immutable-field rejection.
  • If you replace a StatefulSet to change its volumeClaimTemplates, do the existing claims change size?
    No. `volumeClaimTemplates` describes claims made from then on; claims that already exist were created under the old template and keep their size. Helm also does not delete those claims as part of the replacement — they were created by the controller and were never objects in the release. So a replacement gives you a correct template and a set of old claims, which is why this case needs a migration plan rather than a flag.
  • Is `--force-replace` scoped to the one object that was rejected?
    No. It is a flag on the upgrade, not an annotation on a resource, so it changes how Helm writes the release rather than how it writes one object. Before using it, look at what else the release contains — a chart that renders a dozen objects, including ones fronting live traffic, is not a good place to set a release-wide replacement strategy to fix one Job.

saying these in an interview costs you the question

  • Calls it a harmless retry flag for a failed upgrade
  • Thinks it performs a rolling replacement rather than a gap
  • Says --force overrides server-side-apply field conflicts
  • Believes it only touches the resource that was rejected
  • Assumes replacing a StatefulSet resizes existing claims
  • Treats --force as the current Helm 4 spelling

context

resolving links…