README
¶
pkg/controller/configchange
Configuration validation orchestrator and reinitialization signaller.
Overview
ConfigChangeHandler bridges configuration parsing, validation, and controller reinitialization. It does not watch any Kubernetes resource — that's the job of the CRD watcher in pkg/controller. Instead it consumes events:
- Validation orchestration — subscribes to
ConfigParsedEvent, fans aConfigValidationRequestout to all registered validators (basic,template,jsonpath) using the bus's scatter-gather (bus.Request), aggregates theConfigValidationResponseevents, and publishes eitherConfigValidatedEventorConfigInvalidEvent. The scatter-gather can take tens of seconds (thevalidationtestsvalidator runs the config's full embedded suite), so it runs off the event loop — single-flight, latest-wins for parsed configs arriving mid-validation — keeping side events (most critically theBecameLeaderEventstate replay for leader-only components) responsive throughout. - Reinitialization signal — subscribes to its own
ConfigValidatedEventoutput and forwards the validated config on a channel back to the controller, debounced so rapid CRD updates coalesce into a single reinit.
This package also contains StatusUpdater, which writes validation results back onto the HAProxyTemplateConfig CRD's status subresource.
Quick Start
import "gitlab.com/haproxy-haptic/haptic/pkg/controller/configchange"
configChangeCh := make(chan *coreconfig.Config, 1)
handler := configchange.NewConfigChangeHandler(
bus,
logger,
configChangeCh,
[]string{"basic", "template", "jsonpath"}, // validator names that must respond
0, // 0 → DefaultReinitDebounceInterval (2s)
)
go handler.Start(ctx)
// Elsewhere: react to the reinit signal
for cfg := range configChangeCh {
// controller restarts its iteration with cfg
}
The handler also exposes SetInitialConfigVersion and EnableReinitialization to suppress the bootstrap ConfigValidatedEvent that the CRD watcher emits at startup; without those calls every cold start would reinit itself.
Events
- Subscribes:
ConfigParsedEvent,ConfigValidatedEvent,BecameLeaderEvent,CredentialsUpdatedEvent - Publishes:
ConfigValidationRequest(scatter),ConfigValidatedEvent,ConfigInvalidEvent - Receives:
ConfigValidationResponse(gather — collected viabus.Request, not a registered responder)
License
Apache-2.0 — see root LICENSE.
Documentation
¶
Index ¶
- Constants
- Variables
- type ConfigChangeHandler
- func (h *ConfigChangeHandler) EnableReinitialization()
- func (h *ConfigChangeHandler) SetEffectiveResolver(resolve func(*coreconfig.Config) (*coreconfig.Config, error))
- func (h *ConfigChangeHandler) SetInitialConfigVersion(version string)
- func (h *ConfigChangeHandler) SetInitialCredentialsVersion(version string)
- func (h *ConfigChangeHandler) Start(ctx context.Context) error
- type StatusUpdater
Constants ¶
const ( // ComponentName is the unique identifier for this component. ComponentName = "configchange-handler" // EventBufferSize is the size of the event subscription buffer. // Moderate-volume component handling config and validation events. EventBufferSize = busevents.StandardSubscriberBuffer )
const ( // StatusUpdaterComponentName is the unique identifier for this component. StatusUpdaterComponentName = "status-updater" // StatusUpdaterEventBufferSize is the size of the event subscription buffer. StatusUpdaterEventBufferSize = busevents.StandardSubscriberBuffer )
Variables ¶
var DefaultReinitDebounceInterval = types.DefaultDebounceInterval
DefaultReinitDebounceInterval is the default time to wait after the last config change before signaling controller reinitialization. This allows rapid CRD updates to be coalesced, ensuring templates are fully rendered before reinitialization starts. Reuses the lenient per-watcher debounce default (types.DefaultDebounceInterval, 2s): CRD config edits are operator-initiated and tolerate a couple of seconds of coalescing, like other structural changes.
Functions ¶
This section is empty.
Types ¶
type ConfigChangeHandler ¶
type ConfigChangeHandler struct {
// contains filtered or unexported fields
}
ConfigChangeHandler coordinates configuration validation and detects config changes.
This component has two main responsibilities:
Validation Coordination: Subscribes to ConfigParsedEvent, sends ConfigValidationRequest, collects responses from validators using scatter-gather pattern, and publishes ConfigValidatedEvent or ConfigInvalidEvent.
Change Detection: Subscribes to ConfigValidatedEvent and signals the controller to reinitialize via the configChangeCh channel with debouncing to coalesce rapid changes.
Debouncing behavior: When multiple CRD config changes arrive in rapid succession, the handler debounces the reinitialization signal. This ensures all pending renders complete before reinitialization starts, preventing the race condition where reinitialization cancels in-progress renders.
Architecture: This component bridges the gap between configuration parsing and validation, and between validation and controller reinitialization. It uses the scatter-gather pattern from the event bus for coordinating validation across multiple validators.
func NewConfigChangeHandler ¶
func NewConfigChangeHandler( eventBus *busevents.EventBus, logger *slog.Logger, configChangeCh chan<- *coreconfig.Config, validators []string, debounceInterval time.Duration, ) *ConfigChangeHandler
NewConfigChangeHandler creates a new ConfigChangeHandler.
Parameters:
- eventBus: The EventBus to subscribe to and publish on
- logger: Structured logger for diagnostics
- configChangeCh: Channel to signal controller reinitialization with validated config
- validators: List of expected validator names (e.g., ["basic", "template", "jsonpath"])
- debounceInterval: Time to wait after last config change before triggering reinitialization. Use 0 for default (500ms).
Returns:
- *ConfigChangeHandler ready to start
func (*ConfigChangeHandler) EnableReinitialization ¶
func (h *ConfigChangeHandler) EnableReinitialization()
EnableReinitialization enables the reinitialization signaling mechanism.
This must be called after controller startup is complete to allow config changes to trigger reinitialization. During startup, ConfigValidatedEvents occur that should NOT trigger reinitialization. Calling this method signals that the startup phase is complete and future config changes should trigger reinitialization.
Note: CRDWatcher uses generation-based filtering, so status-only updates (which don't increment generation) never trigger ConfigValidatedEvents in the first place.
func (*ConfigChangeHandler) SetEffectiveResolver ¶
func (h *ConfigChangeHandler) SetEffectiveResolver(resolve func(*coreconfig.Config) (*coreconfig.Config, error))
SetEffectiveResolver installs the effective-config transformation applied to every parsed config before validation (see the field doc). Like SetInitialConfigVersion, this must be called after construction and before the CRD watcher starts delivering events.
func (*ConfigChangeHandler) SetInitialConfigVersion ¶
func (h *ConfigChangeHandler) SetInitialConfigVersion(version string)
SetInitialConfigVersion sets the initial config version to prevent reinitialization on bootstrap ConfigValidatedEvent.
This must be called after fetching the initial config but before CRDWatcher starts. When CRDWatcher's informer triggers onAdd for the existing CRD, it publishes a ConfigValidatedEvent with the same version. Without this tracking, that event would trigger reinitialization, creating an infinite loop.
Parameters:
- version: The resourceVersion from the initial CRD fetch
func (*ConfigChangeHandler) SetInitialCredentialsVersion ¶
func (h *ConfigChangeHandler) SetInitialCredentialsVersion(version string)
SetInitialCredentialsVersion records the resourceVersion of the credentials Secret as observed at iteration startup, so the bootstrap CredentialsUpdatedEvent (fired by the watcher's initial onAdd) doesn't trigger a redundant reinitialization loop.
func (*ConfigChangeHandler) Start ¶
func (h *ConfigChangeHandler) Start(ctx context.Context) error
Start begins processing events from the EventBus.
This method blocks until the context is canceled. The component is already subscribed to the EventBus (subscription happens in constructor). Returns nil on graceful shutdown.
Example:
go handler.Start(ctx)
type StatusUpdater ¶
StatusUpdater updates HAProxyTemplateConfig status based on validation results.
This component subscribes to ConfigValidatedEvent, ConfigInvalidEvent, and ValidationFailedEvent, updating the HAProxyTemplateConfig CRD status to reflect validation state. Users can then see validation errors via `kubectl describe haproxytemplateconfig`.
Architecture: This is an event adapter that bridges validation events to Kubernetes API updates. It uses the generated typed client for HAProxyTemplateConfig status updates.
The component handles two types of validation: - Config validation (Stage 1): Template syntax, JSONPath expressions, etc. - HAProxy validation (Stage 4): Rendered config syntax check with haproxy -c.
func NewStatusUpdater ¶
func NewStatusUpdater( crdClient versioned.Interface, kubeClient kubernetes.Interface, eventBus *busevents.EventBus, logger *slog.Logger, ) *StatusUpdater
NewStatusUpdater creates a new StatusUpdater.
Parameters:
- crdClient: typed client for HAProxyTemplateConfig CRD status updates
- kubeClient: core client used to emit Kubernetes Events on the CRD
- eventBus: EventBus to subscribe to validation events
- logger: Structured logger for diagnostics
Returns:
- *StatusUpdater ready to start
func (*StatusUpdater) HandleEvent ¶
func (u *StatusUpdater) HandleEvent(event busevents.Event)
HandleEvent implements component.EventHandler, routing each validation event to the matching status-update handler using the loop context captured by Start.
Source Files