Why can installing one Helm chart a second time under a new release name still fail on cluster-scoped objects?

## The scenario You run a media-transcoding pipeline and you want one operator chart installed once per tenant: six tenant namespaces, six releases, six copies of a 240-line values file with different queue sizes and node selectors. Release names are unique per namespace, so the naming looks fine. The first install succeeds. The second one fails, and the object it names is not in any of the namespaces you were thinking about. ## Why the second install fails Helm scopes a *release* to a namespace. It does not scope the *objects a chart renders* to a namespace — the chart does that, by rendering namespaced kinds. Operator charts almost never render only namespaced kinds. A typical one ships: - a `ClusterRole` and `ClusterRoleBinding` so the controller can watch its custom resources across the cluster; - a `ValidatingWebhookConfiguration` or `MutatingWebhookConfiguration`; - a `PriorityClass` for the controller pod, or a `StorageClass` for the scratch volumes the transcoder uses; - `CustomResourceDefinition` objects, either under `templates/` or under `crds/`. Every one of those kinds is cluster-scoped: there is exactly one `ClusterRole` named `transcoder-operator` in the whole cluster, and it belongs to whichever release created it. The second release renders the same name — because the chart author wrote it as a constant, or because the fullname helper was applied to the namespaced objects but not to this one — and the install refuses: that object already exists and belongs to another release. Helm does not merge, does not rename, and does not take it over by default. The failure is often confusing because the error names a cluster-scoped object while the operator was thinking in namespaces. "But the release names are different and they're in different namespaces" is exactly the misconception the question is testing. ## The `crds/` exception, which is not the relief it looks like CustomResourceDefinitions are the special case. If the chart puts them under `templates/`, they are ordinary rendered objects and behave exactly like the ClusterRole above: the second release collides. If the chart puts them in the top-level `crds/` directory, Helm treats them specially. They are never templated, they are installed before the rest of the release, and — the part that matters here — Helm skips them when a definition of that name already exists. So the second release installs cleanly. What you have bought is not isolation but sharing: both releases now depend on one set of definitions, whose version is whatever the *first* install put there. Helm does not upgrade `crds/` definitions on a later `helm upgrade`, in any version, so bumping the chart in tenant two does not update the schema tenant one installed. If the newer chart's controller expects a field that the older definition does not accept, you get a failure at custom-resource-creation time, far away from the install that caused it. ## What to do instead The general shape of the fix is to stop pretending the cluster-scoped half is per-tenant, because it is not. **Split the chart.** One chart (or one sub-chart, or one value-gated block) owns the cluster-scoped objects and is installed exactly once, by whoever owns the cluster. A second, namespaced-only chart is installed once per tenant. This mirrors how operators are usually shipped in practice: an operator install and a per-namespace instance. **Gate the cluster-scoped block behind a value.** A single chart with something like `clusterResources.create` defaulting to true, set to false for every release after the first, works but is fragile: whoever holds the true has to be upgraded first, and uninstalling that release takes the shared objects out from under the others. **Template the names when the objects genuinely are per-release.** Some cluster-scoped objects can legitimately exist once per tenant — a ClusterRole restricted to that tenant's resources, say. Then the name has to include the release name *and* the namespace, because two releases in different namespaces may share a release name and would otherwise still collide. **Decide about the CRDs explicitly.** Either the cluster owns them (install them once, with the shared release, and upgrade them as a deliberate act) or you accept that they are shared and pin every tenant to a compatible chart version range. What you must not do is assume a per-tenant `helm upgrade` keeps their schema current. ## The check that would have caught it Before promising a chart is multi-instance, install it twice into two scratch namespaces on a throwaway cluster and try upgrading only one of them. Reading the templates finds the obvious hardcoded name; installing it twice finds the webhook configuration nobody remembered was cluster-scoped, and upgrading one release afterwards finds the CRD that never moved.