Kubernetes 1.37 makes the StorageVersionMigration API stable and enabled by default, giving cluster administrators and custom resource authors a supported way to rewrite existing objects in the API server’s current storage version.
The change matters because changing an API or CRD storage version does not automatically rewrite every object already stored in the cluster. Objects can remain in an older representation until they are updated or explicitly migrated. Storage version migration can also be used when rotating encryption-at-rest keys, although operators must retain the old key until the relevant objects have been rewritten.
What changed in Kubernetes 1.37
The Kubernetes 1.37 release overview identifies the StorageVersionMigration API as stable and enabled by default. This makes the API generally available for supported migration workflows in clusters running the new release.
That does not mean Kubernetes automatically migrates every existing object when a cluster is upgraded. Migration remains an explicit operation. An administrator creates a StorageVersionMigration resource for a particular API resource, applies it to the cluster, and monitors its status.
The distinction is important: new or updated objects use the current storage version, but older objects may continue to use an earlier version until they are rewritten. A normal read can convert an object for the client without changing its stored representation, so reading objects alone is not a substitute for storage version migration.
Why stored versions matter
Kubernetes supports multiple served API versions in several migration scenarios. The API server can convert objects between versions for clients, while persisting them in a designated storage version. When that storage version changes, existing data can remain in the previous format.
The Kubernetes storage-version documentation describes migration as a way to rewrite stored objects into the current version. This is relevant when an API schema changes, when a CRD changes its preferred storage version, and when operators need to rewrite encrypted data after an encryption-key change.
For encryption-at-rest rotation, migration can rewrite objects under the new key. The old key still needs to remain available until all relevant objects have been rewritten. The supplied Kubernetes documentation does not define a complete key-retirement policy, so operators should not treat completion of a single migration request as a universal signal that an old key can immediately be removed.
How administrators trigger a migration
The documented procedure requires a Kubernetes server version of 1.30 or later and a configured kubectl client that can communicate with the cluster. The workflow is resource-specific:
- Create a
StorageVersionMigrationobject that identifies the target resource group and resource. - Apply the migration manifest with
kubectl. - Monitor the migration resource and its status conditions.
- Verify that the target objects have been rewritten before removing an obsolete API or storage version.
The official storage version migration task includes manifests and kubectl examples for these operations. The migration status includes conditions such as Running and Succeeded, which provide a way to determine whether the operation is still active or has completed.
Migration is an active control-plane operation rather than a read-only inspection. The implementation performs list and update activity against the API server. As a result, it can increase resource use in the API server and kube-controller-manager. The implementation documentation also identifies API-server or etcd unavailability as an error condition.
What CRD authors need to verify
CustomResourceDefinitions must designate exactly one version as the storage version. A CRD can serve multiple versions, but its conversion behavior must support the relationship between those versions when their schemas differ.
Changing the storage version in a CRD does not by itself guarantee that all existing custom resources have been rewritten. CRD authors and cluster administrators should explicitly migrate the existing objects, then verify the CRD status before removing an older version.
The CRD versioning documentation says an old version should not be removed until:
- clients have been migrated to the newer version;
- existing objects have been upgraded or migrated;
- the old version no longer appears in
status.storedVersions.
Removing a version too early can leave stored objects unreadable or cause clients that still depend on the version to fail. Checking status.storedVersions is therefore a necessary part of the removal process, not just an administrative formality.
Operational and compatibility considerations
Administrators should schedule migrations with the control plane’s workload in mind. Because the operation generates list and update requests, large migrations may compete with normal API activity. Monitor the migration status and the migration-related metrics or events documented for the implementation where those signals are available.
Storage version migration should also be evaluated resource by resource. The Kubernetes task documentation indicates that resources and CRDs generally have the required resource-version behavior, but warns that migration can fail for resources such as aggregated APIs. Kubernetes does not provide a complete compatibility matrix in the supplied documentation, so operators should verify support before applying the process broadly.
The precise RBAC permissions required for every migration scenario are not established in the supplied sources. Administrators should use their organization’s access controls and validate permissions in a controlled environment rather than assuming that the stable API changes existing authorization boundaries.
What you should do
- Inventory version changes. Identify CRDs and other resources whose storage version has changed or whose API version is scheduled for removal.
- Confirm prerequisites. Use a Kubernetes server at version 1.30 or later and ensure
kubectlis configured for the intended cluster. - Review conversion behavior. For CRDs with different schemas, confirm that the CRD’s conversion strategy supports the versions involved.
- Trigger migration explicitly. Create a
StorageVersionMigrationresource for the target group and resource, apply it, and monitor its status until it reports completion. - Verify before removal. For CRDs, inspect
status.storedVersionsand confirm that the obsolete version is absent before removing it from the CRD. - Handle encryption rotation carefully. If the migration follows an encryption-key change, retain the old key until the relevant objects have been rewritten.
- Test unsupported cases. Treat aggregated APIs and resources with uncertain compatibility as requiring separate verification.
Availability caveat
The v1.37 release overview supports the statement that StorageVersionMigration is stable and enabled by default. However, the official migration task page contains contradictory wording: its heading says the feature is disabled by default, while later text says the feature gate and the storagemigration.k8s.io/v1 API are enabled by default.
For that reason, this article relies on the narrower release-level claim rather than asserting a particular feature-gate configuration. The supplied material does not establish the exact v1.37 feature-gate table or whether administrators must configure a gate in every deployment. Provider-specific and distribution-specific availability is also not established.
