This is a Bug Report

Problem:

One part of the "Versions in CustomResourceDefinitions" document says that conversion is performed from storage version to served version. Another says it's not (and furthermore, that k8s will lie about apiVersion by setting it without actually making any attempt at schema conversion).

Specifically:

1. https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#webhook-conversion says:

The API server also supports webhook conversions that call an external service in case a conversion is required. For example when:

• custom resource is requested in a different version than stored version.

2. At the same time https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#writing-reading-and-updating-versioned-customresourcedefinition-objects says:

If you specify a version that is different from the object's persisted version, Kubernetes returns the object to you at the version you requested, but the persisted object is neither changed on disk, nor converted in any way (other than changing the apiVersion string) while serving the request.

The above sentence is not true in general. Specifically because the part:

the persisted object is neither changed on disk, nor converted in any way (other than changing the apiVersion string) while serving the request

blurs the distinction between the "persisted object" (which indeed never changes on reads) and the served representation (which definitely is converted, if only to change the apiVersion string), this sentence could be read in two ways:

1. The persisted object is not changed on disk. The served representation is not converted (i.e. does not differ from the persisted object) other than the version string.
   This first interpretation is only correct if the schemas do not differ. A casual reader of a general document on conversion webhooks certainly dos not have this assumption, and definitely not before reading the example which follows the above sentence.
2. The persisted object is not changed on disk. The only conversion applied to persisted object is that the apiVersion string is changed. This conversion to persisted object happens when the request is being served.
   This second interpretation is just plain wrong. The on-disk object does not change. Period.

Then later, there is an example which describes a special case of serving a v1 representation of an object persisted at v1beta1 version:

• You read your object at version v1beta1, then you read the object again at version v1. Both returned objects are identical except for the apiVersion field.

This sentence is correct, and in this particular context the first sentence makes more sense (but is still blurry).

Proposed Solution:

1. restructure the first sentence to:
   1. match what happens in the general case of stored version != served version. Not just in the specific vXbetaY -> vX case.
   2. make an explicit distinction between (conceptually immutable on reads) persisted object and the served representation, rather to try and describe both in one go
2. provide an example for the case where conversion webhooks are actually useful (i.e. where the schema between persisted and served versions differs). This can be an additional second example, or the existing example can be replaced.
3. [separate issue] provide an additional example of what happens when there is no conversion webhook defined and
   1. schemas differ
   2. schemas are identical (except for the version string)
4. [separate issue] additionally, it might be good to use "stored version" consistently, rather than "persisted version". This should also probably be a different orthogonal issue.

Page to Update:
https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning