Your CustomResourceDefinition currently offers version v1alpha1 and you want to introduce v1beta1 without breaking existing objects or existing clients. Explain what the `served` and `storage` flags mean on each version entry, and when you need a conversion webhook.

## One object, several representations A CRD's `spec.versions` is a list, and each entry carries its own schema, its own `additionalPrinterColumns` and its own `subresources`. The key insight is that there is only ever **one object** in etcd; the versions are alternative representations of it, and the API server converts between them on every read and write. Two flags control the lifecycle: - **`served: true|false`** — whether the API server exposes that version's endpoint. A version with `served: false` still exists in the CRD (and may still be the historic storage version) but clients cannot use it. Turning `served` off is how you retire a version without deleting data. - **`storage: true|false`** — exactly one version must be `true`. When an object is written, the API server converts it to this version and stores that form. Making a version the storage version is not retroactive. ## Adding a version safely The standard sequence for introducing `v1beta1` alongside `v1alpha1`: 1. **Add** the `v1beta1` entry with `served: true, storage: false`, plus a conversion strategy if the schemas differ. Both endpoints now work; every object is still stored as v1alpha1 and converted up on read. 2. **Migrate clients** — controllers, GitOps repos, CI — to v1beta1. Nothing breaks, because both are served. 3. **Flip storage**: `v1beta1` gets `storage: true`, `v1alpha1` gets `storage: false`. From now on, writes store v1beta1. Existing objects **remain stored as v1alpha1**; the API server converts them on read. 4. **Storage migration**: force every object to be rewritten so it is persisted in the new version. The simple way is to read and write each object (`kubectl get <res> -A -o json | kubectl replace -f -`); the supported tool is the storage version migrator, driven by `StorageVersionMigration` resources in newer clusters. 5. **Prune `status.storedVersions`**: the API server tracks every version any object has been stored in. Until v1alpha1 is removed from that list — which you may only do after migration — you cannot remove the version, because the API server would be unable to decode objects still in that form. 6. **Stop serving** v1alpha1 (`served: false`), then remove the entry entirely. Skipping step 4 or 5 is the classic failure: you delete the old version, and objects still stored in it become undecodable. ## Conversion strategies `spec.conversion.strategy` takes two values. **`None`** performs no transformation at all — the API server simply relabels `apiVersion`. It is correct **only** when the versions are structurally identical, or differ merely by additive optional fields where the missing data is acceptable. Using `None` across a renamed field silently loses data: writing v1beta1 with `spec.storageSize` and reading v1alpha1 expecting `spec.size` yields an object with the field pruned. **`Webhook`** points at a TLS endpoint (a Service reference plus `caBundle`, exactly like admission webhooks) that receives a `ConversionReview` containing a list of objects and the `desiredAPIVersion`, and returns the converted objects. Requirements: - It must convert **in both directions**, since reads may request any served version. - It must be **lossless in practice**: the usual technique is a *hub-and-spoke* model where every version converts to and from one internal hub version, and any field that exists only in a newer version is round-tripped through an annotation so a v1beta1 → v1alpha1 → v1beta1 trip does not destroy data. - It is on the read path for *every* request to a non-storage version, including list operations that may pass many objects at once, so it must be fast and highly available. If it is down, objects in the non-storage version cannot be read at all — including by your own controller. Because `apiextensions.k8s.io/v1` requires the schema per version, the API server validates each representation against its own schema after conversion. ## Compatibility discipline Since the conversion webhook is real operational risk, the strongest move is to avoid needing one: prefer **additive, optional** changes within a version, and use a new version only for genuinely breaking restructurings. Kubernetes' own API convention — alpha may break, beta must be convertible, GA is stable — is a good rule to adopt for your CRDs too. Note also that `served: false` on an alpha version is a legitimate way to force migration in a pre-production platform. One more operational detail: the CRD's `status.conditions` will report `NonStructuralSchema` or conversion problems, and `kubectl get crd <name> -o jsonpath='{.status.storedVersions}'` is the single most useful command when planning a version removal.