Helm CRD install mode: unclear Replace strategy sequence and storageVersion handling

Question

Helm CRD install mode
In Helm 3, the chart metadata field crd-install controls how CustomResourceDefinitions are processed during install and upgrade. The default CreateOnly strategy leaves existing CRDs untouched, while Replace deletes and recreates the CRD before applying the new schema.
Although the Replace option exists, the precise order of operations—whether the API server deletes the CRD first and then creates it, or performs a combined update—is not fully documented. Moreover, it is unclear whether the API server resets the storageVersion or preserves it during the replacement, and whether this behavior differs across Kubernetes API server releases.
These uncertainties affect upgrade reliability for charts that rely on schema changes.
Questions:

What is the exact sequence of deletion and creation when crd-install: Replace is used?
Does the replacement process preserve or reset the CRD’s storageVersion?
How does this behavior vary across different Kubernetes API server versions?

Tasadduq Burney · Answer

Analysis of CRD Replacement Behavior

Based on the standard behavior of Helm 3, there is no native crd-install metadata field in Chart.yaml that implements a Replace strategy. By design, Helm installs CRDs located in the crds/ directory only during the initial installation; it does not upgrade, delete, or replace them during subsequent helm upgrade operations.

Understanding the 'Replace' Sequence

If a custom replacement mechanism is implemented (such as via a post-install hook or an external operator) that performs a delete-then-create sequence, the following behavior occurs at the Kubernetes API level:

Sequence: The API server processes a DELETE request for the CRD, followed by a CREATE request. These are distinct operations.
Data Loss: A critical consequence of deleting a CRD is that all existing Custom Resources (CRs) of that type are immediately deleted by the API server. They are not preserved and cannot be recovered by simply recreating the CRD.
Storage Versioning: In Kubernetes, the status.storedVersions field (a list of versions) tracks which versions have been used to store data in etcd. Because the CRD is deleted, the associated metadata and version history are wiped. Upon recreation, the API server initializes the storedVersions list based on the new manifest's version.

Version Considerations and Uncertainty

The behavior of storedVersions has been consistent since the transition to apiextensions.k8s.io/v1, but specific internal API server handling of the deletion grace period can vary across Kubernetes releases. We cannot confirm a specific "reset to 1" numeric behavior because storedVersions is a string array, not a counter.

Verification Steps

To verify how your specific environment handles CRD versions during a manual replacement, you can use these scoped commands:

# 1. Check current stored versions
kubectl get crd <crd-name> -o jsonpath='{.status.storedVersions}'

# 2. Manually delete and recreate (WARNING: This deletes all CRs of this type)
kubectl delete crd <crd-name>
kubectl apply -f <crd-manifest>.yaml

# 3. Verify the new stored versions
kubectl get crd <crd-name> -o jsonpath='{.status.storedVersions}'

To provide a more accurate recommendation, please clarify if you are using a specific third-party Helm plugin or a custom wrapper that introduces the crd-install field, as this is not a standard Helm 3 feature.

Helm CRD install mode: unclear Replace strategy sequence and storageVersion handling