Helm "rendered manifests contain a resource that already exists"

By Daniel Zoghalchali·Latchkey

Helm wants to create a resource that already exists in the cluster but is not owned by this release. Helm will not adopt a resource it did not create, so the install/upgrade stops.

What this error means

helm install/upgrade --install fails with rendered manifests contain a resource that already exists. Unable to continue with install, naming the existing object and what owns it.

helm output

Error: INSTALLATION FAILED: rendered manifests contain a resource that already
exists. Unable to continue with install: ConfigMap "app-config" in namespace
"prod" exists and cannot be imported into the current release: invalid ownership
metadata; ...

Diagnose it: render the chart before you install it

Most Helm failures are visible in the rendered manifests. Template them locally with the same values CI uses and you will usually see the problem without touching the cluster.

Terminal

# what will actually be applied
helm template <release> <chart> -f values.ci.yaml | head -60

# validate against the live cluster schema without installing
helm install <release> <chart> -f values.ci.yaml --dry-run --debug

# what state is the release actually in?
helm history <release>
helm status <release>

Common causes

Resource created outside this release

The object was applied with kubectl, by another Helm release, or by a previous failed install, so it lacks this release’s ownership labels/annotations.

Two releases render the same object

Two charts/releases generate a resource with the same name/namespace, and the second collides with the first.

How to fix it

Adopt the existing resource into the release

Label and annotate it so Helm recognizes it as managed by this release, then upgrade.

Terminal

kubectl label configmap app-config -n prod \
  app.kubernetes.io/managed-by=Helm --overwrite
kubectl annotate configmap app-config -n prod \
  meta.helm.sh/release-name=<release> \
  meta.helm.sh/release-namespace=prod --overwrite
helm upgrade --install <release> ./chart -n prod

Or remove the conflicting resource

Confirm what owns it: kubectl get <res> <name> -o yaml | grep -A3 ownerReferences and the managed-by label.
If it is a leftover from a failed install, delete it and re-run.
If another active release owns it, rename the resource in one chart to avoid the clash.

How to prevent it

Create cluster resources through Helm, not ad hoc kubectl apply, when a chart owns them.
Keep resource names unique across releases in the same namespace.
Use --atomic so failed installs clean up instead of leaving orphans.

Frequently asked questions

What causes Helm "rendered manifests contain a resource that already exists"?

There are 2 common causes: resource created outside this release and two releases render the same object. The object was applied with kubectl, by another Helm release, or by a previous failed install, so it lacks this release’s ownership labels/annotations.

How do I fix Helm "rendered manifests contain a resource that already exists"?

There are 2 fixes depending on which cause you have: adopt the existing resource into the release and or remove the conflicting resource. Work through them in order, since the first is the most common.

What does Helm "rendered manifests contain a resource that already exists" actually mean?

helm install/upgrade --install fails with rendered manifests contain a resource that already exists.

How do I stop Helm "rendered manifests contain a resource that already exists" happening again?

Create cluster resources through Helm, not ad hoc kubectl apply, when a chart owns them. The prevention section lists 3 changes that keep it from recurring.