In Helm, how do you adopt an object that already exists in the cluster?

## The problem adoption solves A resource exists in the cluster — created by hand, by an older script, or by a tool you are migrating away from — and you now want a chart to manage it. Helm refuses to write over it because it carries no ownership metadata naming your release. Adoption is the act of making Helm's ownership check pass for that object so the release can take it under management without a delete-and-recreate, which for something like a Service with a provisioned load-balancer address, or a PersistentVolumeClaim, is exactly what you are trying to avoid. ## Route one: stamp the metadata yourself The check reads one label and two annotations, so you can satisfy it directly: - `app.kubernetes.io/managed-by=Helm` as a label; - `meta.helm.sh/release-name=<release>` as an annotation; - `meta.helm.sh/release-namespace=<namespace of the release>` as an annotation. Use `--overwrite` on the annotate and label commands, because an object migrating from another tool often already carries a different `managed-by` value. Then run `helm upgrade --install`. Helm hits `AlreadyExists`, re-reads the object, finds all three keys matching, and adopts it. This route has one large advantage: it is per-object. You decide exactly which resources are claimed, and the ownership check keeps guarding every other object in the release. It is also reviewable — the commands are the change, and they can go in a runbook or a migration script. ## Route two: --take-ownership Helm 3.17 added `--take-ownership` to `helm install` and `helm upgrade` (Helm 4 carries it too). With the flag set, Helm does not perform the ownership check at all for that run: any existing object the release renders is claimed and stamped with the release's ownership metadata as part of the apply. That is convenient when a chart adopts a dozen objects at once and hand-stamping each would be tedious. It is also indiscriminate — it is a property of the command, not of an object, so it will just as happily claim a resource that another Helm release currently owns. ## What changes after adoption An adopted object is not special afterwards; it is an ordinary member of the release: - **It is reconciled to the chart.** The next apply makes the object match what the chart renders. Settings a person added by hand and the chart does not express are not protected by adoption — get the chart rendering what you want *before* you adopt, or the adoption itself becomes a live change. - **It enters the stored manifest.** From that revision on it appears in the release's recorded manifest, so `helm history` and `helm rollback` cover it. - **`helm uninstall` deletes it.** This is the consequence people are surprised by. A database Service or a PVC that pre-dated the chart and survived every previous experiment now disappears with the release, unless the chart marks it with the resource-policy annotation that tells Helm to leave it behind. ## Practical sequencing A safe adoption reads like this. Render the chart and compare its output against the live object, so you know what the first upgrade will change. Adjust values until the rendered object is as close to the live one as you want it to be. Stamp the ownership metadata on the specific objects you intend to claim. Run the upgrade. Then confirm the release now lists them — the objects appear in the release's manifest and carry the annotations naming your release. ## Things that go wrong - Setting `meta.helm.sh/release-namespace` to the *object's* namespace when the release lives elsewhere. It must be the release's namespace, which matters for cluster-scoped objects. - A typo in the release name: the check still fails, with a message showing the value it found. - Assuming the flags that delete-and-recreate an object, or that override apply conflicts, will do this job. They address different failures and do not skip the ownership check. - Adopting an object another release owns. Nothing stops you, and the loser is the other release, which will delete or fight over the object later.