Improve ClusterCacheTracker to address fundamental limitations

[sbueringer]

Over time the ClusterCacheTracker evolved significantly. While it generally improved we have a few systematic issues that we should solve:

• the current locking and client creation behavior is not good, whenever a reconciler calls GetClient it has a chance to be stuck for 10 seconds if the wl cluster is unreachable (because then GetClient might tries to create a client and then times out after 10s). While one reconciler tries to create a client other reconcilers will permanently requeue (currently with requeueAfter 1m). See also https://github.com/kubernetes-sigs/cluster-api/issues/10819
• I think in general there is a huge potential to make the locking smarter
• the current health checking code starts 1 go routine for every cluster (so 1k clusters => 1k health check goroutines)
• ClusterCacheTracker requires to also add the ClusterCache reconcile to the manager. Because ClusterCache reconcile is a separate component that is easily forgotten

I probably missed a few :)

We also have some additional requirements:

• We want to expose some information about the health checking state so that controllers can tell when the connection to the wl cluster broke and e.g. set the RemoteConnectionProbe condition accordingly (xref: https://github.com/kubernetes-sigs/cluster-api/pull/10897)

Tasks:

• [x] Implement new version of ClusterCacheTracker (called ClusterCache): https://github.com/kubernetes-sigs/cluster-api/pull/11247

Follow-up Tasks:

• [x] [P0] Add panic metric validation to envtest package so we have it everywhere: https://github.com/kubernetes-sigs/cluster-api/pull/11279
• [x] [P0] Deprecate the old ClusterCacheTracker: https://github.com/kubernetes-sigs/cluster-api/pull/11312
• [ ] [P1] Remove requeues on "ErrClusterNotConnected" in other reconcilers
  • Run some scale e2e tests to verify (including checking some Go profiles while we're at it)
• [x] [Cleanup] Input validation & get rid of r.ClusterCache == nil checks
  • [x] Add input validation to all SetupWithManager funcs for stuff like Client, ClusterCache, SecretCachingClient: #11327
  • [x] Get rid of r.ClusterCache == nil checks machine_controller.go & machinehealthcheck_controller.go: #11336
• [x] https://github.com/kubernetes-sigs/cluster-api/pull/11331
• [ ] Add metrics based on health checking data & connection state (previous issue: https://github.com/kubernetes-sigs/cluster-api/issues/7147)

Backlog:

• [ ] Consider exposing and using ReaderFailOnMissingInformer cache option
• [ ] Consider more sophisticated backoff behavior for connection creation (unclear if necessary / wanted)
• [ ] Consider making ClusterCache a generic cache per cluster, e.g. for:
  • etcd client certs (to replace GetClientCertificatePrivateKey)
  • Potentially also just use one private key for KCP instead of one per-Cluster (we can also consider rotating this one key if necessary)
  • but also maybe other stuff like drain cache
  • Important! Must be safe against deadlocks!

[sbueringer]

/area clustercachetracker /triage accepted