Add cluster.Aware interface to support dynamic cluster engagement

On-behalf-of: SAP [email protected]
Co-authored-by: Vince Prignano <[email protected]>
Co-authored-by: Dr. Stefan Schimanski <[email protected]>
Signed-off-by: Marvin Beckers <[email protected]>

Author: 3 people

pkg/cluster/cluster.go

@@ -37,6 +37,11 @@ import (
 
 // Cluster provides various methods to interact with a cluster.
 type Cluster interface {
+	// Name returns the name of the cluster. It identifies the cluster in the
+	// manager if that is attached to a cluster provider. The value is usually
+	// empty for the default cluster of a manager.
+	Name() string
+
 	// GetHTTPClient returns an HTTP client that can be used to talk to the apiserver
 	GetHTTPClient() *http.Client
 
@@ -75,6 +80,11 @@ type Cluster interface {
 
 // Options are the possible options that can be configured for a Cluster.
 type Options struct {
+	// name is the name of the cluster. It identifies the cluster in the manager
+	// if that is attached to a cluster provider. The value is usually empty for
+	// the default cluster of a manager.
+	Name string
+
 	// Scheme is the scheme used to resolve runtime.Objects to GroupVersionKinds / Resources
 	// Defaults to the kubernetes/client-go scheme.Scheme, but it's almost always better
 	// idea to pass your own scheme in.  See the documentation in pkg/scheme for more information.
@@ -234,6 +244,7 @@ func New(config *rest.Config, opts ...Option) (Cluster, error) {
 	}
 
 	return &cluster{
+		name:             options.Name,
 		config:           originalConfig,
 		httpClient:       options.HTTPClient,
 		scheme:           options.Scheme,
@@ -300,3 +311,13 @@ func setOptionsDefaults(options Options, config *rest.Config) (Options, error) {
 
 	return options, nil
 }
+
+// WithName sets the name of the cluster. The name can only be set once.
+func WithName(name string) Option {
+	return func(o *Options) {
+		if o.Name != "" {
+			panic("cluster name cannot be set more than once")
+		}
+		o.Name = name
+	}
+}

pkg/cluster/internal.go

@@ -32,6 +32,11 @@ import (
 )
 
 type cluster struct {
+	// name is the name of the cluster. It identifies the cluster in the manager
+	// if that is attached to a cluster provider. The value is usually empty for
+	// the default cluster of a manager.
+	name string
+
 	// config is the rest.config used to talk to the apiserver.  Required.
 	config *rest.Config
 
@@ -59,6 +64,10 @@ type cluster struct {
 	logger logr.Logger
 }
 
+func (c *cluster) Name() string {
+	return c.name
+}
+
 func (c *cluster) GetConfig() *rest.Config {
 	return c.config
 }

pkg/cluster/multicluster.go

@@ -0,0 +1,55 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package cluster
+
+import (
+	"context"
+)
+
+// Aware is an interface that can be implemented by components that
+// can engage and disengage when clusters are added or removed at runtime.
+type Aware interface {
+	// Engage gets called when the component should start operations for the given Cluster.
+	// The given context is tied to the Cluster's lifecycle and will be cancelled when the
+	// Cluster is removed or an error occurs.
+	//
+	// Implementers should return an error if they cannot start operations for the given Cluster,
+	// and should ensure this operation is re-entrant and non-blocking.
+	//
+	//	\_________________|)____.---'--`---.____
+	//              ||    \----.________.----/
+	//              ||     / /    `--'
+	//            __||____/ /_
+	//           |___         \
+	//               `--------'
+	Engage(context.Context, Cluster) error
+
+	// Disengage gets called when the component should stop operations for the given Cluster.
+	Disengage(context.Context, Cluster) error
+}
+
+// Provider defines methods to retrieve clusters by name. The provider is
+// responsible for discovering and managing the lifecycle of each cluster.
+//
+// Example: A Cluster API provider would be responsible for discovering and
+// managing clusters that are backed by Cluster API resources, which can live
+// in multiple namespaces in a single management cluster.
+type Provider interface {
+	// Get returns a cluster for the given identifying cluster name. Get
+	// returns an existing cluster if it has been created before.
+	Get(ctx context.Context, clusterName string) (Cluster, error)
+}

pkg/source/source.go

@@ -25,6 +25,7 @@ import (
 	"k8s.io/client-go/util/workqueue"
 	"k8s.io/utils/ptr"
 	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/cluster"
 	"sigs.k8s.io/controller-runtime/pkg/event"
 	"sigs.k8s.io/controller-runtime/pkg/handler"
 	internal "sigs.k8s.io/controller-runtime/pkg/internal/source"
@@ -69,6 +70,13 @@ type TypedSyncingSource[request comparable] interface {
 	WaitForSync(ctx context.Context) error
 }
 
+// TypedClusterAwareSource is a source that can be engaged and disengaged when
+// clusters are added or removed from the manager.
+type TypedClusterAwareSource[request comparable] interface {
+	TypedSource[request]
+	cluster.Aware
+}
+
 // Kind creates a KindSource with the given cache provider.
 func Kind[object client.Object](
 	cache cache.Cache,