Skip to content

KEP-5667: CRD Map Key Validation #5668

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

KEP-5667: CRD Map Key Validation #5668

wants to merge 1 commit into from
+680 −0

Conversation

@jpbetz
Copy link
Contributor

@jpbetz jpbetz commented Oct 23, 2025

We propose adding a x-kubernetes-property-names extension to OpenAPI 3.0.

This extension can be used to validate map keys. For example, to define map
of string to string where the keys and values have a max length of 32:

type: object
properties:
  exampleMap:
    type: object
    x-kubernetes-property-names:
      type: string
      maxLength: 32
    additionalProperties:
      type: string
      maxLength: 32

@k8s-ci-robot k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Oct 23, 2025
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Oct 23, 2025

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jpbetz

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 23, 2025
@k8s-ci-robot k8s-ci-robot added kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Oct 23, 2025
@jpbetz jpbetz mentioned this pull request Oct 23, 2025
Open
4 tasks
@jpbetz jpbetz force-pushed the x-kubernetes-property-names branch from 4c6d82c to bea50d5 Compare October 23, 2025 22:45
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Oct 23, 2025

@jpbetz: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name Commit Details Required Rerun command
pull-enhancements-test bea50d5 link true /test pull-enhancements-test
pull-enhancements-verify bea50d5 link true /test pull-enhancements-verify

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

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-sigs/prow repository. I understand the commands that are listed here.

JoelSpeed
JoelSpeed reviewed Oct 28, 2025
View reviewed changes
keps/sig-api-machinery/5667-crd-map-key-validation/README.md
`x-kubernetes-property-names` extension as a way of evolving OpenAPI 3.0 in a direction that is
aligned with OpenAPI 3.1.

### Goals
Copy link
Contributor

@JoelSpeed JoelSpeed Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps a good goal here is to make sure that any changes we build in this direction are compatible with a future move to OpenAPI 3.1?

keps/sig-api-machinery/5667-crd-map-key-validation/README.md

- Add `x-kubernetes-property-names` extension.
- Require the use of structural schemas for map keys.
- Update CEL cost estimate system to use `maxLength` of map keys.
Copy link
Contributor

@JoelSpeed JoelSpeed Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the moment it assumes unbounded effectively? So max string length of ~3MiB?

keps/sig-api-machinery/5667-crd-map-key-validation/README.md
- OpenAPI 3.0 libraries that do not recognize the `x-kubernetes-property-names` property are required to ignore it.
This is what makes using an extension preferable to using `propertyNames`. OpenAPI 3.0 libraries may report
an "unrecognized property" error if `propertyNames` is encountered.
- Support for key defaults will also be added.
Copy link
Contributor

@JoelSpeed JoelSpeed Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this mean? How does defaulting for a key work?

keps/sig-api-machinery/5667-crd-map-key-validation/README.md
Risk: The ecosystem is fragmented by CRD schemas that use this feature, since older versions of Kubernetes
do not support it.

Mitigation: Ratchet it in. We do this for other capabilities like new formats, CEL functions, ...
Copy link
Contributor

@JoelSpeed JoelSpeed Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume we will need to follow the same pattern for bringing CEL in of introduce the extension in 1.X, but only allow CRDs to write to the extension in 1.X+1 right? To allow for upgrades/rollback cycles

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JoelSpeed JoelSpeed JoelSpeed left review comments

@apelisse apelisse Awaiting requested review from apelisse

@fedebongio fedebongio Awaiting requested review from fedebongio

Assignees

No one assigned

Labels

approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jpbetz @k8s-ci-robot @JoelSpeed