Skip to content

Commit 74dd655

Browse files
committed
Clarify the case of requested version != stored version.
1 parent 8c9ca05 commit 74dd655

File tree

1 file changed

+17
-6
lines changed

1 file changed

+17
-6
lines changed

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1027,12 +1027,21 @@ existing objects are never converted automatically. However, newly-created
10271027
or updated objects are written at the new storage version. It is possible for an
10281028
object to have been written at a version that is no longer served.
10291029

1030-
When you read an object, you specify the version as part of the path. If you
1031-
specify a version that is different from the object's stored version,
1032-
Kubernetes returns the object to you at the version you requested, but the
1033-
stored object is neither changed on disk, nor converted in any way
1034-
(other than changing the `apiVersion` string) while serving the request.
1030+
When you read an object, you specify the version as part of the path.
10351031
You can request an object at any version that is currently served.
1032+
If you specify a version that is different from the object's stored version,
1033+
Kubernetes returns the object to you at the version you requested, but the
1034+
stored object is not changed on disk.
1035+
1036+
What happens to the object that is being returned while serving the read
1037+
request depends on what is specified in the CRD's `spec.conversion`:
1038+
- if the default `strategy` value `None` is specified, the only modifications
1039+
to the object are changing the `apiVersion` string and perhaps [pruning
1040+
unknown fields](/docs/concepts/extend-kubernetes/api-extension/custom-resources/custom-resource-definitions/#field-pruning)
1041+
(depending on the configuration). Note that this is unlikely to lead to good
1042+
results if the schemas differ between the storage and requested version.
1043+
- if [webhook conversion](#webhook-conversion) is specified, then this
1044+
mechanism controls the conversion.
10361045

10371046
If you update an existing object, it is rewritten at the version that is
10381047
currently the storage version. This is the only way that objects can change from
@@ -1042,7 +1051,9 @@ To illustrate this, consider the following hypothetical series of events:
10421051

10431052
1. The storage version is `v1beta1`. You create an object. It is stored at version `v1beta1`
10441053
2. You add version `v1` to your CustomResourceDefinition and designate it as
1045-
the storage version.
1054+
the storage version. Here the schemas for `v1` and `v1beta1` are identical,
1055+
which is typically the case when promoting an API to stable in the
1056+
Kubernetes ecosystem.
10461057
3. You read your object at version `v1beta1`, then you read the object again at
10471058
version `v1`. Both returned objects are identical except for the apiVersion
10481059
field.

0 commit comments

Comments
 (0)