add initial BucketAccess controller reconciliation

Add initial implementation for BucketAccess reconciliation based on
v1alpha2 KEP. This initial implementation covers only the first section
of Controller reconciliation for a new BucketAccess. Coverage ends at the
point where reconciliation is handed off to the Sidecar.

Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>

Author: BlaineEXE

client/apis/objectstorage/v1alpha2/definitions.go

@@ -16,12 +16,36 @@ limitations under the License.
 
 package v1alpha2
 
+// Finalizers
 const (
 	// ProtectionFinalizer is applied to a COSI resource object to protect it from deletion while
 	// COSI processes deletion of the object's intermediate and backend resources.
 	ProtectionFinalizer = `objectstorage.k8s.io/protection`
 )
 
+// Annotations
+const (
+	// HasBucketAccessReferencesAnnotation : This annotation is applied by the COSI Controller to a
+	// BucketClaim when a BucketAccess that references the BucketClaim is created. The annotation
+	// remains for as long as any BucketAccess references the BucketClaim. Once all BucketAccesses
+	// that reference the BucketClaim are deleted, the annotation is removed.
+	HasBucketAccessReferencesAnnotation = `objectstorage.k8s.io/has-bucketaccess-references`
+
+	// SidecarCleanupFinishedAnnotation : This annotation is applied by a COSI Sidecar to a managed
+	// BucketAccess when the resources is being deleted. The Sidecar calls the Driver to perform
+	// backend deletion actions and then hands off final deletion cleanup to the COSI Controller
+	// by setting this annotation on the resource.
+	SidecarCleanupFinishedAnnotation = `objectstorage.k8s.io/sidecar-cleanup-finished`
+
+	// ControllerManagementOverrideAnnotation : This annotation can be applied to a resource by the
+	// COSI Controller in order to reclaim management of the resource temporarily when it would
+	// otherwise be managed by a COSI Sidecar. This is intended for scenarios where a bug in
+	// provisioning needs to be rectified by a newer version of the COSI Controller. Once the bug is
+	// resolved, the annotation should be removed to allow normal Sidecar handoff to occur.
+	ControllerManagementOverrideAnnotation = `objectstorage.k8s.io/controller-management-override`
+)
+
+// Sidecar RPC definitions
 const (
 	// RpcEndpointDefault is the default RPC endpoint unix socket location.
 	RpcEndpointDefault = "unix:///var/lib/cosi/cosi.sock"

controller/internal/reconciler/bucketaccess.go

@@ -18,13 +18,22 @@ package reconciler
 
 import (
 	"context"
+	"fmt"
+	"time"
 
+	"github.com/go-logr/logr"
+	kerrors "k8s.io/apimachinery/pkg/api/errors"
 	"k8s.io/apimachinery/pkg/runtime"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
-	logf "sigs.k8s.io/controller-runtime/pkg/log"
+	ctrlutil "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+	ctrlpredicate "sigs.k8s.io/controller-runtime/pkg/predicate"
+	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 
+	cosiapi "sigs.k8s.io/container-object-storage-interface/client/apis/objectstorage/v1alpha2"
 	objectstoragev1alpha2 "sigs.k8s.io/container-object-storage-interface/client/apis/objectstorage/v1alpha2"
+	"sigs.k8s.io/container-object-storage-interface/internal/handoff"
+	cosipredicate "sigs.k8s.io/container-object-storage-interface/internal/predicate"
 )
 
 // BucketAccessReconciler reconciles a BucketAccess object
@@ -33,31 +42,156 @@ type BucketAccessReconciler struct {
 	Scheme *runtime.Scheme
 }
 
-// +kubebuilder:rbac:groups=objectstorage.k8s.io,resources=bucketaccesses,verbs=get;list;watch;create;update;patch;delete
-// +kubebuilder:rbac:groups=objectstorage.k8s.io,resources=bucketaccesses/status,verbs=get;update;patch
+// +kubebuilder:rbac:groups=objectstorage.k8s.io,resources=bucketaccesses,verbs=get;list;watch;create;update
+// +kubebuilder:rbac:groups=objectstorage.k8s.io,resources=bucketaccesses/status,verbs=get;update
 // +kubebuilder:rbac:groups=objectstorage.k8s.io,resources=bucketaccesses/finalizers,verbs=update
 
 // Reconcile is part of the main kubernetes reconciliation loop which aims to
 // move the current state of the cluster closer to the desired state.
-// TODO(user): Modify the Reconcile function to compare the state specified by
-// the BucketAccess object against the actual cluster state, and then
-// perform operations to make the cluster state reflect the state specified by
-// the user.
-//
-// For more details, check Reconcile and its Result here:
-// - https://pkg.go.dev/sigs.k8s.io/controller-runtime@v0.21.0/pkg/reconcile
 func (r *BucketAccessReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
-	_ = logf.FromContext(ctx)
+	logger := ctrl.LoggerFrom(ctx)
 
-	// TODO(user): your logic here
+	access := &cosiapi.BucketAccess{}
+	if err := r.Get(ctx, req.NamespacedName, access); err != nil {
+		if kerrors.IsNotFound(err) {
+			logger.V(1).Info("not reconciling nonexistent BucketAccess")
+			return ctrl.Result{}, nil
+		}
+		// no resource to add status to or report an event for
+		logger.Error(err, "failed to get BucketAccess")
+		return ctrl.Result{}, err
+	}
 
-	return ctrl.Result{}, nil
+	if handoff.BucketAccessManagedBySidecar(access) {
+		logger.V(1).Info("not reconciling BucketAccess that should be managed by sidecar")
+		return ctrl.Result{}, nil
+	}
+
+	retryError, err := r.reconcile(ctx, logger, access)
+	if err != nil {
+		// Because the BucketAccess status is could be managed by either Sidecar or Controller,
+		// indicate that this error is coming from the Controller.
+		err = fmt.Errorf("COSI Controller error: %w", err)
+
+		// Record any error as a timestamped error in the status.
+		access.Status.Error = cosiapi.NewTimestampedError(time.Now(), err.Error())
+		if updErr := r.Status().Update(ctx, access); updErr != nil {
+			logger.Error(err, "failed to update BucketAccess status after reconcile error", "updateError", updErr)
+			// If status update fails, we must retry the error regardless of the reconcile return.
+			// The reconcile needs to run again to make sure the status is eventually be updated.
+			return reconcile.Result{}, err
+		}
+
+		if !retryError {
+			return reconcile.Result{}, reconcile.TerminalError(err)
+		}
+		return reconcile.Result{}, err
+	}
+
+	// NOTE: Do not clear the error in the status on success. Success indicates 1 of 2 things:
+	//   1. BucketAccess was initialized successfully, and it's now owned by the Sidecar
+	//   2. BucketAccess deletion cleanup was just finished, and no status update is needed
+
+	return reconcile.Result{}, err
 }
 
 // SetupWithManager sets up the controller with the Manager.
 func (r *BucketAccessReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		For(&objectstoragev1alpha2.BucketAccess{}).
 		Named("bucketaccess").
+		WithEventFilter(
+			ctrlpredicate.And(
+				cosipredicate.BucketAccessManagedByController(r.Scheme), // only opt in to reconciles managed by controller
+				ctrlpredicate.Or(
+					// when managed by controller, we should reconcile ALL Create/Delete/Generic events
+					cosipredicate.AnyCreate(),
+					cosipredicate.AnyDelete(),
+					cosipredicate.AnyGeneric(),
+					// opt in to desired update events
+					cosipredicate.BucketAccessHandoffOccurred(r.Scheme), // reconcile any handoff change
+					cosipredicate.ProtectionFinalizerRemoved(r.Scheme),  // re-add protection finalizer if removed
+				),
+			),
+		).
 		Complete(r)
 }
+
+func (r *BucketAccessReconciler) reconcile(
+	ctx context.Context, logger logr.Logger, access *cosiapi.BucketAccess,
+) (retryErrorType, error) {
+	if !access.GetDeletionTimestamp().IsZero() {
+		logger.V(1).Info("beginning BucketAccess deletion cleanup")
+
+		// TODO: deletion logic
+
+		ctrlutil.RemoveFinalizer(access, cosiapi.ProtectionFinalizer)
+		if err := r.Update(ctx, access); err != nil {
+			logger.Error(err, "failed to remove finalizer")
+			return RetryError, fmt.Errorf("failed to remove finalizer: %w", err)
+		}
+
+		return DoNotRetryError, fmt.Errorf("deletion is not yet implemented") // TODO
+	}
+
+	needInit, err := readyForControllerInitialization(&access.Status)
+	if err != nil {
+		logger.Error(err, "processed a degraded BucketAccess")
+		return DoNotRetryError, fmt.Errorf("processed a degraded BucketAccess: %w", err)
+	}
+	if !needInit {
+		// BucketAccessClass info should only be copied to the BucketAccess status once, upon
+		// initial provisioning. After the info is copied, we can make no attempt to fill in any
+		// missing or lost info because we don't know whether the current Class is compatible with
+		// the info from the existing (old) Class info. If we reach this condition, something is
+		// systemically wrong. Sidecar should have ownership, but we determined otherwise, and the
+		// Sidecar will likely also determine us to be the owner.
+		logger.Error(nil, "processed a BucketAccess that should be managed by COSI Sidecar")
+		return DoNotRetryError, fmt.Errorf("processed a BucketAccess that should be managed by COSI Sidecar")
+	}
+
+	// TODO:
+	// 1. get referenced BucketClaims
+	//    a. for each, add HasBucketAccessReferencesAnnotation to the claim
+	//    b. for each, get Bucket info to build corresponding accessedBuckets list
+	// 2. get BucketAccessClass
+	// 3. build updated status
+	//    a. accessedBuckets list
+	//    b. driverName, authType, parameters
+	//    c. error = nil
+	// 4. status().update()
+
+	return NoError, nil
+}
+
+// Return true if the Controller needs to initialize the BucketAccess with BucketClaim and
+// BucketAccessClass info. Return false if required info is set.
+// Return an error if any required info is only partially set. This indicates some sort of
+// degradation or bug.
+func readyForControllerInitialization(s *cosiapi.BucketAccessStatus) (bool, error) {
+	requiredFields := map[string]bool{}
+	requiredFieldIsSet := func(fieldName string, isSet bool) {
+		requiredFields[fieldName] = isSet
+	}
+
+	requiredFieldIsSet("status.accessedBuckets", len(s.AccessedBuckets) > 0)
+	requiredFieldIsSet("status.driverName", s.DriverName != "")
+	requiredFieldIsSet("status.authenticationType", string(s.AuthenticationType) != "")
+
+	set := []string{}
+	for field, isSet := range requiredFields {
+		if isSet {
+			set = append(set, field)
+		}
+	}
+
+	if len(set) == 0 {
+		return true, nil
+	}
+
+	if len(set) == len(requiredFields) {
+		return false, nil
+	}
+
+	return false, fmt.Errorf("required Controller-managed fields are only partially set: %v", requiredFields)
+}

controller/internal/reconciler/bucketclaim.go

@@ -81,7 +81,7 @@ func (r *BucketClaimReconciler) Reconcile(ctx context.Context, req ctrl.Request)
 	}
 
 	// On success, clear any errors in the status.
-	if claim.Status.Error != nil {
+	if claim.Status.Error != nil && !claim.DeletionTimestamp.IsZero() {
 		claim.Status.Error = nil
 		if err := r.Status().Update(ctx, claim); err != nil {
 			logger.Error(err, "failed to update BucketClaim status after reconcile success")

internal/handoff/handoff.go

@@ -0,0 +1,67 @@
+/*
+Copyright 2025 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 handoff defines logic needed for handing off control of resources between Controller and
+// Sidecar.
+package handoff
+
+import (
+	cosiapi "sigs.k8s.io/container-object-storage-interface/client/apis/objectstorage/v1alpha2"
+)
+
+// BucketAccessManagedBySidecar returns true if a BucketAccess should be managed by the Sidecar.
+// A false return value indicates that it should be managed by the Controller instead.
+//
+// In order for COSI Controller and any given Sidecar to work well together, they should avoid
+// managing the same BucketAccess resource at the same time. Instances where a resource has no
+// manager MUST be avoided without exception.
+//
+// Version skew between Controller and Sidecar should be assumed. In order for version skew issues
+// to be minimized, avoid updating this logic unless it is absolutely critical. If updates are made,
+// be sure to carefully consider all version skew cases below. Minimize dual-ownership scenarios,
+// and avoid no-owner scenarios.
+//
+//  1. Sidecar version low, Controller version low
+//  2. Sidecar version low, Controller version high
+//  3. Sidecar version high, Controller version low
+//  4. Sidecar version high, Controller version high
+func BucketAccessManagedBySidecar(ba *cosiapi.BucketAccess) bool {
+	// Allow a future-compatible mechanism by which the Controller can override the normal
+	// BucketAccess management handoff logic in order to resolve a bug.
+	// Instances where this is utilized should be infrequent -- ideally, never used.
+	if _, ok := ba.Annotations[cosiapi.ControllerManagementOverrideAnnotation]; ok {
+		return false
+	}
+
+	// During provisioning, there are several status fields that the Controller needs to set before
+	// the Sidecar can provision an access. However, tying this function's logic to ALL of the
+	// status items could make long-term Controller-Sidecar handoff logic fragile. More logic means
+	// more risk of unmanaged resources and more difficulty reasoning about how changes will impact
+	// ownership during version skew. Minimize risk by relying on a single determining status field.
+	if ba.Status.DriverName == "" {
+		return false
+	}
+
+	// During deletion, as long as the access was handed off to the Sidecar at some point, the
+	// Sidecar must first clean up the backend bucket, then hand back final deletion to the
+	// Controller by setting an annotation.
+	if !ba.DeletionTimestamp.IsZero() {
+		_, ok := ba.Annotations[cosiapi.SidecarCleanupFinishedAnnotation]
+		return !ok // ok means sidecar is done cleaning up
+	}
+
+	return true
+}