From 8c9ca0579d2e755ca1b96466efdc6b1fd6c9f8d7 Mon Sep 17 00:00:00 2001 From: Marcin Owsiany Date: Mon, 10 Oct 2022 11:26:32 +0200 Subject: [PATCH 1/3] Use "stored" rather than "persisted" consistently with the rest of the document. --- .../custom-resource-definition-versioning.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md index 99fd7f4823d..074b3f3a3ee 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md @@ -356,7 +356,7 @@ spec: ### Version removal -An older API version cannot be dropped from a CustomResourceDefinition manifest until existing persisted data has been migrated to the newer API version for all clusters that served the older version of the custom resource, and the old version is removed from the `status.storedVersions` of the CustomResourceDefinition. +An older API version cannot be dropped from a CustomResourceDefinition manifest until existing stored data has been migrated to the newer API version for all clusters that served the older version of the custom resource, and the old version is removed from the `status.storedVersions` of the CustomResourceDefinition. ```yaml apiVersion: apiextensions.k8s.io/v1 @@ -1021,16 +1021,16 @@ Example of a response from a webhook indicating a conversion request failed, wit ## Writing, reading, and updating versioned CustomResourceDefinition objects -When an object is written, it is persisted at the version designated as the +When an object is written, it is stored at the version designated as the storage version at the time of the write. If the storage version changes, existing objects are never converted automatically. However, newly-created or updated objects are written at the new storage version. It is possible for an object to have been written at a version that is no longer served. When you read an object, you specify the version as part of the path. If you -specify a version that is different from the object's persisted version, +specify a version that is different from the object's stored 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 +stored object is neither changed on disk, nor converted in any way (other than changing the `apiVersion` string) while serving the request. You can request an object at any version that is currently served. @@ -1040,23 +1040,22 @@ one version to another. To illustrate this, consider the following hypothetical series of events: -1. The storage version is `v1beta1`. You create an object. It is persisted in - storage at version `v1beta1` +1. The storage version is `v1beta1`. You create an object. It is stored at version `v1beta1` 2. You add version `v1` to your CustomResourceDefinition and designate it as the storage version. 3. 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. -4. You create a new object. It is persisted in storage at version `v1`. You now +4. You create a new object. It is stored at version `v1`. You now have two objects, one of which is at `v1beta1`, and the other of which is at `v1`. -5. You update the first object. It is now persisted at version `v1` since that +5. You update the first object. It is now stored at version `v1` since that is the current storage version. ### Previous storage versions The API server records each version which has ever been marked as the storage -version in the status field `storedVersions`. Objects may have been persisted +version in the status field `storedVersions`. Objects may have been stored at any version that has ever been designated as a storage version. No objects can exist in storage at a version that has never been a storage version. From 74dd6552860cbef9bd201dd65eb2c4d732da3642 Mon Sep 17 00:00:00 2001 From: Marcin Owsiany Date: Tue, 11 Oct 2022 10:33:43 +0200 Subject: [PATCH 2/3] Clarify the case of requested version != stored version. --- .../custom-resource-definition-versioning.md | 23 ++++++++++++++----- 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md index 074b3f3a3ee..ce45205d4e6 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md @@ -1027,12 +1027,21 @@ existing objects are never converted automatically. However, newly-created or updated objects are written at the new storage version. It is possible for an object to have been written at a version that is no longer served. -When you read an object, you specify the version as part of the path. If you -specify a version that is different from the object's stored version, -Kubernetes returns the object to you at the version you requested, but the -stored object is neither changed on disk, nor converted in any way -(other than changing the `apiVersion` string) while serving the request. +When you read an object, you specify the version as part of the path. You can request an object at any version that is currently served. +If you specify a version that is different from the object's stored version, +Kubernetes returns the object to you at the version you requested, but the +stored object is not changed on disk. + +What happens to the object that is being returned while serving the read +request depends on what is specified in the CRD's `spec.conversion`: +- if the default `strategy` value `None` is specified, the only modifications + to the object are changing the `apiVersion` string and perhaps [pruning + unknown fields](/docs/concepts/extend-kubernetes/api-extension/custom-resources/custom-resource-definitions/#field-pruning) + (depending on the configuration). Note that this is unlikely to lead to good + results if the schemas differ between the storage and requested version. +- if [webhook conversion](#webhook-conversion) is specified, then this + mechanism controls the conversion. If you update an existing object, it is rewritten at the version that is 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: 1. The storage version is `v1beta1`. You create an object. It is stored at version `v1beta1` 2. You add version `v1` to your CustomResourceDefinition and designate it as - the storage version. + the storage version. Here the schemas for `v1` and `v1beta1` are identical, + which is typically the case when promoting an API to stable in the + Kubernetes ecosystem. 3. 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. From 270c6803d19f712774f49a215019aa68951cc571 Mon Sep 17 00:00:00 2001 From: Marcin Owsiany Date: Wed, 14 Dec 2022 12:15:28 +0100 Subject: [PATCH 3/3] Applied review comment. --- .../custom-resources/custom-resource-definition-versioning.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md index ce45205d4e6..3d0d3a4800a 100644 --- a/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md +++ b/content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning.md @@ -1040,6 +1040,8 @@ request depends on what is specified in the CRD's `spec.conversion`: unknown fields](/docs/concepts/extend-kubernetes/api-extension/custom-resources/custom-resource-definitions/#field-pruning) (depending on the configuration). Note that this is unlikely to lead to good results if the schemas differ between the storage and requested version. + In particular, you should not use this strategy if the same data is + represented in different fields between versions. - if [webhook conversion](#webhook-conversion) is specified, then this mechanism controls the conversion.