✨ New kubebuilder:schemaModifier CRD marker

[yaroslavborbat]

Overview

Closes #441

This pull request introduces a new marker kubebuilder:schemaModifier, which allows modifying specific fields in JSONSchemaProps for CustomResourceDefinitions (CRDs). This marker supports flexible rules for targeting specific paths in the CRD schema and allows setting multiple properties at once.

Details

New Marker: kubebuilder:schemaModifier

The schemaModifier marker operates on CRD schemas and enables users to apply modifications to specific fields. The targeting of fields is achieved using the PathPattern attribute, which defines a path-matching rule using a JSONPath-like syntax:

• *: Matches any single field name (e.g., /spec/*/field).
• **: Matches fields across multiple levels of nesting (e.g., /spec/**/field).

This marker can update multiple properties in JSONSchemaProps, such as Description, Format, Maximum, Nullable, and others.

Example:

// +kubebuilder:schemaModifier:pathPattern=/spec/exampleObject/*,description=""

The above example applies the empty description to all fields matching /spec/exampleObject/*.

How This Was Tested

Currently, no tests have been added for this feature. However, once the structure and approach are approved, I plan to add integration tests to verify the functionality of the kubebuilder:schemaModifier marker.

[k8s-ci-robot]

Welcome @yaroslavborbat!

It looks like this is your first PR to kubernetes-sigs/controller-tools 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/controller-tools has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @yaroslavborbat. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: yaroslavborbat
Once this PR has been reviewed and has the lgtm label, please assign sbueringer for approval. For more information see the Code Review Process.

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

Needs approval from an approver in each of these files:

• OWNERS

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

[chrischdi]

This should have unit-test coverage.

I'd like to understand the use-case some more: Can't this be done by just not setting markers at some fields?

I guess this does not work e.g. for description, but I don't get it for other fields.

[JoelSpeed]

Where there are lists, for example an enum, would you need to specify the entire enum with this marker, and how would that look? What separators are used?

Does this encourage the use of/give folks the ability to create schemas that aren't valid? I wonder if we want to encourage patching schemas in ways that could be foot guns? WDYT?

[yaroslavborbat]

Hi @chrischdi! I'll add test coverage for this soon.

This approach works for description and should also work for other fields. CRD markers are processed last, when the full schema has already been generated, so we can traverse it recursively and modify fields as needed.

One key use case is when defining a CRD that includes imported types. Since we cannot modify or extend annotations on those types directly, this marker allows us to adjust their schema properties where necessary.

[yaroslavborbat]

Hi @JoelSpeed!
For lists like enums, you would need to specify the entire list when modifying it. The marker does not perform partial updates to list elements—it replaces the entire field.

Here’s an example of how I replaced the required list and the description:

// +kubebuilder:schemaModifier:pathPattern=/spec/testObject,required={"field1", "field2", "field3", "field4"},description="new my description"

Regarding schema validity, this marker does allow users to generate an invalid schema if used incorrectly, so it should be used with caution. At the same time, it provides additional flexibility in CRD generation. Personally, I found such a marker useful, which is why I created this PR 🙃.

[k8s-ci-robot]

PR needs rebase.

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.