Add pause reconciliation support for Device and associated resources

Introduce the ability to pause reconciliation for Devices and their
associated resources. This is useful for maintenance scenarios where
network device configuration should be temporarily frozen.

Pausing can be enabled via:
- Setting `spec.paused: true` on a Device (pauses Device and all
  associated resources)
- Adding the `networking.metal.ironcore.dev/paused` annotation to
  any individual resource

When paused, controllers will skip reconciliation and log an info
message indicating the resource is paused.

Author: felix-kaestner

api/core/v1alpha1/device_types.go

@@ -13,6 +13,10 @@ import (
 
 // DeviceSpec defines the desired state of Device.
 type DeviceSpec struct {
+	// Paused can be used to prevent controllers from processing the Device and its associated objects.
+	// +optional
+	Paused *bool `json:"paused,omitempty"`
+
 	// Endpoint contains the connection information for the device.
 	// +required
 	Endpoint Endpoint `json:"endpoint"`

api/core/v1alpha1/groupversion_info.go

@@ -25,6 +25,11 @@ var (
 // with reconciliation of the object only if this label and a configured value is present.
 const WatchLabel = "networking.metal.ironcore.dev/watch-filter"
 
+// PausedAnnotation is an annotation that can be applied to any Network API object
+// to prevent a controller from processing it. Controllers working with Network API objects
+// must check the existence of this annotation on the reconciled object.
+const PausedAnnotation = "networking.metal.ironcore.dev/paused"
+
 // FinalizerName is the identifier used by the controllers to perform cleanup before a resource is deleted.
 // It is added when the resource is created and ensures that the controller can handle teardown logic
 // (e.g., deleting external dependencies) before Kubernetes finalizes the deletion.

internal/annotations/annotations.go

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2025 SAP SE or an SAP affiliate company and IronCore contributors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package annotations implements annotation helper functions.
+package annotations
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+)
+
+// IsPaused returns true if the Device is paused or the object has the [v1alpha1.PausedAnnotation].
+func IsPaused(device *v1alpha1.Device, obj metav1.Object) bool {
+	return (device.Spec.Paused != nil && *device.Spec.Paused) || HasPaused(obj)
+}
+
+// HasPaused returns true if the object has the [v1alpha1.PausedAnnotation].
+func HasPaused(obj metav1.Object) bool {
+	return Has(obj, v1alpha1.PausedAnnotation)
+}
+
+// Has returns true if the object has the specified annotation.
+func Has(obj metav1.Object, annotation string) bool {
+	_, ok := obj.GetAnnotations()[annotation]
+	return ok
+}

internal/controller/cisco/nx/bordergateway_controller.go

@@ -29,6 +29,7 @@ import (
 
 	nxv1alpha1 "github.com/ironcore-dev/network-operator/api/cisco/nx/v1alpha1"
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
 	"github.com/ironcore-dev/network-operator/internal/provider"
@@ -103,6 +104,11 @@ func (r *BorderGatewayReconciler) Reconcile(ctx context.Context, req ctrl.Reques
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "cisco-nx-border-gateway-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/cisco/nx/system_controller.go

@@ -23,6 +23,7 @@ import (
 
 	nxv1alpha1 "github.com/ironcore-dev/network-operator/api/cisco/nx/v1alpha1"
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
 	"github.com/ironcore-dev/network-operator/internal/provider"
@@ -96,6 +97,11 @@ func (r *SystemReconciler) Reconcile(ctx context.Context, req ctrl.Request) (_ c
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "cisco-nx-system-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/cisco/nx/vpcdomain_controller.go

@@ -27,6 +27,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/provider"
 	"github.com/ironcore-dev/network-operator/internal/resourcelock"
@@ -112,6 +113,11 @@ func (r *VPCDomainReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "cisco-nx-vpcdomain-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/core/acl_controller.go

@@ -22,6 +22,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
 	"github.com/ironcore-dev/network-operator/internal/provider"
@@ -95,6 +96,11 @@ func (r *AccessControlListReconciler) Reconcile(ctx context.Context, req ctrl.Re
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "acl-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/core/banner_controller.go

@@ -26,6 +26,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/clientutil"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
@@ -102,6 +103,11 @@ func (r *BannerReconciler) Reconcile(ctx context.Context, req ctrl.Request) (_ c
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "banner-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/core/bgp_controller.go

@@ -22,6 +22,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
 	"github.com/ironcore-dev/network-operator/internal/provider"
@@ -99,6 +100,11 @@ func (r *BGPReconciler) Reconcile(ctx context.Context, req ctrl.Request) (_ ctrl
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "bgp-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")

internal/controller/core/bgp_peer_controller.go

@@ -27,6 +27,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 
 	"github.com/ironcore-dev/network-operator/api/core/v1alpha1"
+	"github.com/ironcore-dev/network-operator/internal/annotations"
 	"github.com/ironcore-dev/network-operator/internal/conditions"
 	"github.com/ironcore-dev/network-operator/internal/deviceutil"
 	"github.com/ironcore-dev/network-operator/internal/provider"
@@ -104,6 +105,11 @@ func (r *BGPPeerReconciler) Reconcile(ctx context.Context, req ctrl.Request) (_
 		return ctrl.Result{}, err
 	}
 
+	if annotations.IsPaused(device, obj) {
+		log.Info("Reconciliation is paused for this object")
+		return ctrl.Result{}, nil
+	}
+
 	if err := r.Locker.AcquireLock(ctx, device.Name, "bgppeer-controller"); err != nil {
 		if errors.Is(err, resourcelock.ErrLockAlreadyHeld) {
 			log.Info("Device is already locked, requeuing reconciliation")