Implement periodic resync scheduling with CLI flag

Add --default-resync-period CLI flag to the manager for setting a global
default resync period. Implement DetermineResyncPeriod to resolve the
effective period using per-resource then global default precedence.

Create resync scheduler package using wait.Jitter for jittered duration
calculation. Modify shouldReconcile to support periodic resync by
checking lastSyncTime against the effective resync period.

Integrate resync requeue scheduling into reconcileNormal and update the
status writer to set lastSyncTime on successful reconciliation. Wire
the DefaultResyncPeriod from manager options through to all controllers.

Add typed ExternallyDeleted signal on ReconcileStatus for safe
detection of externally deleted OpenStack resources.

Author: eshulman2

cmd/manager/main.go

@@ -80,6 +80,9 @@ func main() {
 	flag.IntVar(&orcOpts.ScopeCacheMaxSize, "scope-cache-max-size", 10,
 		"The maximum credentials count the operator should keep in cache. "+
 			"Setting this value to 0 means no cache.")
+	flag.DurationVar(&orcOpts.DefaultResyncPeriod, "default-resync-period", 0,
+		"Default resync period for all resources. Set to 0 to disable. "+
+			"Can be overridden per-resource via spec.resyncPeriod.")
 	flag.StringVar(&defaultCACertsPath, "default-ca-certs", "",
 		"The path to a PEM-encoded CA Certificate file to supply as default for OpenStack API requests.")
 	flag.Func("namespace", "A namespace that the controller watches to reconcile ORC objects. "+

internal/controllers/addressscope/controller.go

@@ -19,6 +19,7 @@ package addressscope
 import (
 	"context"
 	"errors"
+	"time"
 
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/builder"
@@ -40,17 +41,22 @@ const controllerName = "addressscope"
 // +kubebuilder:rbac:groups=openstack.k-orc.cloud,resources=addressscopes/status,verbs=get;update;patch
 
 type addressscopeReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return addressscopeReconcilerConstructor{scopeFactory: scopeFactory}
+	return &addressscopeReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (addressscopeReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *addressscopeReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 var projectDependency = dependency.NewDeletionGuardDependency[*orcv1alpha1.AddressScopeList, *orcv1alpha1.Project](
 	"spec.resource.projectRef",
 	func(addressscope *orcv1alpha1.AddressScope) []string {
@@ -75,7 +81,7 @@ var projectImportDependency = dependency.NewDependency[*orcv1alpha1.AddressScope
 )
 
 // SetupWithManager sets up the controller with the Manager.
-func (c addressscopeReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *addressscopeReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := ctrl.LoggerFrom(ctx)
 	k8sClient := mgr.GetClient()
 
@@ -109,6 +115,6 @@ func (c addressscopeReconcilerConstructor) SetupWithManager(ctx context.Context,
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, addressscopeHelperFactory{}, addressscopeStatusWriter{})
+	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, addressscopeHelperFactory{}, addressscopeStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/applicationcredential/controller.go

@@ -19,6 +19,7 @@ package applicationcredential
 import (
 	"context"
 	"errors"
+	"time"
 
 	corev1 "k8s.io/api/core/v1"
 	ctrl "sigs.k8s.io/controller-runtime"
@@ -94,17 +95,22 @@ var (
 )
 
 type applicationcredentialReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return applicationcredentialReconcilerConstructor{scopeFactory: scopeFactory}
+	return &applicationcredentialReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (applicationcredentialReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *applicationcredentialReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 var userDependency = dependency.NewDeletionGuardDependency[*orcv1alpha1.ApplicationCredentialList, *orcv1alpha1.User](
 	"spec.resource.userRef",
 	func(applicationcredential *orcv1alpha1.ApplicationCredential) []string {
@@ -129,7 +135,7 @@ var userImportDependency = dependency.NewDependency[*orcv1alpha1.ApplicationCred
 )
 
 // SetupWithManager sets up the controller with the Manager.
-func (c applicationcredentialReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *applicationcredentialReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := ctrl.LoggerFrom(ctx)
 	k8sClient := mgr.GetClient()
 
@@ -195,6 +201,6 @@ func (c applicationcredentialReconcilerConstructor) SetupWithManager(ctx context
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, applicationcredentialHelperFactory{}, applicationcredentialStatusWriter{})
+	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, applicationcredentialHelperFactory{}, applicationcredentialStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/domain/controller.go

@@ -19,6 +19,7 @@ package domain
 import (
 	"context"
 	"errors"
+	"time"
 
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/controller"
@@ -37,19 +38,24 @@ const controllerName = "domain"
 // +kubebuilder:rbac:groups=openstack.k-orc.cloud,resources=domains/status,verbs=get;update;patch
 
 type domainReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return domainReconcilerConstructor{scopeFactory: scopeFactory}
+	return &domainReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (domainReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *domainReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 // SetupWithManager sets up the controller with the Manager.
-func (c domainReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *domainReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := ctrl.LoggerFrom(ctx)
 
 	builder := ctrl.NewControllerManagedBy(mgr).
@@ -63,6 +69,6 @@ func (c domainReconcilerConstructor) SetupWithManager(ctx context.Context, mgr c
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, domainHelperFactory{}, domainStatusWriter{})
+	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, domainHelperFactory{}, domainStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/endpoint/controller.go

@@ -19,6 +19,7 @@ package endpoint
 import (
 	"context"
 	"errors"
+	"time"
 
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/builder"
@@ -40,17 +41,22 @@ const controllerName = "endpoint"
 // +kubebuilder:rbac:groups=openstack.k-orc.cloud,resources=endpoints/status,verbs=get;update;patch
 
 type endpointReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return endpointReconcilerConstructor{scopeFactory: scopeFactory}
+	return &endpointReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (endpointReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *endpointReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 var serviceDependency = dependency.NewDeletionGuardDependency[*orcv1alpha1.EndpointList, *orcv1alpha1.Service](
 	"spec.resource.serviceRef",
 	func(endpoint *orcv1alpha1.Endpoint) []string {
@@ -75,7 +81,7 @@ var serviceImportDependency = dependency.NewDependency[*orcv1alpha1.EndpointList
 )
 
 // SetupWithManager sets up the controller with the Manager.
-func (c endpointReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *endpointReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := ctrl.LoggerFrom(ctx)
 	k8sClient := mgr.GetClient()
 
@@ -109,6 +115,6 @@ func (c endpointReconcilerConstructor) SetupWithManager(ctx context.Context, mgr
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, endpointHelperFactory{}, endpointStatusWriter{})
+	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, endpointHelperFactory{}, endpointStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/flavor/controller.go

@@ -19,6 +19,7 @@ package flavor
 import (
 	"context"
 	"errors"
+	"time"
 
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/controller"
@@ -37,19 +38,24 @@ const controllerName = "flavor"
 // +kubebuilder:rbac:groups=openstack.k-orc.cloud,resources=flavors/status,verbs=get;update;patch
 
 type flavorReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return flavorReconcilerConstructor{scopeFactory: scopeFactory}
+	return &flavorReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (flavorReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *flavorReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 // SetupWithManager sets up the controller with the Manager.
-func (c flavorReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *flavorReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := ctrl.LoggerFrom(ctx)
 
 	builder := ctrl.NewControllerManagedBy(mgr).
@@ -63,6 +69,6 @@ func (c flavorReconcilerConstructor) SetupWithManager(ctx context.Context, mgr c
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, flavorHelperFactory{}, flavorStatusWriter{})
+	r := reconciler.NewController(controllerName, mgr.GetClient(), c.scopeFactory, flavorHelperFactory{}, flavorStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/floatingip/controller.go

@@ -19,6 +19,7 @@ package floatingip
 import (
 	"context"
 	"errors"
+	"time"
 
 	"k8s.io/utils/ptr"
 	ctrl "sigs.k8s.io/controller-runtime"
@@ -39,17 +40,22 @@ import (
 // +kubebuilder:rbac:groups=openstack.k-orc.cloud,resources=floatingips/status,verbs=get;update;patch
 
 type floatingipReconcilerConstructor struct {
-	scopeFactory scope.Factory
+	scopeFactory        scope.Factory
+	defaultResyncPeriod time.Duration
 }
 
 func New(scopeFactory scope.Factory) interfaces.Controller {
-	return floatingipReconcilerConstructor{scopeFactory: scopeFactory}
+	return &floatingipReconcilerConstructor{scopeFactory: scopeFactory}
 }
 
 func (floatingipReconcilerConstructor) GetName() string {
 	return controllerName
 }
 
+func (c *floatingipReconcilerConstructor) SetDefaultResyncPeriod(d time.Duration) {
+	c.defaultResyncPeriod = d
+}
+
 const controllerName = "floatingip"
 
 var (
@@ -136,7 +142,7 @@ var (
 )
 
 // SetupWithManager sets up the controller with the Manager.
-func (c floatingipReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
+func (c *floatingipReconcilerConstructor) SetupWithManager(ctx context.Context, mgr ctrl.Manager, options controller.Options) error {
 	log := mgr.GetLogger().WithValues("controller", controllerName)
 	k8sClient := mgr.GetClient()
 
@@ -217,6 +223,6 @@ func (c floatingipReconcilerConstructor) SetupWithManager(ctx context.Context, m
 		return err
 	}
 
-	r := reconciler.NewController(controllerName, k8sClient, c.scopeFactory, floatingipHelperFactory{}, floatingipStatusWriter{})
+	r := reconciler.NewController(controllerName, k8sClient, c.scopeFactory, floatingipHelperFactory{}, floatingipStatusWriter{}, c.defaultResyncPeriod)
 	return builder.Complete(&r)
 }

internal/controllers/generic/interfaces/controller.go

@@ -18,6 +18,7 @@ package interfaces
 
 import (
 	"context"
+	"time"
 
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
@@ -31,6 +32,14 @@ type Controller interface {
 	GetName() string
 }
 
+// ResyncConfigurable is an optional interface that Controller implementations
+// may satisfy to receive the operator-level default resync period. The manager
+// calls SetDefaultResyncPeriod before SetupWithManager so that the value is
+// available when the controller is built.
+type ResyncConfigurable interface {
+	SetDefaultResyncPeriod(time.Duration)
+}
+
 type ResourceController interface {
 	GetName() string
 

internal/controllers/generic/interfaces/status.go

@@ -35,10 +35,12 @@ type ORCApplyConfig[objectApplyPT any, statusApplyPT ORCStatusApplyConfig[status
 }
 
 // ORCStatusApplyConfig is an interface implemented by the status of any apply
-// configuration for an ORC API object. It has Conditions and an ID field.
+// configuration for an ORC API object. It has Conditions, an ID field, and a
+// LastSyncTime field.
 type ORCStatusApplyConfig[statusApplyPT any] interface {
 	WithConditions(...*applyconfigv1.ConditionApplyConfiguration) statusApplyPT
 	WithID(id string) statusApplyPT
+	WithLastSyncTime(metav1.Time) statusApplyPT
 }
 
 // ResourceStatusWriter defines methods for writing an ORC object status

internal/controllers/generic/progress/reconcile_status.go

@@ -42,6 +42,8 @@ type reconcileStatus struct {
 	requeue  time.Duration
 
 	err error
+
+	externallyDeleted bool
 }
 
 // NewReconcileStatus returns an empty ReconcileStatus
@@ -177,9 +179,38 @@ func (r ReconcileStatus) WithReconcileStatus(o ReconcileStatus) ReconcileStatus
 		return o
 	}
 
-	return r.WithProgressMessage(o.GetProgressMessages()...).
+	r = r.WithProgressMessage(o.GetProgressMessages()...).
 		WithRequeue(o.GetRequeue()).
 		WithError(o.GetError())
+	if o != nil && o.externallyDeleted {
+		r.externallyDeleted = true
+	}
+	return r
+}
+
+// ExternallyDeleted returns a ReconcileStatus indicating that the OpenStack
+// resource referenced by status.id has been deleted outside of ORC. The caller
+// is expected to clear status.id and add an appropriate progress message.
+func (r ReconcileStatus) ExternallyDeleted() ReconcileStatus {
+	if r == nil {
+		r = &reconcileStatus{}
+	}
+	r.externallyDeleted = true
+	return r
+}
+
+// ExternallyDeleted is a convenience method which returns a new ReconcileStatus with ExternallyDeleted.
+func ExternallyDeleted() ReconcileStatus {
+	return NewReconcileStatus().ExternallyDeleted()
+}
+
+// IsExternallyDeleted returns true if the ReconcileStatus indicates that the
+// OpenStack resource was deleted externally.
+func (r ReconcileStatus) IsExternallyDeleted() bool {
+	if r == nil {
+		return false
+	}
+	return r.externallyDeleted
 }
 
 // WaitingOnEvent represents the type of event we are waiting on