Add drift detection and periodic resync for OpenStack resources

[eshulman2]

Summary

Implements periodic resync and external deletion handling for the OpenStack Resource Controller. When enabled, ORC periodically reconciles resources with OpenStack to detect configuration drift and external deletions, automatically recreating managed resources that were deleted outside of ORC while surfacing terminal errors for imported resources.

Changes

API Changes

• Added resyncPeriod field to the code generator spec template for per-resource resync configuration
• Added lastSyncTime field to the code generator status template to track successful reconciliation timestamps
• Added GetResyncPeriod(), GetLastSyncTime(), and IsImported() methods to APIObjectAdapter interface

CLI & Manager

• Added --default-resync-period CLI flag with default value of 0 (disabled)
• Added ResyncConfigurable interface to propagate global default to all controllers

Core Resync Logic

• Created internal/controllers/generic/resync/ package with:
  • DetermineResyncPeriod(): resolves effective period (per-resource → global → disabled)
  • CalculateJitteredDuration(): wraps wait.Jitter with 20% positive-only jitter
  • ShouldScheduleResync(): guards against scheduling for disabled/terminal/pending-requeue states
• Modified shouldReconcile() to trigger reconciliation when resync period has elapsed
• Modified reconcileNormal() to schedule jittered requeue after successful reconciliation

External Deletion Handling

• Modified GetOrCreateOSResource() to detect 404s when fetching by status.id
• Returns typed ExternallyDeleted signal via ReconcileStatus for managed non-imported resources
• Restored safety guard for unexpected nil returns from actuators
• Imported/unmanaged resources return terminal error
• Added ClearStatusID() to status writer for clearing ID before recreation

Status Updates

• Modified UpdateStatus() to set lastSyncTime only on successful reconciliation
• Fixed Available condition: terminal errors now set False instead of Unknown

Code Generation

• Updated api.template and adapter.template with new fields and methods
• Regenerated all resources, CRDs, deep copy, and client code

Documentation

• Created website/docs/user-guide/drift-detection.md
• Updated enhancements/drift-detection.md with implementation status

Commit structure

1. API fields + templates — hand-written type and template changes
2. Regenerate — all generated code (CRDs, adapters, apply configs, OpenAPI, docs)
3. Resync scheduling — scheduler, controller integration, CLI flag, all controller wiring
4. E2E tests for resync — kuttl test suites + integration tests
5. External deletion — detection, recreation, condition fix, unit + E2E tests
6. Documentation — user guide and enhancement doc
7. Design update — update enhancement proposal with typed ExternallyDeleted signal

Design decisions

• Typed ExternallyDeleted signal: The original proposal used a (nil, nil) return from GetOrCreateOSResource to signal external deletion. This was replaced with a typed ExternallyDeleted flag on ReconcileStatus, which avoids ambiguity with actuator bugs that might also return nil and restores a safety guard for unexpected nil returns from GetOSResourceByID.
• wait.Jitter reuse: CalculateJitteredDuration wraps k8s.io/apimachinery/pkg/util/wait.Jitter rather than reimplementing the same [base, base*1.2) jitter range.
• Removed dead CommonStatus/CommonOptions types: These types were declared but never embedded — the code generator inlines the fields directly. They were removed to avoid misleading readers.

Testing

• Unit tests for resync package, shouldReconcile, status updates, external deletion (all policy/import combinations)
• 6 kuttl E2E test suites: resync-period, resync-disabled, resync-terminal-error, resync-jitter, external-deletion, external-deletion-import
• go build, go vet, make lint all pass

[eshulman2]

there are some issues especially with docs

[mandre]

Adding the hold label because this is an experiment.

[eshulman2]

@mandre I revised the PR myself removing any indication of internal references I think it is ready for review

[dlaw4608]

Hey @eshulman2 , I ran it locally following the drift-detection.md and it works well, also ran some of the E2E tests, I left a few comments, please let me know what you think?