Change:
{{< note >}} CRDs converted from `apiextensions.k8s.io/v1beta1` to `apiextensions.k8s.io/v1` might lack structural schemas, and `spec.preserveUnknownFields` might be `true`. <del> For migrated CustomResourceDefinitions where `spec.preserveUnknownFields` is set, pruning is _not_ enabled and you can store arbitrary data. For best compatibility, you should update your custom resources to meet an OpenAPI schema, and you should set `spec.preserveUnknownFields` to true for the CustomResourceDefinition itself. </del> <ins> For legacy CustomResourceDefinition objects created as `apiextensions.k8s.io/v1beta1` with `spec.preserveUnknownFields` set to `true`, the following is also true: * Pruning is not enabled. * You can store arbitrary data. For compatibility with `apiextensions.k8s.io/v1`, update your custom resource definitions to: 1. Use a structural OpenAPI schema. 2. Set `spec.preserveUnknownFields` to `false`. </ins> {{< /note >}} If you save the following YAML to `my-crontab.yaml`:

Discussion:
In the "" section there is a text box referring to the conversion from CRDs defined with apiVersion: to apiVersion: It says (second and final paragraph in that text box): For migrated CustomResourceDefinitions where spec.preserveUnknownFields is set, pruning is not enabled and you can store arbitrary data. For best compatibility, you should update your custom resources to meet an OpenAPI schema, and you should set spec.preserveUnknownFields to true for the CustomResourceDefinition itself. I think it is wrong. As we aim for CRD objects defined according to to become RIGHT (as much as possible) CRD objects according to (once converted) I think it should say instead (second sentence in that paragraph): For best compatibility, you should update your custom objects to meet an structural OpenAPI schema, and you should set spec.preserveUnknownFields to false for the CustomResourceDefinition itself where to also specify that structural OpenAPI schema for each defined custom resource version.
This issue is currently awaiting triage. SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the label. The label can be by org members by writing in a comment. <detailsInstructions for interacting with me using PR comments are available . If you have questions or suggestions related to my behavior, please file an issue against the repository. </details
Seems to me that we should write the page to help readers switch to , provided that they are happy that all the clients are accessing via . Does that sound right? /sig api-machinery
To be honest, I do not know. When reading that text box (I read it many times) I understand (but not 100% sure) that the writer is thinking on updating an existing CRD object that refers to "apiVersion: " so the resulting updated CRD object can better match the expectations for a CRD object compliant to "" (when conversion is applied). But presuming (after those so many reads) the writer was not really thinking on anyone updating that existing "" CRD object so it sets "apiVersion: ". (some clarification on all this would be really helpful inside that text box; if both "" and "" are supported in the target k8s API server why then not directly to propose to update the existing CRD objects to set "apiVersion: " ?)

I just checked (in a 1.19 k8s cluster) that it is possible to set "x-kubernetes-preserve-unknown-fields: true" inside the "validation" stanza of an "" CRD object (I was not 100% sure on that) Question: is it possible (i.e. understood by API server) in a pre 1.16 k8s cluster not supporting the newer ""?
what should we document here?
/assign
I only partially understand this problem, and don't want to create additional confusion at that point :-) I'll let Stefan answer, I think he authored that documentation.
I realized now I made some mistakes in my first answer to making difficult to understand my comment. First paragraph should say: When reading that text box (I read it many times) I understand (but not 100% sure) that the writer is thinking on updating an existing CRD object that was originally created with "apiVersion: " so the resulting updated CRD object can better match the expectations for a CRD object compliant to "" (once conversion to this second group-version is applied). And so also presuming (after those so many reads) the writer was not really thinking on anyone updating that existing "" CRD object so it sets "apiVersion: ". (some clarification on all this would be really helpful inside that text box); related question: if both "" and "" are supported in the target k8s API server (i.e. k8s semver = 1.16) why then not directly to propose to update the existing CRD objects to "apiVersion: " ?)
We should not encourage the use of . In by far most cases, it is not good idea, especially when it is used the root of a CRD schema. In general, we want to encourage users of CRDs to get rid of unpruned semantics. In v1 CRDs this is enforced. But if you create a CRD as v1beta1 and then query the v1 conversion of that CRD (note that kube-apiserver will transparently convert back and force in the background) will have although a new v1 CRD could not be created. In other words, the only way to get a v1 CRD with is to create it as v1beta1 and then retrieve it as v1.

I agree the existing sentence is wrong: This should rather be this:
This proposed update would really help to the reader ;-)
I just checked it was not solved in just released 1.20 documentation