OCI Chart Storage Stabilization in Helm 3.11 Introduces Unresolved CRD Version Conflict Handling

Question

When using Helm 3.11’s stabilized OCI chart storage to distribute charts, teams aim to safely manage CustomResourceDefinition (CRD) versions across multiple releases.
However, Helm does not currently detect or prevent situations where two releases attempt to install different versions of the same CRD, leaving the cluster in an indeterminate state that requires manual inspection to determine which version is active.
This gap raises the question of how Helm should handle CRD version conflicts moving forward.
Should Helm emit a warning when a release would introduce a conflicting CRD version? Should Helm block the installation unless the user explicitly overrides the conflict? Should Helm provide a flag to enforce namespace‑scoped CRDs or delegate CRD management to external tools?

Tasadduq Burney · Answer

Answering the Question

Helm 3.11’s OCI chart storage installs CRDs via the standard crd-install hook. The hook simply kubectl apply‑s the CRD resource; it does not compare the incoming CRD spec with the one already present in the cluster. Consequently, if two releases ship different versions of the same CRD, the last release applied wins silently and the cluster remains in an indeterminate state.

Why the Gap Exists

CRDs are cluster‑scoped, so Helm has no built‑in namespace‑level isolation to prevent accidental overrides.
Helm’s release history records the CRD resource, but the engine treats it like any other resource without validation.
Detecting a version conflict would require deep comparison of the CRD’s spec.versions list, which is not part of Helm’s current hook semantics.

Practical Steps for Teams

Inspect the existing CRD before upgrade:

kubectl get crd <crd-name> -o json | jq .spec.versions

Separate CRD installation from chart upgrades: Create a dedicated Helm release (or use a GitOps tool) that installs only the CRD once and pins its version.
Use an external CRD manager: Operator Lifecycle Manager, Kustomize, or a dedicated CRD repository can enforce immutable CRD versions or block upgrades.
Enable Helm debug output during install/upgrade:
```
helm install my-release my-chart --debug
```
This logs the applied CRD, allowing manual verification.
Document CRD versions in your chart’s README: Include a CRD_VERSION variable that team members check against the cluster.

What Helm Could Offer in the Future

Emit a warning when a crd-install hook would overwrite an existing CRD with a different spec.versions list.
Provide a --block-crd-conflict flag that aborts the install unless the user passes --force-crd-overwrite.
Introduce a --namespace-scoped-crd flag that either rejects cluster‑scoped CRDs or requires the operator to expose a namespaced variant.
Expose a hook‑level API for CRD comparison so that chart authors can decide how strict the conflict resolution should be.

Immediate Work‑Arounds

Run helm upgrade --dry-run --debug to review all resources that will be applied, including CRDs.
If you detect a conflicting CRD, manually delete or patch the existing CRD before running helm upgrade.
```
kubectl delete crd <crd-name>
helm upgrade my-release my-chart
```
Use helm get manifest my-release to compare the CRD spec in the release with the cluster’s current CRD.

Conclusion

At present, Helm 3.11 does not detect or prevent CRD version conflicts. Teams should adopt a disciplined approach: separate CRD installation, use external tooling, and manually verify before upgrades. While future Helm releases could add warning or blocking flags, those features are not yet available. Until then, the best mitigation is to treat CRDs as immutable artifacts and manage them outside the chart lifecycle.