@@ -1027,12 +1027,21 @@ existing objects are never converted automatically. However, newly-created
1027
1027
or updated objects are written at the new storage version. It is possible for an
1028
1028
object to have been written at a version that is no longer served.
1029
1029
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.
1035
1031
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.
1036
1045
1037
1046
If you update an existing object, it is rewritten at the version that is
1038
1047
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:
1042
1051
1043
1052
1. The storage version is `v1beta1`. You create an object. It is stored at version `v1beta1`
1044
1053
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.
1046
1057
3. You read your object at version `v1beta1`, then you read the object again at
1047
1058
version `v1`. Both returned objects are identical except for the apiVersion
1048
1059
field.
0 commit comments