Enhancement Description
- One-line enhancement description (can be used as a release note):
Vanilla CRD OpenAPI Subset: Structural Schemas
- Kubernetes Enhancement Proposal:
The CRD validation schemas today support nearly the whole OpenAPI v3 schema language. Here, we propose to impose a restriction called structural schema to that language, which will
- significantly reduce difficulty in moving forward with advanced features like pruning, defaulting, server-side apply, read-only fields and protobuf in the near and medium term future
- while keeping needed expressivity to express Kubernetes-like APIs including powerful value validations.
Schema generators (like crd-gen and openapi-gen) which recurse over API Golang types produce structural schemas naturally. Developers can enrich those structural schemas with nearly arbitrary value validation logic, usually using in-code +kubebuilder-like tags.
The restriction is an API change of the CustomResourceDefinition kind in the apiextensions.k8s.io/v1beta1 API group, but in the sense that
- CRDs created via the
v1beta1 endpoints are not restricted such that existing CRDs keep working as before,
- but CRDs created or updated via the
v1beta1 endpoints have to conform to the new restrictions if they want to make use of new features.
In the v1 CustomResourceDefinition API we will enforce structural schemas on creation and do ratcheting validation on update (allow updates with non-structural schemas if the original schema was non-structural already).
To communicate to the developer that a CRD does not follow the structural schema restriction and will therefore not benefit from future developments, we add a NonStructuralSchema condition to the CRD.
#1002
Implementation History
Please keep this description up to date. This will help the Enhancement Team to track the evolution of the enhancement efficiently.
Enhancement Description
Vanilla CRD OpenAPI Subset: Structural Schemas
The CRD validation schemas today support nearly the whole OpenAPI v3 schema language. Here, we propose to impose a restriction called structural schema to that language, which will
Schema generators (like crd-gen and openapi-gen) which recurse over API Golang types produce structural schemas naturally. Developers can enrich those structural schemas with nearly arbitrary value validation logic, usually using in-code
+kubebuilder-like tags.The restriction is an API change of the CustomResourceDefinition kind in the
apiextensions.k8s.io/v1beta1API group, but in the sense thatv1beta1endpoints are not restricted such that existing CRDs keep working as before,v1beta1endpoints have to conform to the new restrictions if they want to make use of new features.In the
v1CustomResourceDefinition API we will enforce structural schemas on creation and do ratcheting validation on update (allow updates with non-structural schemas if the original schema was non-structural already).To communicate to the developer that a CRD does not follow the structural schema restriction and will therefore not benefit from future developments, we add a
NonStructuralSchemacondition to the CRD.#1002
k/enhancements) update PR(s):k/k) update PR(s):k/website) update PR(s):Implementation History
Please keep this description up to date. This will help the Enhancement Team to track the evolution of the enhancement efficiently.