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.

• Discussion Link:

#1002

• Primary contact (assignee): @sttts, @mbohlool
• Responsible SIGs: sig-api-machinery
• Enhancement target (which target equals to which milestone):
  • Alpha release target (x.y):
  • Beta release target (x.y):
  • Stable release target (x.y):
• Alpha
  • KEP (k/enhancements) update PR(s):
  • Code (k/k) update PR(s):
  • Docs (k/website) update PR(s):

Implementation History

• PR to implement this KEP: apiextensions: implement structural schema condition kubernetes#77207
• brain storming document with more detail and background: https://docs.google.com/document/d/1pcGlbmw-2Y0JJs9hsYnSBXamgG9TfWtHY6eh80zSTd8/edit?ts=5cbe0089#heading=h.l1xazlj9aw9f
• prototype of pruning: apiextensions: [alpha] opt-in CR pruning according to OpenAPI schema kubernetes#64558
• prototype of defaulting: apiextensions: [alpha] implement defaulting kubernetes#63604

Please keep this description up to date. This will help the Enhancement Team to track the evolution of the enhancement efficiently.