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.
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 ( // DriftMonitorComponentName is the unique identifier for the drift prevention monitor component. DriftMonitorComponentName = "drift-monitor" // DriftMonitorEventBufferSize is the size of the event subscription buffer for the drift monitor. DriftMonitorEventBufferSize = 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 )
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
The component publishes deployment result events for observability.
func New ¶
New creates a new Deployer component.
Parameters:
- eventBus: The EventBus for subscribing to events and publishing results
- logger: Structured logger for component logging
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 processes events from the subscription channel established in the constructor.
Parameters:
- ctx: Context for cancellation and lifecycle management
Returns:
- nil when context is cancelled (graceful shutdown)
- Error only in exceptional circumstances
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 processes events from the subscription channel established in the constructor.
Parameters:
- ctx: Context for cancellation and lifecycle management
Returns:
- nil when context is cancelled (graceful shutdown)
- Error only in exceptional circumstances
type DriftPreventionMonitor ¶
type DriftPreventionMonitor struct {
// contains filtered or unexported fields
}
DriftPreventionMonitor triggers periodic reconciliation to prevent configuration drift and keep HTTP Store caches warm across all replicas.
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.
The component runs on ALL replicas (not just the leader) to ensure HTTP Store caches stay warm. Only the leader's DeploymentScheduler will actually deploy.
Event subscriptions:
- DeploymentCompletedEvent: Reset drift prevention timer
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.
The component is subscribed to the EventBus during construction to ensure proper startup synchronization without timing-based sleeps.
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. The component is already subscribed to the EventBus (subscription happens in NewDriftPreventionMonitor()), so this method only processes events and manages the drift prevention timer:
- DeploymentCompletedEvent: Resets the drift prevention timer
- 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
Source Files