In a Kubernetes CRD, what does setting deprecated: true on a version entry do for clients, and how is it different from served: false?

## Two flags, two different promises Each entry in a CustomResourceDefinition's `spec.versions` has flags that act on clients rather than on data: - **`deprecated`** (default `false`) — the version still works exactly as before, but the API server attaches a **warning** to every response for a request made at that version. - **`deprecationWarning`** — replaces the default warning text. It may be set only when `deprecated` is `true`. - **`served`** — whether the version's REST paths exist at all. Neither flag changes how objects are stored. The storage version and the objects in etcd are untouched either way. ## What `deprecated: true` looks like to a client The warning travels in an HTTP `Warning` response header. `kubectl` prints it, and client libraries can log or surface it. The default text names the deprecated version and, when one exists, the newest served non-deprecated version of the same kind: ```bash kubectl get suggestindexes.v1alpha1.autocomplete.example.com -n search ``` For the search-autocomplete team's `SuggestIndex`, that command still lists the objects, and `kubectl` first prints `Warning: autocomplete.example.com/v1alpha1 SuggestIndex is deprecated; use autocomplete.example.com/v1 SuggestIndex`. A custom `deprecationWarning` is useful when the default text is not enough — for example to link a migration guide or name the release in which the version stops being served. Deprecation is **advisory**: nothing breaks, so it is the right first step when the search-autocomplete team wants to retire `v1alpha1`. ## What `served: false` does Setting `served: false` removes the version from the API surface: 1. Requests to `/apis/autocomplete.example.com/v1alpha1/...` get **404 Not Found**, as if the version never existed. 2. Discovery stops advertising it, so tools that enumerate versions no longer see it. 3. Objects **stored** in `v1alpha1` are still readable through `v1`, because the API server can convert from any version still listed in `spec.versions`, served or not. That third point is the difference between "stop serving" and "delete": data survives `served: false`, but it would not survive removing the entry while objects are still stored in it. ## Side by side | | `deprecated: true` | `served: false` | |---|---|---| | Requests at that version | Succeed, with a warning | Fail with 404 | | Visible in discovery | Yes | No | | Stored objects | Unchanged, readable | Unchanged, readable through other versions | | Typical use | Announce retirement | Flush out remaining clients | | Reversible instantly | Yes | Yes | ## The usual retirement order 1. Add the new version and make it the storage version. 2. Set `deprecated: true` on the old one and tell users. 3. After a release or two, set `served: false`. 4. Migrate stored objects and remove the old entry once nothing is stored in it. ## Common confusions - Deprecation does **not** reject requests, and it does not convert stored data. - `served: false` is **not** removal: the entry, its schema and conversion from it are still in use. - A version can be stored without being served; the storage flag and the served flag are independent.