Skip to content

✨ feat: add kubebuilder:externalDoc marker#1335

Merged
k8s-ci-robot merged 1 commit intokubernetes-sigs:mainfrom
pedjak:externaldocs-marker
Feb 17, 2026
Merged

✨ feat: add kubebuilder:externalDoc marker#1335
k8s-ci-robot merged 1 commit intokubernetes-sigs:mainfrom
pedjak:externaldocs-marker

Conversation

@pedjak
Copy link
Copy Markdown
Contributor

@pedjak pedjak commented Feb 12, 2026 •
edited
Loading

Implement the kubebuilder:externalDocs 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
Copy Markdown
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
Copy Markdown
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 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
Copy Markdown
Contributor Author

pedjak commented Feb 12, 2026

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

@sttts
Copy link
Copy Markdown
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
Copy Markdown
Contributor

sttts commented Feb 12, 2026

Lgtm.

@camilamacedo86 camilamacedo86 mentioned this pull request Feb 13, 2026
Closed
@pedjak
Copy link
Copy Markdown
Contributor 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
Comment thread 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
Copy Markdown
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
Copy Markdown
Contributor 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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Contributor 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
Copy Markdown
Contributor 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
Copy Markdown
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
Copy Markdown

tmshort commented Feb 13, 2026

/test pull-controller-tools-test-main

@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
Copy Markdown
Member

sbueringer commented Feb 13, 2026

/retest

@sbueringer
Copy link
Copy Markdown
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
Copy Markdown
Contributor

k8s-ci-robot commented Feb 13, 2026

LGTM label has been added.

DetailsGit tree hash: d2461f42e581c3dba6601b03e7f27ad863bf0e73

@pedjak @claude
feat: add kubebuilder:externalDocs marker
916f3ca 
Implement the `kubebuilder:externalDocs` 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 3abdb9c to 916f3ca Compare February 16, 2026 14:58
@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 16, 2026
@sbueringer
Copy link
Copy Markdown
Member

sbueringer commented Feb 17, 2026

Thx!

/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 17, 2026
@k8s-ci-robot
Copy link
Copy Markdown
Contributor

k8s-ci-robot commented Feb 17, 2026

LGTM label has been added.

DetailsGit tree hash: 562399acd597b937bc03d365dbd3da493e020880

@JoelSpeed
Copy link
Copy Markdown
Contributor

JoelSpeed commented Feb 17, 2026

/approve

Thanks @pedjak

@k8s-ci-robot
Copy link
Copy Markdown
Contributor

k8s-ci-robot commented Feb 17, 2026

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: JoelSpeed, pedjak

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

The pull request process is described 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 approved Indicates a PR has been approved by an approver from all required OWNERS files. label Feb 17, 2026
@k8s-ci-robot k8s-ci-robot merged commit 6e62937 into kubernetes-sigs:main Feb 17, 2026
11 checks passed
shubham-sumo added a commit to SumoLogic/tailing-sidecar that referenced this pull request Feb 22, 2026
@shubham-sumo
feat: add setup-envtest.sh file from kubernetes-sigs repo
02c89fe 
Copied script from kubernetes-sigs repo and changed the url of envtest tools to point to github releases directly instead of google storage api
More Info: kubernetes-sigs/controller-tools#1335 (comment)
@shubham-sumo shubham-sumo mentioned this pull request Feb 22, 2026
Merged
shubham-sumo added a commit to SumoLogic/tailing-sidecar that referenced this pull request Feb 23, 2026
@shubham-sumo
feat: add envtest script locally (#833)
5988950 
* chore: upgrade sumo-otel-collector version

* chore: upgrade base image(alpine) to latest version

* feat: add setup-envtest.sh file from kubernetes-sigs repo

Copied script from kubernetes-sigs repo and changed the url of envtest tools to point to github releases directly instead of google storage api
More Info: kubernetes-sigs/controller-tools#1335 (comment)

* feat: update makefile to use script from this repo

* fix: fix path
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

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. 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