A CRD introduces an API shared beyond one release
A CustomResourceDefinition adds a resource API to the cluster. Controllers and applications create custom objects using that API, so the definition's lifecycle can affect more than one chart release or namespace. Ownership needs to be explicit before an upgrade changes schemas or supported versions.
Helm documents special handling for definitions shipped in a chart's crds directory. Those definitions do not follow the same ordinary upgrade, rollback and deletion workflow as templated namespaced objects. Verify the deployed Helm version and chart's published procedure before assuming an upgraded controller also upgraded its API definition.
Setup: inventory definition and consumer versions
Record the CRD name, served and storage versions, schema, conversion configuration and owning operator. Identify controller versions and custom objects using it across the cluster. A namespaced release owner may not know all consumers of a cluster-level definition.
Read the chart or operator's supported upgrade procedure and prerequisites. Some projects separate CRD installation from controller deployment. Plan backup or export evidence appropriate to the custom objects and the operator's recovery contract, including dependent secrets and external state where required.
Review the API lifecycle
- Compare the installed CRD with the target project's published definition and supported migration path. Inspect schema and version changes rather than checking only the chart version number.
- Identify which release process is authorized to update the definition. Avoid allowing independent namespaces to compete over one cluster-wide API without coordination.
- Test representative existing custom objects against the target schema and conversion behavior. Include objects with older field shapes and any supported stored-version migration requirements.
- Rehearse the controller rollout and observe reconciliation. A new definition accepted by the API server does not guarantee that the selected controller can process every existing object correctly.
Illustrative incident: the controller upgrades while its schema stays old
In this illustrative scenario, a team upgrades a chart containing a new controller image. The workflow assumes the CRD was upgraded through the same ordinary chart operation, but its documented special lifecycle left the installed schema unchanged. New custom-object fields are rejected or ignored according to the actual API behavior.
The team follows the project's supported CRD procedure and adds schema-version checks before controller activation. It verifies existing objects as well as a new sample. The scenario explains lifecycle coordination and does not report a real customer cluster incident.
Diagnostic table
| Observation | Evidence | Boundary |
|---|---|---|
| New fields fail validation | Installed schema and target definition | CRD version mismatch |
| Objects exist but do not reconcile | Controller logs and supported versions | Controller compatibility |
| Several charts claim the definition | Release ownership and cluster inventory | Shared API governance |
| Proposed cleanup removes a CRD | Custom-object inventory and recovery plan | Cluster-wide data lifecycle |
Correction and verification
Use the operator's documented supported upgrade sequence and retain the prior definitions and recovery evidence. Review conversion webhooks and controller availability where they participate in the migration. Do not delete a definition as a quick way to clear an ownership error; deletion can remove the associated custom objects.
Verify API discovery, schema acceptance, existing-object visibility and controller reconciliation. Include dependent application behavior and a supported recovery exercise. Reverting a chart revision alone should not be presented as proof that stored custom-object data and API versions returned to their previous state.
SOP
Assign a cluster API owner, controller owner and application consumer contacts. Record CRD upgrade windows, compatibility tests and recovery limitations. The runbook should keep custom-resource lifecycle work reviewable across namespaces, so a routine chart update cannot quietly become an uncoordinated cluster API migration.
See Clouvenix containers kubernetes for implementation and operational handover.
Technical reference
Official reference 1; Official reference 2. Documentation checked 20 October 2026; confirm behavior for your deployed edition and version.