README
¶
pkg/controller/deployer
Deployment orchestration components for HAProxy configuration deployment.
Overview
The deployer package implements a three-component architecture that provides smart deployment scheduling with rate limiting, drift prevention, and stateless execution.
Architecture
Three-Component Design
ValidationCompletedEvent ──────┐
HAProxyPodsDiscoveredEvent ────┤
DriftPreventionTriggeredEvent ─┤
↓
DeploymentScheduler
(Rate Limiting & State)
↓
DeploymentScheduledEvent
↓
Deployer
(Stateless Executor)
↓
DeploymentCompletedEvent
↓
DriftPreventionMonitor
(Periodic Triggering)
Components
1. DeploymentScheduler
Purpose: Coordinates WHEN deployments happen
Responsibilities:
- Maintains state (last validated config, current endpoints)
- Enforces minimum deployment interval (rate limiting)
- Implements "latest wins" queueing for concurrent changes
- Publishes DeploymentScheduledEvent when ready to deploy
Events:
- Subscribes:
TemplateRenderedEvent,ValidationCompletedEvent,HAProxyPodsDiscoveredEvent,DriftPreventionTriggeredEvent,DeploymentCompletedEvent - Publishes:
DeploymentScheduledEvent
Configuration:
min_deployment_interval: Minimum time between consecutive deployments (default: 2s)
2. Deployer
Purpose: Executes deployments to HAProxy instances
Responsibilities:
- Stateless deployment execution
- Parallel deployment to multiple endpoints
- Per-instance success/failure tracking
- Publishes detailed deployment events
Events:
- Subscribes:
DeploymentScheduledEvent - Publishes:
DeploymentStartedEvent,InstanceDeployedEvent,InstanceDeploymentFailedEvent,DeploymentCompletedEvent
3. DriftPreventionMonitor
Purpose: Prevents configuration drift from external changes
Responsibilities:
- Monitors deployment activity via timer
- Triggers periodic deployments after idle period
- Resets timer on each successful deployment
Events:
- Subscribes:
DeploymentCompletedEvent - Publishes:
DriftPreventionTriggeredEvent
Configuration:
drift_prevention_interval: Interval for periodic deployments (default: 60s)
Quick Start
// Create deployment scheduler with rate limiting
minInterval := 2 * time.Second
scheduler := deployer.NewDeploymentScheduler(bus, logger, minInterval)
go scheduler.Start(ctx)
// Create stateless deployer
deployer := deployer.New(bus, logger)
go deployer.Start(ctx)
// Create drift prevention monitor
driftInterval := 60 * time.Second
monitor := deployer.NewDriftPreventionMonitor(bus, logger, driftInterval)
go monitor.Start(ctx)
Key Features
Rate Limiting
Prevents rapid-fire deployments during high-frequency changes:
- Configurable minimum interval between deployments
- Enforced by DeploymentScheduler before publishing events
- Prevents version conflicts in HAProxy Dataplane API
"Latest Wins" Queueing
Only the most recent configuration change is queued:
- Single pending deployment value (not a queue)
- New deployment requests overwrite pending deployments
- Ensures eventual consistency without unnecessary work
Drift Prevention
Detects and corrects external configuration changes:
- Periodic deployment triggers if system is idle
- Helps identify drift from other Dataplane API clients
- Configurable interval (default: 60s)
Concurrent Deployment Protection
Prevents overlapping deployments:
- Scheduler tracks deployment in-progress state
- Pending deployments queued until current completes
- Recursive processing ensures all changes are applied
License
See main repository for license information.
Documentation
¶
Overview ¶
Package deployer implements the Deployer component that deploys validated HAProxy configurations to discovered HAProxy pod endpoints.
The Deployer is a stateless executor that receives DeploymentScheduledEvent and executes deployments to the specified endpoints. All deployment scheduling, rate limiting, and queueing logic is handled by the DeploymentScheduler component.
Package deployer implements deployment scheduling and execution components.
Index ¶
Constants ¶
const ( // ComponentName is the unique identifier for this component. ComponentName = "deployer" // EventBufferSize is the size of the event subscription buffer. // Size 50: Low-volume component (~1-2 deployment events per reconciliation cycle). // Larger buffers reduce event drops during bursts but consume more memory. EventBufferSize = 50 )
const ( // SchedulerComponentName is the unique identifier for the DeploymentScheduler component. SchedulerComponentName = "deployment-scheduler" // SchedulerEventBufferSize is the size of the event subscription buffer for the scheduler. // Size 50: Moderate-volume component handling template, validation, and discovery events. // Note: Named with "Scheduler" prefix to avoid conflict with EventBufferSize in this package. SchedulerEventBufferSize = 50 )
const (
// DriftMonitorComponentName is the unique identifier for the drift prevention monitor component.
DriftMonitorComponentName = "drift-monitor"
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Component ¶
type Component struct {
// contains filtered or unexported fields
}
Component implements the deployer component.
It subscribes to DeploymentScheduledEvent and deploys configurations to HAProxy instances. This is a stateless executor - all scheduling logic is handled by the DeploymentScheduler component.
Event subscriptions:
- DeploymentScheduledEvent: Execute deployment to specified endpoints
- DeploymentCancelRequestEvent: Cancel in-progress deployment
The component publishes deployment result events for observability.
func New ¶
func New(eventBus *busevents.EventBus, logger *slog.Logger, maxParallel, rawPushThreshold int) *Component
New creates a new Deployer component.
Parameters:
- eventBus: The EventBus for subscribing to events and publishing results
- logger: Structured logger for component logging
- maxParallel: Maximum concurrent Dataplane API operations (0 = unlimited)
- rawPushThreshold: Change count threshold for raw config push (0 = disabled)
Returns:
- A new Component instance ready to be started
func (*Component) HealthCheck ¶
HealthCheck implements the lifecycle.HealthChecker interface. Returns an error if the component appears to be stalled (processing for > timeout). Returns nil when idle (not processing) - idle is always healthy for event-driven components.
func (*Component) Name ¶
Name returns the unique identifier for this component. Implements the lifecycle.Component interface.
func (*Component) Start ¶
Start begins the deployer's event loop.
This method blocks until the context is cancelled or an error occurs. It subscribes to events when called (after leadership is acquired).
Parameters:
- ctx: Context for cancellation and lifecycle management
Returns:
- nil when context is cancelled (graceful shutdown)
- Error only in exceptional circumstances
func (*Component) SubscriptionReady ¶
func (c *Component) SubscriptionReady() <-chan struct{}
SubscriptionReady returns a channel that is closed when the component has completed its event subscription. This implements lifecycle.SubscriptionReadySignaler.
type DeploymentScheduler ¶
type DeploymentScheduler struct {
// contains filtered or unexported fields
}
DeploymentScheduler implements deployment scheduling with rate limiting.
It subscribes to events that trigger deployments, maintains the state of rendered and validated configurations, and enforces minimum deployment intervals.
Event subscriptions:
- TemplateRenderedEvent: Track rendered config and auxiliary files
- ValidationCompletedEvent: Cache validated config and schedule deployment
- ValidationFailedEvent: Deploy cached config for drift prevention fallback
- HAProxyPodsDiscoveredEvent: Update endpoints and schedule deployment
The component publishes DeploymentScheduledEvent when a deployment should execute.
func NewDeploymentScheduler ¶
func NewDeploymentScheduler(eventBus *busevents.EventBus, logger *slog.Logger, minDeploymentInterval, deploymentTimeout time.Duration) *DeploymentScheduler
NewDeploymentScheduler creates a new DeploymentScheduler component.
Parameters:
- eventBus: The EventBus for subscribing to events and publishing scheduled deployments
- logger: Structured logger for component logging
- minDeploymentInterval: Minimum time between consecutive deployments (rate limiting)
- deploymentTimeout: Maximum time to wait for a deployment to complete before retrying
Returns:
- A new DeploymentScheduler instance ready to be started
func (*DeploymentScheduler) HealthCheck ¶
func (s *DeploymentScheduler) HealthCheck() error
HealthCheck implements the lifecycle.HealthChecker interface. Returns an error if the component appears to be stalled (processing for > timeout). Returns nil when idle (not processing) - idle is always healthy for event-driven components.
func (*DeploymentScheduler) Name ¶
func (s *DeploymentScheduler) Name() string
Name returns the unique identifier for this component. Implements the lifecycle.Component interface.
func (*DeploymentScheduler) Start ¶
func (s *DeploymentScheduler) Start(ctx context.Context) error
Start begins the deployment scheduler's event loop.
This method blocks until the context is cancelled or an error occurs. It subscribes to events when called (after leadership is acquired).
Parameters:
- ctx: Context for cancellation and lifecycle management
Returns:
- nil when context is cancelled (graceful shutdown)
- Error only in exceptional circumstances
func (*DeploymentScheduler) SubscriptionReady ¶
func (s *DeploymentScheduler) SubscriptionReady() <-chan struct{}
SubscriptionReady returns a channel that is closed when the component has completed its event subscription. This implements lifecycle.SubscriptionReadySignaler.
type DriftPreventionMonitor ¶
type DriftPreventionMonitor struct {
// contains filtered or unexported fields
}
DriftPreventionMonitor triggers periodic reconciliation to prevent configuration drift in HAProxy pods.
When no deployment has occurred within the configured interval, it publishes a DriftPreventionTriggeredEvent to trigger reconciliation. This helps detect and correct configuration drift caused by other Dataplane API clients or manual changes.
This is a leader-only component that starts when leadership is acquired. Only the leader needs drift prevention since only the leader deploys. The Reconciler triggers fresh reconciliation on BecameLeaderEvent to provide current state.
Event subscriptions:
- DeploymentCompletedEvent: Reset drift prevention timer
- LostLeadershipEvent: Stop drift timer when losing leadership
The component publishes DriftPreventionTriggeredEvent when drift prevention is needed.
func NewDriftPreventionMonitor ¶
func NewDriftPreventionMonitor(eventBus *busevents.EventBus, logger *slog.Logger, driftPreventionInterval time.Duration) *DriftPreventionMonitor
NewDriftPreventionMonitor creates a new DriftPreventionMonitor component.
As a leader-only component, subscription happens in Start() after leadership is acquired, not during construction.
Parameters:
- eventBus: The EventBus for subscribing to events and publishing triggers
- logger: Structured logger for component logging
- driftPreventionInterval: Interval after which to trigger drift prevention deployment
Returns:
- A new DriftPreventionMonitor instance ready to be started
func (*DriftPreventionMonitor) HealthCheck ¶
func (m *DriftPreventionMonitor) HealthCheck() error
HealthCheck implements the lifecycle.HealthChecker interface. Returns an error if the component appears to be stalled (no timer tick for > stallTimeout). For a timer-based component like DriftPreventionMonitor, a healthy state means the timer is firing at the expected interval.
func (*DriftPreventionMonitor) Name ¶
func (m *DriftPreventionMonitor) Name() string
Name returns the unique identifier for this component. Implements the lifecycle.Component interface.
func (*DriftPreventionMonitor) Start ¶
func (m *DriftPreventionMonitor) Start(ctx context.Context) error
Start begins the drift prevention monitor's event loop.
This method blocks until the context is cancelled or an error occurs. As a leader-only component, it subscribes to events when started (after leadership is acquired).
Event handling:
- DeploymentCompletedEvent: Resets the drift prevention timer
- LostLeadershipEvent: Stops drift timer when losing leadership
- Drift timer expiration: Publishes DriftPreventionTriggeredEvent
The component runs until the context is cancelled, at which point it performs cleanup and returns.
Parameters:
- ctx: Context for cancellation and lifecycle management
Returns:
- nil when context is cancelled (graceful shutdown)
- Error only in exceptional circumstances
func (*DriftPreventionMonitor) SubscriptionReady ¶
func (m *DriftPreventionMonitor) SubscriptionReady() <-chan struct{}
SubscriptionReady returns a channel that is closed when the component has completed its event subscription. This implements lifecycle.SubscriptionReadySignaler.
Source Files