move webhooks away from api folder

[malt3]

What do you want to happen?

This may be seen as an extension to #2627. I want projects to not place webhook handlers and envtests in the api folder.

Instead, webhooks should be moved into the controllers folder (or into a completely separate folder).
This allows external projects to import the api module without importing envtest libraries.

Extra Labels

No response

[camilamacedo86]

Hi @malt3,

I would like to suggest you read the PR #3055 and the comment #2627 (comment) as #2627 (comment). You can see that those who raise the idea after their experiment realize that it is not a good option and decide that it would be better addressed by documentation.

I want projects to not place webhook handlers and envtests in the api folder.
Instead, webhooks should be moved into the controllers folder (or into a completely separate folder).

• Are webhook controllers? So, why should it be in the controller's folder?
• When you say envtest, I understand that you are speaking about the webhook tests so they must to be kept with the webhooks.

Therefore, I'd like to raise a few questions:

• a) What would you like to do that is impossible with the current layout?
• b) Why/when do you think that changing the layout would be beneficial? For what use case?
• c) What would be the technical/good practice argumentation to have the webhooks in another folder? Could you please provide some references?
• d) How could this change be beneficial for all standard cases? what would be the pros and cons?

[varshaprasad96]

@malt3 We would like to look into this issue in-depth to accept this as feature. Assigning this to myself to take a look.

[malt3]

Hello,

I will try to answer the open questions.

Are webhook controllers? So, why should it be in the controller's folder?

You are right. Depending on your viewpoint, webhooks may not be seen as controllers. However, webhooks have handlers (private implementation only used by the operator that is not required for other projects that may import the api folder). Placing the implementation and tests of webhooks into a new folder may also be an option.

When you say envtest, I understand that you are speaking about the webhook tests so they must to be kept with the webhooks.

I agree. The webhook envtests should live in the same folder as the webhooks. This means they should be moved together, away from the api folder.

a) What would you like to do that is impossible with the current layout?

Have operators that use multiple go.mod files (one just for the api folder), and import the api folder of one operator in the implementation of another operator. This does not have to be the default, but should be possible.
Currently, this means I have to upgrade a lot of dependencies for all of my operators in sync, since I have to import envtest and other dependencies that are not required for the actual API structs I want to import.

b) Why/when do you think that changing the layout would be beneficial? For what use case?

For operators that use kubebuilder and also use go workspaces. And to allow imports of API modules of other open source operators without having to also depend on their version of envtest and other imports that are currently in the api folder.

c) What would be the technical/good practice argumentation to have the webhooks in another folder? Could you please provide some references?

A general best practice for go packages: If a package/module is meant to be imported by other modules, it should only import what is needed to consume the public api.

The package/module api holds structs that form the public api of the operator. Currently, this folder also holds the implementation and tests of webhooks.

The reconcile loops for custom resources live in controllers so this is already designed well for this part of the implementation.

d) How could this change be beneficial for all standard cases? what would be the pros and cons?

This would have negligible impact for the standard case (only one go.mod).

Pros:

• separation between public API <--> webhook handlers / webhook envtests
• allows users of go workspaces to only inherit required dependencies for struct definitions

Cons:

• existing operators will have to migrate to the new layout

[camilamacedo86]

Hi @n1r1,

It is a very interesting thought. However, we just released go/v4 stable. Therefore, any change in the layout (breaking change) like this one can only be addressed in the new version, which would be go/v5.

I am adding this one to the go/v5 milestone, and when we have a significant number of changes that justify we getting started with the new layout, we can discuss this request. I hope that can be fine.

[camilamacedo86]

It seems the others are either looking for this one: #3721 (comment)

Motivation: Allow to import only APIs from a project to another without webhooks

(IMO) However, before we start working in a go/v5 we will need to:

• a) Todo a release supporting k8s 1.29
• b) Remove all deprecations and clean up all and then do a new release; ⚠️ Upcoming Major Version Release for Kubebuilder with the next k8s 1.29 release - Action Required #3622

Then, we can start to work within a go/v5 alpha, but we will only be able to make it stable and the default scaffold once we have enough changes to do so.

c/c @@nathanperkins

[nathanperkins]

Thanks for bringing this up. I want to stress how important this kind of change is to the community health at large. When projects include controller-runtime code (like webhook implementations) in their public API packages, any breaking change in that controller-runtime code creates a version barrier in which projects on either side of the barrier can't import each other's APIs.

The suggested change here is the only way to fix the issue so that it doesn't reoccur whenever there are breaking changes.

[camilamacedo86]

I am closing this one in favor of #4062
where we are better centralizing all motivations.