Doc available plugins provided by Kubebuilder

[camilamacedo86]

What do you want to happen?

We have the Plugins section on the docs https://book.kubebuilder.io/plugins/plugins.html but it only covers how the architecture works. Therefore, the idea of this issue would be we ensure that we have a section and a doc for each plugin which is provided by the tool which would cover such as:

• What is the purpose of the plugin? When/why it should be used
• What are the commands implemented/supported by the plugin ( a plugin can implement only the create API or init subcommand )
• Add examples, we can link what we have under testdata for e.g.

Extra Labels

No response

[Ashwin901]

Hi @camilamacedo86 I would like to work on this issue as I have been learning and exploring about plugins lately. From what I have observed there is a kustomize plugin in the commons folder and declarative, v2 , v3 plugin in the golang folder. Should there be a separate subsection for all these plugins? And also are there any plugins that I have missed?

[camilamacedo86]

We are open to ideas and proposals for these docs.

IHMO we need to ensure that:

a) (Under the plugin section) we would have a subsection such as "Available Plugins" where: we will clarify that this section describes all plugins which are shipped with the KB project and that those are officially supported by KB. (these ones that you highlighted). However, any person can create their own plugins to work with KB. See:

• https://book.kubebuilder.io/plugins/creating-plugins.html
• https://github.com/kubernetes-sigs/kubebuilder/issues/1378: allow the Kubebuilder CLI or any other CLI, which is Extending the Kubebuilder CLI, to discover external plugins, in this way, allow the users to use these external options as helpers to perform the scaffolds with the tool.

Maybe would be nice here we move for it the content from https://github.com/kubernetes-sigs/kubebuilder/blob/master/VERSIONING.md#versioning.

b) We have a subsection for each plugin that is officially supported/ distribute with KB binary: ( declarative/v1, go/v2 , go/v3 plugin). In this subsection we would cover each case:

• What is the purpose of the plugin
• When the plugin can/should be used
• What are the interfaces/SubCommands available for each case scenario ( for example the declarative only implements create API and init )

Maybe something like

• Overview: (describes what is the plugin and its purpose)
• When should I use it: (e.g. for go/v2: If you want scaffold Go projects which have not backwards compatible with the Kubebuilder layout >= 2.0.0 and < 3.0.0 )
• SubCommand available (e.g for the declarative we can explain that by using it in the init all APIs created afterwards will be scaffolded with the reconciling and etc following its pattern (see the addon sample: https://github.com/kubernetes-sigs/kubebuilder/tree/master/testdata/project-v3-addon and its controllers). Also, we can create a specific API informing this plugin.)

[Ashwin901]

Thanks for the clarification. /assign

[mariuskimmina]

Hey,

I have also been interessted in this, maybe we can split the work and collaborate on this?

In general I think It might make sense to create and seperate Issue for each plugin that should be documented so that the details can be discussed and a PR for each plugin documentation can be linked to an exact issue? - Writing the documentation for all plugins seems a bit overwhelming to me, as a single task.

I would for example like to cover the declarative plugin if that is okay with you @Ashwin901?

[Ashwin901]

Hey @mariuskimmina, you can work on the declarative plugin. Are you going to create a new issue for it ?

[Ashwin901]

Hey @camilamacedo86, in the purpose section of the plugin what exactly should be included? For example for go/v3 plugin should we just mention that this plugin is used to generate the boilerplate code for the custom resource and the controller?

[camilamacedo86]

HI @Ashwin901,

My thoughts here were, see: https://github.com/kubernetes-sigs/kubebuilder/issues/2542#issuecomment-1073687108 But it is also open to ideas.

[Ashwin901]

Hey @mariuskimmina can you please let me know if you are working on the declarative plugin?

[mariuskimmina]

Yes, I am working on the documentation for it and hope to send a PR in the next couple of days.

[camilamacedo86]

It shows done now: https://book.kubebuilder.io/plugins/available-plugins.html So, I am closing this one