Importing API types pulls in lots of dependencies

[JoelSpeed]

What steps did you take and what happened?

Create a simple program, as below and run go mod tidy:

package main

import (
	"fmt"

	capiv1beta1 "sigs.k8s.io/cluster-api/api/v1beta1"
)

func main() {
	myCluster := &capiv1beta1.Cluster{}

	fmt.Printf("My Cluster: %+v\n", myCluster)
}

This results in a go.mod with 56 dependencies. Included in this list is controller-runtime which, is also imported by a lot of consumers of the API types. controller-runtime has evolved a lot over time and, because it is being imported by the APIs currently, means that any project consuming the API types must also import the same controller-runtime as the rest of CAPI.

There are use cases where, building a consumer, I do not need to use any of the code (defaulting, validation etc) from CAPI and as such, do not need such a restriction on my controller-runtime version.

If we modify the way the SchemeBuilder works and move the webhooks to a separate package, then we can reduce the required imports for the API package down to just 31 dependencies, and, these dependencies do not include controller-runtime or other fast moving/changing packages. There are still obviously a good number of deps in there from K8s paths, but these are mostly API machinery related and have pretty stable APIs.

I think if we can separate the webhooks out in this way (I notice Cluster and ClusterClass already are?) then I think this would make consuming these API types in other projects a lot easier.

Note how k8s.io/api does not include much code with the API types for this reason as well.

The alternative solution for consumers is to copy/paste the types out to their own repos which is less ideal.

What did you expect to happen?

API types should not be tied to many dependencies, especially not controller-runtime.

Cluster API version

main branch

Kubernetes version

N/A

Anything else you would like to add?

No response

Label(s) to be applied

/kind bug
One or more /area label. See https://github.com/kubernetes-sigs/cluster-api/labels?q=area for the list of labels.

TODO

• Update schemebuilder in ./api (🌱 Remove reliance on controller-runtime scheme builder #9045)
• Update schemebuilder in ./controlplane/kubeadm/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Update schemebuilder in ./bootstrap/kubeadm/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Update schemebuilder in ./exp/api (🌱 Remove reliance on controller-runtime scheme builder for experimental APIs #9185)
• Update schemebuilder in ./exp/addons/api (🌱 Remove reliance on controller-runtime scheme builder for experimental APIs #9185)
• Update schemebuilder in ./exp/ipam/api (🌱 Remove reliance on controller-runtime scheme builder for experimental APIs #9185)
• Update schemebuilder in ./exp/runtime/api (🌱 Remove reliance on controller-runtime scheme builder for experimental APIs #9185)
• Update schemebuilder in ./cmd/clusterctl/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Update schemebuilder in ./test/infrastructure/docker/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Update schemebuilder in ./test/infrastructure/docker/exp/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Update schemebuilder in ./test/infrastructure/inmemory/api (🌱 Remove reliance on controller-runtime scheme builder for remaining API groups #9266)
• Move webhooks for ./api (🌱 Move API v1beta1 webhooks to a separate package #9047)
• Move webhooks for ./controlplane/kubeadm/api (🌱 Move Kubeadm API v1beta1 webhooks to separate package #9410)
• Move webhooks for ./bootstrap/kubeadm/api (🌱 Move Kubeadm API v1beta1 webhooks to separate package #9410)
• Move webhooks for ./exp/api (🌱 Move experimental API v1beta1 webhooks to separate package #9417)
• Move webhooks for ./exp/addons/api (🌱 Move experimental addons API v1beta1 webhooks to separate package #9438)
• [ ] Move webhooks for ./exp/ipam/api (N/A)
• [ ] Move webhooks for ./exp/runtime/api (N/A)
• [ ] Move webhooks for ./cmd/clusterctl/api (N/A)
• Move webhooks for ./test/infrastructure/docker/api (🌱 Move docker infrastructure API v1beta1 webhooks to separate package  #9458)
• Move webhooks for ./test/infrastructure/docker/exp/api (🌱 Move docker infrastructure experimental API v1beta1 webhooks to separate package #9460)
• Move webhooks for ./test/infrastructure/inmemory/api (🌱 Move inmemory infrastructure API v1beta1 webhooks to separate package #9459)
• Add verification to avoid regressions (e.g. 🌱 Remove the dependency on cluster-api/utils from addons API #9482 (comment))
• Ensure docs for provider implementation explain schemebuilder conventions
• Ensure docs for provider implementation explain separate webhooks conventions
• Add import-boss to prevent regressions
  • ./api 🌱 Add verify-import-restrictions to enforce import restrictions #9407
  • enforce the restrictions in all packages (as soon as we can) (@Ankitasw) 🌱 Enforce import restrictions in all API packages #9461

[vincepri]

/triage accepted

[vincepri]

This all sounds good, a few additional comments would be:

• We should have a clear way on how to structure webhooks in our API packages across Cluster API and its ecosystem of providers
• Separate the SchemeBuilder changes from the webhook ones
• Open an issue in Kubebuilder to potentially change the default way new projects or packages are generated

Thoughts?
cc @CecileRobertMichon @fabriziopandini @sbueringer

[JoelSpeed]

We should have a clear way on how to structure webhooks in our API packages across Cluster API and its ecosystem of providers

Agreed, I don't have context on why Cluster and ClusterClass are separate, but, their pattern works well. Do you think we need to have versioned defaulting/validation? If so, does it make sense to have the webhooks in versioned packages as in my POC branch?

If they don't need to be versioned, having them centrally as for Cluster and ClusterClass would work.

Separate the SchemeBuilder changes from the webhook ones

Ack yes, I can make a PR for this separately so it's considered as a different part of the same effort

---

I think it would be good to have a consistent approach across CAPI and the related repos, if there is a pattern we can come up with that we can document then I would like to also pursue updating the provider APIs to mitigate this issue there as well

[sbueringer]

Agreed, I don't have context on why Cluster and ClusterClass are separate, but, their pattern works well. Do you think we need to have versioned defaulting/validation? If so, does it make sense to have the webhooks in versioned packages as in my POC branch?

The reason why Cluster and ClusterClass are separate is the following:

• we couldn't just implement the Validate / Default methods on the types directly because we needed a client in those webhooks
• So we already had to use CustomDefaulter / CustomValidator
• I didn't want to add even more dependecies to our API package so I suggested to move them to a separate package

I agree that we can just follow the same pattern for all webhooks.

If they don't need to be versioned, having them centrally as for Cluster and ClusterClass would work.

The validate / default funcs / webhooks don't have to be versioned. Whenever we introduced a new apiVersion we moved the methods from the previous apiVersion to the new one :).

So overall sounds good to me. I'm absolutely in favor!

[CecileRobertMichon]

+1

Agree anything we can do to limit importing controller-runtime only where necessary is an improvement

[enxebre]

+1, thanks for creating this Joel. I find having the ability to vendor the API cleanly critical for consumers and to ease adoption of the project.
I think reducing the gomod hard dep on webhooks and solve it generically makes total sense and is a step in the right direction.
For ref old discussion on this topic.

[sbueringer]

We discussed this issue at the backlog grooming on Oct 29th 2021, the consensus was that for now we're not able to fully decouple our API types from the controller runtime dependencies due to conversion webhooks which are strictly tied to our types.
#3465 (comment)

Just to double-check. I think I might have brought this up at the time. If I now take a look at our current code this doesn't seem to be an issue as as we only depend on "sigs.k8s.io/controller-runtime/pkg/conversion" (for conversion.Hub) in old apiVersions. So it won't be a problem for cleaning up dependencies of the latest apiVersion (which I assume is our main goal).

[fabriziopandini]

+1 from my side, thanks for reviving this discussion @JoelSpeed!

[JoelSpeed]

I did a bit of work on the code for this today and came across a small issue.

Currently the package internal/test/builder imports the defaulting functions from clusterv1, if we move these to webhooks, it creates an import cycle because the tests are importing the internal/test/builder to run tests on the webhooks.

I can see 3 possible paths forward:

• Keep the Default() functions inside the clusterv1 package and require that they do not use any import from controller-runtime (not ideal, don't know that this is even possible)
• Remove the defaulting bit from the builder (it's for MHC and MD) and handle the defaulting in the tests where those are needed (there are 9 instances for MHC, 1 for MD)
• Try to move the webhook tests to a separate go package, webhooks_test, which may solve the issue as well (loses access to private functions)

Any preferred method from those or alternative suggestions from anyone?

[killianmuldoon]

Remove the defaulting bit from the builder (it's for MHC and MD) and handle the defaulting in the tests where those are needed (there are 9 instances for MHC, 1 for MD)

From a quick look it should be relatively easy to move the defaulting to the tests themselves rather than the builders. There's only a few instances of this usage. @chrischdi - I think you added this when moving these tests to envtest, is there something I'm not thinking of that could stand in the way?

[JoelSpeed]

Remove the defaulting bit from the builder (it's for MHC and MD) and handle the defaulting in the tests where those are needed (there are 9 instances for MHC, 1 for MD)

Going to play with this idea then, will report back if I hit more issues. Expect some PRs over the coming days