Vanilla CRD OpenAPI Subset: Structural Schemas

[shekhar-rajak]

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.

[shekhar-rajak]

#2331 created for migrating the old keps into new template.

[lasomethingsomething]

/sig api-machinery

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[k8s-triage-robot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue.

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue or PR with /reopen
• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.