# How to adopt existing Kubernetes resources into a Helm release

> Fix the Helm invalid ownership metadata error: find conflicting objects, label and annotate them, and move objects between releases safely.

Published: 2026-11-19
Author: k8wiz Team
URL: https://k8wiz.com/articles/adopt-existing-resources-into-a-helm-release

You have a Deployment, a Service and a few ConfigMaps that someone created with `kubectl apply`, or that another tool rendered from a chart. Now you want Helm to manage them. You run `helm install` and get this:

```text
Error: INSTALLATION FAILED: unable to continue with install: ConfigMap "web-config" in namespace "shop" exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to "web"; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to "shop"
```

Helm is protecting you here. It refuses to take over an object it can't prove belongs to the release. This guide shows how to hand those objects over on purpose, without downtime, and how to move an object from one release to another without Helm deleting it on the way. The commands were checked against Helm 4.3.2, and the ownership rules are the same in Helm 3.

## Why Helm refuses to touch the object

Before an install creates anything, Helm reads every object the chart renders from the cluster. If an object doesn't exist yet, Helm will create it. If it exists, Helm checks three pieces of metadata on the live object: the label `app.kubernetes.io/managed-by` must be `Helm`, the annotation `meta.helm.sh/release-name` must equal the release name, and `meta.helm.sh/release-namespace` must equal the release namespace. When all three match, Helm adopts the object and updates it to match the chart. When any of them is missing or different, the install stops before it changes anything.

Upgrades run the same check, but only on objects that are new in this revision. Helm compares the manifest stored in the previous revision with the new one, and any object in the new manifest that wasn't in the old one goes through the ownership check. That is why a chart upgrade that adds a ConfigMap can fail with the same error, worded as `unable to continue with update`.

The error text tells you which part is wrong. `missing key` means the label or annotation isn't there at all, which is typical for objects created by hand. `must equal "web": current value is "api"` means another release already owns the object. Treat those two cases differently: the first is an unclaimed object, the second belongs to someone else.

## Step 1: list every object the chart would collide with

Helm stops at the first conflict it finds, so running the install over and over only shows you one object at a time. A faster way is to render the chart yourself and ask the cluster which of those objects already exist, along with their current ownership metadata.

```bash
release=web
ns=shop

helm template "$release" ./web-chart -n "$ns" -f values-prod.yaml \
  | kubectl get -n "$ns" -f - --ignore-not-found \
      -o custom-columns='KIND:.kind,NAME:.metadata.name,MANAGED-BY:.metadata.labels.app\.kubernetes\.io/managed-by,RELEASE:.metadata.annotations.meta\.helm\.sh/release-name'
```

Use the same values files and flags you will pass to `helm install`, because values can change which objects the chart renders and what they are called. Every row in the output is an object that exists today. Rows with `<none>` in both columns are unclaimed. Rows that show another release name are owned by that release, and you should stop and find out why before going further.

The `helm template` output also includes hooks and test pods. Helm doesn't run the ownership check on hooks, so you can ignore any hook objects in this list.

## Step 2: check what the chart would change

Adoption isn't a read-only operation. As soon as Helm owns an object, it applies the chart's version of it. If the chart sets two replicas and the live Deployment runs six, the install scales it down. If the chart's Service has a different selector, traffic stops.

Compare the rendered chart with the live objects before you hand anything over.

```bash
helm template "$release" ./web-chart -n "$ns" -f values-prod.yaml \
  | kubectl diff -n "$ns" -f -
```

Read the diff the way you would read a pull request. Fix differences in your values file until the only changes left are ones you want, such as new labels. Pay special attention to Deployment selectors and Service selectors. A Deployment's `spec.selector` can't be changed after creation, so a chart that renders a different selector will fail to apply no matter what the ownership metadata says.

## Step 3: label and annotate the live objects

Now give each unclaimed object the metadata Helm looks for. The loop below takes the object list straight from the rendered chart, so you don't have to type names by hand. Only run it after Step 1 showed that none of these objects belongs to another release, because `--overwrite` will happily replace another release's annotations.

```bash
release=web
ns=shop

helm template "$release" ./web-chart -n "$ns" -f values-prod.yaml \
  | kubectl get -n "$ns" -f - --ignore-not-found -o name \
  | while read -r obj; do
      kubectl -n "$ns" label "$obj" app.kubernetes.io/managed-by=Helm --overwrite
      kubectl -n "$ns" annotate "$obj" \
        meta.helm.sh/release-name="$release" \
        meta.helm.sh/release-namespace="$ns" --overwrite
    done
```

Labels and annotations don't change how a workload runs, so this step is safe on a live system. Pods aren't restarted, because the pod template isn't touched.

Cluster-scoped objects such as a ClusterRole need the same three keys. Their `meta.helm.sh/release-namespace` annotation still holds the namespace of the release, not an empty string.

## Step 4: preview the install, then run it

Run the install as a server-side dry run first. `--dry-run=server` sends the requests to the API server in dry-run mode, so the ownership check runs against the real cluster and nothing is saved. `--dry-run=client` doesn't contact the cluster, so it can't see existing objects and won't catch a conflict.

```bash
helm install "$release" ./web-chart -n "$ns" -f values-prod.yaml --dry-run=server > /dev/null
```

If that exits cleanly, run it for real. Use `helm upgrade --install` if that's what your pipeline runs, since it goes through the same install path for a new release.

```bash
helm upgrade --install "$release" ./web-chart -n "$ns" -f values-prod.yaml --wait
```

Helm 4 applies with server-side apply by default and uses the field manager name `helm`. If an object was last edited by a controller or another tool that owns some of the same fields with different values, the apply can fail with a field conflict. Look at which manager owns the field before you reach for `--force-conflicts`, which makes server-side apply take those fields over. Taking a field from a controller that keeps writing it back just starts a tug of war.

## Step 5: confirm the release owns what you expect

Check that the release recorded every object and that the objects carry the metadata.

```bash
helm status "$release" -n "$ns"

helm get manifest "$release" -n "$ns" \
  | kubectl get -n "$ns" -f - \
      -o custom-columns='KIND:.kind,NAME:.metadata.name,RELEASE:.metadata.annotations.meta\.helm\.sh/release-name'
```

From now on these objects behave like any other Helm-managed object. If a later chart version stops rendering one, the next upgrade deletes it. That is the point of adoption, and also the reason for the next section.

## The --take-ownership shortcut

Helm 3.17 added `--take-ownership` to `helm install` and `helm upgrade`, and Helm 4 keeps it. With the flag, Helm skips the ownership check and adopts every existing object the chart renders, whatever its labels and annotations say. It then writes its own label and annotations onto those objects.

It works, and for a pile of objects created by hand it saves the loop in Step 3. Use it only after running Step 1 anyway. The flag doesn't care whether an object belongs to another release. If it does, both releases now list the object in their manifests. Whichever release upgrades next rewrites the annotations to its own name, and if either release later drops the object from its chart, that upgrade deletes it while the other release still needs it. Explicit annotations make you look at each object, and that is worth the extra minute.

## Moving an object from one release to another

Splitting a chart, or moving a shared ConfigMap into a platform chart, is the case most likely to go wrong. Say release `web` owns the ConfigMap `feature-flags` and you want release `platform` to own it instead.

The trap is in how upgrades delete. When `web` upgrades to a chart version without `feature-flags`, Helm sees an object in the old manifest that isn't in the new one and deletes it. That delete doesn't check who owns the object now. Re-annotating the ConfigMap for `platform` first doesn't protect it. The only thing Helm checks before deleting on upgrade is the `helm.sh/resource-policy: keep` annotation on the live object.

So mark the object to be kept, and remove it from the old release first.

```bash
kubectl -n shop annotate configmap/feature-flags helm.sh/resource-policy=keep

# Upgrade web with a chart version that no longer renders feature-flags.
# Helm skips the delete because of the keep annotation.
helm upgrade web ./web-chart -n shop -f values-prod.yaml
```

The ConfigMap now belongs to no release. Hand it to `platform` the same way as any unclaimed object, then install the chart that renders it.

```bash
kubectl -n shop annotate configmap/feature-flags \
  meta.helm.sh/release-name=platform \
  meta.helm.sh/release-namespace=shop --overwrite

helm upgrade platform ./platform-chart -n shop -f values-platform.yaml --dry-run=server > /dev/null
helm upgrade platform ./platform-chart -n shop -f values-platform.yaml
```

Finally remove the keep annotation, unless you want the object to survive a future uninstall of `platform`.

```bash
kubectl -n shop annotate configmap/feature-flags helm.sh/resource-policy-
```

Doing it in this order means there is no moment when the ConfigMap is missing, and no moment when two releases both believe they own it.

## When the chart and the live names don't match

Adoption only works on exact matches of kind, name and namespace. If the chart renders `web-frontend` and the live Deployment is called `frontend`, Helm sees two different objects. It creates a second Deployment, and the old one keeps running unmanaged next to it.

Most charts let you set the name through `fullnameOverride` or `nameOverride` in values. Set it so the rendered names match the live ones, and Step 1 will show the objects as existing. If the chart has no way to produce the old name, plan a real cutover instead: let Helm create the new objects, move traffic to them, and delete the old ones by hand once nothing points at them.
