The process of rewriting persisted Kubernetes objects so they are stored under the current API version rather than a deprecated one. It matters because old stored versions can block CRD cleanup and turn a simple upgrade into an operational dependency.
Expanded Definition
Stored version migration is the controlled rewrite of persisted Kubernetes API objects so they are saved under the current API version instead of a deprecated one. In practice, this is about how data is serialized in etcd, not just which version clients request at runtime.
The distinction matters because Kubernetes often supports multiple served versions of a resource while only one version is intended for storage. When that storage version changes, cluster operators must migrate existing objects before removing old API versions or deleting conversion logic. This is closely related to the Kubernetes API machinery described in Kubernetes CRD versioning and to persistence expectations in Kubernetes API concepts.
Definitions vary across vendors when they discuss “migration,” because some mean a one-time rewrite and others include ongoing conversion webhooks, but no single standard governs this yet. In NHI and agentic platform operations, the term usually appears during CRD upgrades, controller refactors, and platform deprecations where stored objects must be normalized before the old schema can be retired. The most common misapplication is assuming that serving the new version is enough, which occurs when teams upgrade manifests but leave old objects persisted in the legacy storage version.
Examples and Use Cases
Implementing stored version migration rigorously often introduces temporary operational overhead, requiring organisations to balance safer deprecation against the cost of rewriting objects and validating conversion behavior.
- A platform team upgrades a CRD from v1beta1 to v1 and runs a migration job so existing custom resources are rewritten into the v1 storage format before the old schema is removed.
- An admission or conversion webhook is updated, and operators verify that persisted objects can still round-trip cleanly after migration, using guidance from NIST SP 800-53 Rev 5 Security and Privacy Controls to support change control and integrity expectations.
- A GitOps workflow detects that a controller still reads deprecated fields, so stored version migration is scheduled before the next release train to avoid reconciliation failures.
- A security review finds legacy objects that block CRD cleanup, and the team uses Ultimate Guide to NHIs to frame the broader lifecycle risk of stale machine-held state.
- An SRE team migrates stored versions after an incident exposes that rollbacks can reintroduce removed fields unless persisted objects are normalized first.
Why It Matters in NHI Security
Stored version migration matters because NHI security controls are only as durable as the systems that store and enforce them. If a cluster retains deprecated object versions, controllers may continue to process stale policy shapes, stale credentials references, or outdated identity metadata long after the intended upgrade. That creates failure modes in reconciliation, auditability, and lifecycle governance, especially where service accounts, secrets, and agent permissions are represented in custom resources.
NHIMG research shows that only 5.7% of organisations have full visibility into their service accounts, which means hidden dependency chains and stale storage states are likely to persist unless migration is treated as an explicit control step. This operational risk is amplified when teams rely on Kubernetes to manage agent workloads, because a seemingly minor API deprecation can become an identity governance issue if the old version cannot be safely retired. The issue also connects to broader secret and entitlement hygiene covered in Ultimate Guide to NHIs and to control expectations in NIST SP 800-53 Rev 5 Security and Privacy Controls.
Organisations typically encounter the real cost of stored version migration only after a CRD removal stalls a production upgrade, at which point the migration becomes operationally unavoidable to address.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 and CSA MAESTRO address the attack and risk surface, while NIST CSF 2.0, NIST SP 800-63 and NIST Zero Trust (SP 800-207) set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| NIST CSF 2.0 | PR.IP-1 | Version migration is part of maintaining and improving system baselines across changes. |
| NIST SP 800-63 | Not a direct identity-authentication control, but relevant where object state affects identity workflows. | |
| NIST Zero Trust (SP 800-207) | SC-7 | Stored-version cleanup supports reduced implicit trust in legacy object state and paths. |
| OWASP Non-Human Identity Top 10 | NHI-09 | Legacy stored objects can preserve outdated NHI configuration and access scope. |
| CSA MAESTRO | Agentic platforms require safe lifecycle handling of persisted configuration and state. |
Treat storage-version rewrites as a controlled baseline update and validate object integrity after migration.
