Skip to content

✨ feat: add kubebuilder:externalDoc marker#1335

Open
pedjak wants to merge 1 commit intokubernetes-sigs:mainfrom
pedjak:externaldocs-marker
Open

✨ feat: add kubebuilder:externalDoc marker#1335
pedjak wants to merge 1 commit intokubernetes-sigs:mainfrom
pedjak:externaldocs-marker

Conversation

@pedjak
Copy link

@pedjak pedjak commented Feb 12, 2026 •
edited
Loading

Implement the kubebuilder:externalDoc marker to allow specifying external documentation (url and description) on fields and types, populating the externalDocs field in the generated OpenAPI schema.

The url field is required and validated to be a well-formed URL.
The description field is optional.

Ref: https://spec.openapis.org/oas/v3.0.0.html#external-documentation-object

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

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

k8s-ci-robot commented Feb 12, 2026

Welcome @pedjak!

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 k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Feb 12, 2026
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Feb 12, 2026

Hi @pedjak. 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.

Details

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
Copy link
Contributor

k8s-ci-robot commented Feb 12, 2026

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: pedjak
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.

Details 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 size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 12, 2026
@pedjak pedjak changed the title feat: add kubebuilder:externalDoc marker ✨ feat: add kubebuilder:externalDoc marker Feb 12, 2026
@pedjak
Copy link
Author

pedjak commented Feb 12, 2026

Related to kubernetes/kubernetes#136988 and kubernetes/kubernetes#136977

@sttts
Copy link
Contributor

sttts commented Feb 12, 2026

/ok-to-test

@k8s-ci-robot k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Feb 12, 2026
@sttts
Copy link
Contributor

sttts commented Feb 12, 2026

Lgtm.

@camilamacedo86 camilamacedo86 mentioned this pull request Feb 13, 2026
Closed
@pedjak
Copy link
Author

pedjak commented Feb 13, 2026

The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:
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.

It looks like there is an infra issue with the failed job:

 + curl -sL https://storage.googleapis.com/kubebuilder-tools/kubebuilder-tools-1.11.0-linux-amd64.tar.gz -o /tmp/kubebuilder-tools-1.11.0-linux-amd64.tar.gz
+ tar -zvxf /tmp/kubebuilder-tools-1.11.0-linux-amd64.tar.gz -C /tmp/
gzip: stdin: not in gzip format
tar: Child returned status 1
tar: Error is not recoverable: exiting now
make[1]: *** [Makefile:90: test] Error 2

I can even reproduce it locally.

JoelSpeed
JoelSpeed reviewed Feb 13, 2026
View reviewed changes
pkg/crd/testdata/external_docs/types.go Outdated

// This field has a doc comment link definition.
//
// [Link Def Docs]: https://example.com/link-def
Copy link
Contributor

@JoelSpeed JoelSpeed Feb 13, 2026

Choose a reason for hiding this comment

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

Why do we need to support this syntax instead of just supporting the explicit markers?

Copy link
Author

@pedjak pedjak Feb 13, 2026

Choose a reason for hiding this comment

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

I thought it is a nice add-on, given that many projects today put already links in godoc. This would allows us to find them and put them as externalDocs structure. If you think it could be surprising to users, we could enable this behavior with a command line flag?

Copy link
Contributor

@JoelSpeed JoelSpeed Feb 13, 2026

Choose a reason for hiding this comment

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

I'd prefer we didn't carry this complexity at all if I'm honest. We don't have existing behaviour like this, everything is explicitly part of the markers and I think we should probably stick to that pattern

CC @sbueringer @alvaroaleman keep me honest here

Copy link
Member

@sbueringer sbueringer Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Agree. I also would prefer to only use markers for this

Copy link
Author

@pedjak pedjak Feb 13, 2026

Choose a reason for hiding this comment

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

Agree. I also would prefer to only use markers for this

done, ptal.

Copy link
Author

@pedjak pedjak Feb 13, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

I'd prefer we didn't carry this complexity at all if I'm honest. We don't have existing behaviour like this, everything is explicitly part of the markers and I think we should probably stick to that pattern

I have removed godoc link parsing, but just got an idea: how about that we control the link source via an additional parameter, e.g.:

// +kubebuilder:externalDoc:fromComment

or simply just

// +kubebuilder:externalDoc

and then we look into godoc comment for links? wdyt @JoelSpeed ? This enables users to keep links in the single place, without duplication.

@sbueringer
Copy link
Member

sbueringer commented Feb 13, 2026 •
edited
Loading

@pedjak Yes, please see #1334 (comment) for more details

@sbueringer sbueringer closed this Feb 13, 2026
@sbueringer sbueringer reopened this Feb 13, 2026
@tmshort
Copy link

tmshort commented Feb 13, 2026

/test pull-controller-tools-test-main

@pedjak @claude
feat: add kubebuilder:externalDoc marker
3abdb9c 
Implement the `kubebuilder:externalDoc` marker to allow specifying
external documentation (url and description) on fields and types,
populating the externalDocs field in the generated OpenAPI schema.

The url field is required and validated to be a well-formed URL.
The description field is optional.

Ref: https://spec.openapis.org/oas/v3.0.0.html#external-documentation-object

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@pedjak pedjak force-pushed the externaldocs-marker branch from 1694f3d to 3abdb9c Compare February 13, 2026 15:54
@pedjak pedjak requested a review from JoelSpeed February 13, 2026 15:56
@sbueringer
Copy link
Member

sbueringer commented Feb 13, 2026

/retest

@sbueringer
Copy link
Member

sbueringer commented Feb 13, 2026

/lgtm

/assign @JoelSpeed

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 13, 2026
@k8s-ci-robot
Copy link
Contributor

k8s-ci-robot commented Feb 13, 2026

LGTM label has been added.

DetailsGit tree hash: d2461f42e581c3dba6601b03e7f27ad863bf0e73

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

Reviewers

@sbueringer sbueringer Awaiting requested review from sbueringer

@JoelSpeed JoelSpeed Awaiting requested review from JoelSpeed

Assignees

@sbueringer sbueringer

@JoelSpeed JoelSpeed

Labels

cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. lgtm "Looks good to me", indicates that a PR is ready to be merged. ok-to-test Indicates a non-member PR verified by an org member that is safe to test. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@pedjak @k8s-ci-robot @sttts @sbueringer @tmshort @JoelSpeed