feat: add pkg/controller/ctrlutil package

Add controller utility package with client, constants, errors,
reconcile_result, utils and fakes.

Made-with: Cursor

Author: Anand Kumar

pkg/controller/ctrlutil/client.go

@@ -0,0 +1,150 @@
+package ctrlutil
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+
+	"k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/client-go/util/retry"
+
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/manager"
+)
+
+var errFailedToConvertToClientObject = fmt.Errorf("failed to convert to client.Object")
+
+// ctrlClientImpl implements the CtrlClient interface using the manager's client.
+type ctrlClientImpl struct {
+	client.Client
+}
+
+// CtrlClient defines the interface for controller client operations.
+//
+//go:generate go run github.com/maxbrunsfeld/counterfeiter/v6 -generate
+//counterfeiter:generate -o fakes . CtrlClient
+type CtrlClient interface {
+	Get(context.Context, client.ObjectKey, client.Object) error
+	List(context.Context, client.ObjectList, ...client.ListOption) error
+	StatusUpdate(context.Context, client.Object, ...client.SubResourceUpdateOption) error
+	Update(context.Context, client.Object, ...client.UpdateOption) error
+	UpdateWithRetry(context.Context, client.Object, ...client.UpdateOption) error
+	Create(context.Context, client.Object, ...client.CreateOption) error
+	Delete(context.Context, client.Object, ...client.DeleteOption) error
+	Patch(context.Context, client.Object, client.Patch, ...client.PatchOption) error
+	Exists(context.Context, client.ObjectKey, client.Object) (bool, error)
+}
+
+// NewClient creates a new controller client from the manager.
+// Use the manager's client directly instead of creating a custom client.
+// The manager's client uses the manager's cache, which ensures the reconciler
+// reads from the same cache that the controller's watches use, preventing
+// cache mismatch issues.
+func NewClient(m manager.Manager) (CtrlClient, error) {
+	return &ctrlClientImpl{
+		Client: m.GetClient(),
+	}, nil
+}
+
+func (c *ctrlClientImpl) Get(
+	ctx context.Context, key client.ObjectKey, obj client.Object,
+) error {
+	if err := c.Client.Get(ctx, key, obj); err != nil {
+		return fmt.Errorf("failed to get object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) List(
+	ctx context.Context, list client.ObjectList, opts ...client.ListOption,
+) error {
+	if err := c.Client.List(ctx, list, opts...); err != nil {
+		return fmt.Errorf("failed to list objects: %w", err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) Create(
+	ctx context.Context, obj client.Object, opts ...client.CreateOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := c.Client.Create(ctx, obj, opts...); err != nil {
+		return fmt.Errorf("failed to create object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) Delete(
+	ctx context.Context, obj client.Object, opts ...client.DeleteOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := c.Client.Delete(ctx, obj, opts...); err != nil {
+		return fmt.Errorf("failed to delete object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) Update(
+	ctx context.Context, obj client.Object, opts ...client.UpdateOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := c.Client.Update(ctx, obj, opts...); err != nil {
+		return fmt.Errorf("failed to update object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) UpdateWithRetry(
+	ctx context.Context, obj client.Object, opts ...client.UpdateOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
+		currentInterface := reflect.New(reflect.TypeOf(obj).Elem()).Interface()
+		current, ok := currentInterface.(client.Object)
+		if !ok {
+			return errFailedToConvertToClientObject
+		}
+		if err := c.Client.Get(ctx, key, current); err != nil {
+			return fmt.Errorf("failed to fetch latest %q for update: %w", key, err)
+		}
+		obj.SetResourceVersion(current.GetResourceVersion())
+		if err := c.Client.Update(ctx, obj, opts...); err != nil {
+			return fmt.Errorf("failed to update %q resource: %w", key, err)
+		}
+		return nil
+	}); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func (c *ctrlClientImpl) StatusUpdate(
+	ctx context.Context, obj client.Object, opts ...client.SubResourceUpdateOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := c.Client.Status().Update(ctx, obj, opts...); err != nil {
+		return fmt.Errorf("failed to update status for object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) Patch(
+	ctx context.Context, obj client.Object, patch client.Patch, opts ...client.PatchOption,
+) error {
+	key := client.ObjectKeyFromObject(obj)
+	if err := c.Client.Patch(ctx, obj, patch, opts...); err != nil {
+		return fmt.Errorf("failed to patch object %q: %w", key, err)
+	}
+	return nil
+}
+
+func (c *ctrlClientImpl) Exists(ctx context.Context, key client.ObjectKey, obj client.Object) (bool, error) {
+	if err := c.Client.Get(ctx, key, obj); err != nil {
+		if errors.IsNotFound(err) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}

pkg/controller/ctrlutil/constants.go

@@ -0,0 +1,6 @@
+package ctrlutil
+
+// ManagedResourceLabelKey is the common label key used by all operand controllers
+// to identify resources they manage. Each controller uses a different value
+// to distinguish its resources.
+const ManagedResourceLabelKey = "app"

pkg/controller/ctrlutil/errors.go

@@ -0,0 +1,123 @@
+package ctrlutil
+
+import (
+	"errors"
+	"fmt"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+)
+
+// ErrorReason represents the reason for a reconciliation error.
+type ErrorReason string
+
+const (
+	// IrrecoverableError indicates an error that cannot be recovered by retrying.
+	IrrecoverableError ErrorReason = "IrrecoverableError"
+
+	// RetryRequiredError indicates an error that may be recovered by retrying.
+	RetryRequiredError ErrorReason = "RetryRequiredError"
+
+	// MultipleInstanceError indicates that multiple singleton instances exist.
+	MultipleInstanceError ErrorReason = "MultipleInstanceError"
+)
+
+// ReconcileError represents an error that occurred during reconciliation.
+type ReconcileError struct {
+	Reason  ErrorReason `json:"reason,omitempty"`
+	Message string      `json:"message,omitempty"`
+	Err     error       `json:"error,omitempty"`
+}
+
+var _ error = &ReconcileError{}
+
+// NewIrrecoverableError creates a new irrecoverable error.
+func NewIrrecoverableError(err error, message string, args ...any) *ReconcileError {
+	if err == nil {
+		return nil
+	}
+	return &ReconcileError{
+		Reason:  IrrecoverableError,
+		Message: fmt.Sprintf(message, args...),
+		Err:     err,
+	}
+}
+
+// NewMultipleInstanceError creates a new multiple instance error.
+func NewMultipleInstanceError(err error) *ReconcileError {
+	if err == nil {
+		return nil
+	}
+	return &ReconcileError{
+		Reason:  MultipleInstanceError,
+		Message: fmt.Sprint(err.Error()),
+		Err:     err,
+	}
+}
+
+// NewRetryRequiredError creates a new error that requires retry.
+func NewRetryRequiredError(err error, message string, args ...any) *ReconcileError {
+	if err == nil {
+		return nil
+	}
+	return &ReconcileError{
+		Reason:  RetryRequiredError,
+		Message: fmt.Sprintf(message, args...),
+		Err:     err,
+	}
+}
+
+// FromClientError creates a ReconcileError from a Kubernetes client error.
+func FromClientError(err error, message string, args ...any) *ReconcileError {
+	if err == nil {
+		return nil
+	}
+	if apierrors.IsUnauthorized(err) || apierrors.IsForbidden(err) || apierrors.IsInvalid(err) ||
+		apierrors.IsBadRequest(err) || apierrors.IsServiceUnavailable(err) {
+		return NewIrrecoverableError(err, message, args...)
+	}
+
+	return NewRetryRequiredError(err, message, args...)
+}
+
+// FromError creates a ReconcileError from a generic error.
+func FromError(err error, message string, args ...any) *ReconcileError {
+	if err == nil {
+		return nil
+	}
+	if IsIrrecoverableError(err) {
+		return NewIrrecoverableError(err, message, args...)
+	}
+	return NewRetryRequiredError(err, message, args...)
+}
+
+// IsIrrecoverableError checks if the error is an irrecoverable error.
+func IsIrrecoverableError(err error) bool {
+	rerr := &ReconcileError{}
+	if errors.As(err, &rerr) {
+		return rerr.Reason == IrrecoverableError
+	}
+	return false
+}
+
+// IsRetryRequiredError checks if the error requires retry.
+func IsRetryRequiredError(err error) bool {
+	rerr := &ReconcileError{}
+	if errors.As(err, &rerr) {
+		return rerr.Reason == RetryRequiredError
+	}
+	return false
+}
+
+// IsMultipleInstanceError checks if the error is a multiple instance error.
+func IsMultipleInstanceError(err error) bool {
+	rerr := &ReconcileError{}
+	if errors.As(err, &rerr) {
+		return rerr.Reason == MultipleInstanceError
+	}
+	return false
+}
+
+// Error implements the error interface.
+func (e *ReconcileError) Error() string {
+	return fmt.Sprintf("%s: %s", e.Message, e.Err)
+}