kubebuilder
kubebuilder copied to clipboard
kubernetes-sigs
Documentation needed for `+kubebuilder:scaffold` markers
Hi!
Please add documentation about the +kubebuilder:scaffold markers.
I came across this in the main.go generated file of a project I'm currently working on, where there's this line in the imports section, which apparently helps Kubebuilder put import statements there when you create new api-versions.
// +kubebuilder:scaffold:imports
Possible landing spots in CronJob tutorial or in markers reference.
Thanks to @djzager and @estroz for your help in Slack. 🙏
Cheers
/kind documentation
Note that the whole explanation about what/where we need to change is: https://github.com/kubernetes-sigs/kubebuilder/issues/1487#issuecomment-1074985232
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-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
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-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
Is there any progress about that? I still do not know about // +kubebuilder:scaffold:builder, // +kubebuilder:scaffold:scheme or // +kubebuilder:scaffold:imports. There is no such information about them.
Thanks.
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
Agree that this docs on these markers are needed. For example, what does the kubebuilder:scaffold:scheme marker do? Can I add other schemes besides the ones needed for my project's APIs?
These markers are used to insrt code with kubebuilder commands, for example when a controller is created, the main file has to include some code fragments to load it, and where to place those code fragments is marked by //+kubebuilder:scaffold:*
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
The Kubernetes project currently lacks enough 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/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Mark this issue or PR as fresh with
/remove-lifecycle stale - Mark this issue or PR as rotten with
/lifecycle rotten - Close this issue or PR with
/close - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale
What is the goal of this one? We have in the docs the info about the markers which are used by the Kubebuilder CLI to inject code.
- More info: https://github.com/kubernetes-sigs/kubebuilder/issues/1487#issuecomment-823864494 and https://github.com/kubernetes-sigs/kubebuilder/issues/1487#issuecomment-815871167
Where can I find the references to work on this one?
- The marker docs are in: https://book.kubebuilder.io/reference/markers.html
- we have not on it a section that speaks about the markers that allow us inject the fragments
//+kubebuilder:scaffold:* - The markers in the docs are generated via code built from : https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/utils/markerdocs/main.go
- Here is the code where we process the markers: https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/machinery/marker.go. See:: https://github.com/kubernetes-sigs/kubebuilder/blob/72f7c2ef3fd42d21756bc04029ecc499daee2533/pkg/machinery/scaffold.go#L334-L354
- The valid markers are implemented per plugin. a) You can check here the const for the code fragments (go/v3 ) plugin; https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/v3/scaffolds/internal/templates/main.go#L91-L121 b) You can check here the const for the code fragments (go/v2 ) plugin; https://github.com/kubernetes-sigs/kubebuilder/blob/master/pkg/plugins/golang/v2/scaffolds/internal/templates/main.go#L91-L121
Do I need to generate these docs programmatically
No. We can add the info in the docs in the best way that we see fit. It does not need to be programmatic. It would be nice if we could generate automatically from the source code and its comment but that is not a requirement.
HI @adambkaplan,
Are you working on this one? If not could you please unsigned that to you so others can try to do this one?
@camilamacedo86 unsure how I was assigned to this issue (if I ever was). I am not actively working on this issue.
It would be useful to know that these markers are only tracked by main.go because kubebuilder does not tokenize and parse the entire project to find it's scaffolding markers.
For a project I started today, my initial goal was to make sure that the same binary was used for the operator and it's utilities with a cli package call urfave.cli (this is similar to cobra.cli). I ended up having to place the operator inside it's own function and add the subcommand during init().
@cprivitere if you break out the things managed by kubebuilder in main.go out into separate file, you will have to manage them manually as far as I can tell. They wont get read from anywhere else, so there's no point in keeping them if you are managing the scaffolding yourself.
I'm afraid I don't know what that means. I'm working on code originally generated by someone else and am just trying to figure out what these do. These are in my main.go.
As an example, suppose you have a brand new operator and you only have 1 API called SomeResourceName.
$ mkdir example-operator
$ go mod init example.org
$ kubebuilder init example.org --domain example.org --owner "Bob Ross"
$ kubebuilder create api --group group-name --version v1alpha1 --kind SomeResourceName --controller true --resource true
You will have main.go. This is the only file that kubebuilder will scan for scaffolding tags. The problem is that you might want to build a single binary operator and command line tool with something like github.com/spf13/cobra or github.com/urfave/cli, where the operator is a subcommand like ./maincmd operator.
The things managed by these scaffolding tags would be:
groupnamev1alpha1 "example.org/api/v1alpha1"
"example.org/controllers"
//+kubebuilder:scaffold:imports
utilruntime.Must(groupnamev1alpha1.AddToScheme(scheme))
//+kubebuilder:scaffold:scheme
if err = (&controllers.SomeResourceNameReconciler{
Client: mgr.GetClient(),
Scheme: mgr.GetScheme(),
}).SetupWithManager(mgr); err != nil {
setupLog.Error(err, "unable to create controller", "controller", "SomeResourceName")
os.Exit(1)
}
//+kubebuilder:scaffold:builder
If you move these scaffolds elsewhere, they will be ignored by kubebuilder. You functionally end up having to manage them yourself.
Just to clarify:
The goal of this task is to implement the code that will generate the docs automatically for those markers, see; https://github.com/kubernetes-sigs/kubebuilder/issues/1487#issuecomment-1074985232