Documentation
¶
Overview ¶
Package controller provide a simple pattern for async operations that require retries and/or regular intervals.
Index ¶
- func GetGlobalStatus() models.ControllerStatuses
- func NoopFunc(ctx context.Context) error
- type Controller
- type ControllerFunc
- type ControllerParams
- type ExitReason
- type Manager
- func (m *Manager) GetStatusModel() models.ControllerStatuses
- func (m *Manager) RemoveAll()
- func (m *Manager) RemoveAllAndWait()
- func (m *Manager) RemoveController(name string) error
- func (m *Manager) RemoveControllerAndWait(name string) error
- func (m *Manager) TerminationChannel(name string) chan struct{}
- func (m *Manager) TriggerController(name string)
- func (m *Manager) UpdateController(name string, params ControllerParams)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetGlobalStatus ¶
func GetGlobalStatus() models.ControllerStatuses
GetGlobalStatus returns the status of all controllers
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
Controller is a simple pattern that allows to perform the following tasks:
- Run an operation in the background and retry until it succeeds
- Perform a regular sync operation in the background
A controller has configurable retry intervals and will collect statistics on number of successful runs, number of failures, last error message, and last error timestamp.
Controllers have a name and are tied to a Manager. The manager is typically bound to higher level objects such as endpoint. These higher level objects can then run multiple controllers to perform async tasks such as:
- Annotating k8s resources with values
- Synchronizing an object with the kvstore
- Any other async operation to may fail and require retries
Embedding the Manager into higher level resources allows to bind controllers to the lifetime of that object. Controllers also have a UUID to allow correlating all log messages of a controller instance.
Guidelines to writing controllers:
- Make sure that the task the controller performs is done in an atomic fashion, e.g. if a controller modifies a resource in multiple steps, an intermediate manipulation operation failing should not leave behind an inconsistent state. This can typically be achieved by locking the resource and rolling back or by using transactions.
- Controllers typically act on behalf of a higher level object such as an endpoint. The controller must ensure that the higher level object is properly locked when accessing any fields.
- Controllers run asynchronously in the background, it is the responsibility of the controller to be aware of the lifecycle of the owning higher level object. This is typically achieved by removing all controllers when the owner dies. It is the responsibility of the owner to either lock the owner in a way that will delay destruction throughout the controller run or to check for the destruction throughout the run.
func (*Controller) GetFailureCount ¶
func (c *Controller) GetFailureCount() int
GetFailureCount returns the number of failed controller runs
func (*Controller) GetLastError ¶
func (c *Controller) GetLastError() error
GetLastError returns the last error returned
func (*Controller) GetLastErrorTimestamp ¶
func (c *Controller) GetLastErrorTimestamp() time.Time
GetLastErrorTimestamp returns the last error returned
func (*Controller) GetStatusModel ¶
func (c *Controller) GetStatusModel() *models.ControllerStatus
GetStatusModel returns a models.ControllerStatus representing the controller's configuration & status
func (*Controller) GetSuccessCount ¶
func (c *Controller) GetSuccessCount() int
GetSuccessCount returns the number of successful controller runs
type ControllerFunc ¶
ControllerFunc is a function that the controller runs. This type is used for DoFunc and StopFunc.
type ControllerParams ¶
type ControllerParams struct {
// DoFunc is the function that will be run until it succeeds and/or
// using the interval RunInterval if not 0.
// An unset DoFunc is an error and will be logged as one.
DoFunc ControllerFunc
// StopFunc is called when the controller stops. It is intended to run any
// clean-up tasks for the controller (e.g. deallocate/release resources)
// It is guaranteed that DoFunc is called at least once before StopFunc is
// called.
// An unset StopFunc is not an error (and will be a no-op)
// Note: Since this occurs on controller exit, error counts and tracking may
// not be checked after StopFunc is run.
StopFunc ControllerFunc
// If set to any other value than 0, will cause DoFunc to be run in the
// specified interval. The interval starts from when the DoFunc has
// returned last
RunInterval time.Duration
// ErrorRetryBaseDuration is the initial time to wait to run DoFunc
// again on return of an error. On each consecutive error, this value
// is multiplied by the number of consecutive errors to provide a
// constant back off. The default is 1s.
ErrorRetryBaseDuration time.Duration
// NoErrorRetry when set to true, disabled retries on errors
NoErrorRetry bool
Context context.Context
}
ControllerParams contains all parameters of a controller
type ExitReason ¶
type ExitReason struct {
// contains filtered or unexported fields
}
ExitReason is a returnable type from DoFunc that causes the controller to exit. This reason is recorded in the controller's status. The controller is not removed from any manager. Construct one with NewExitReason("a reason")
func NewExitReason ¶
func NewExitReason(reason string) ExitReason
NewExitReason returns a new ExitReason
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is a list of controllers
func FakeManager ¶
FakeManager returns a fake controller manager with the specified number of failing controllers. The returned manager is identical in any regard except for internal pointers.
func (*Manager) GetStatusModel ¶
func (m *Manager) GetStatusModel() models.ControllerStatuses
GetStatusModel returns the status of all controllers as models.ControllerStatuses
func (*Manager) RemoveAll ¶
func (m *Manager) RemoveAll()
RemoveAll stops and removes all controllers of the manager
func (*Manager) RemoveAllAndWait ¶
func (m *Manager) RemoveAllAndWait()
RemoveAllAndWait stops and removes all controllers of the manager and then waits for all controllers to exit
func (*Manager) RemoveController ¶
RemoveController stops and removes a controller from the manager. If DoFunc is currently running, DoFunc is allowed to complete in the background.
func (*Manager) RemoveControllerAndWait ¶
RemoveControllerAndWait stops and removes a controller using RemoveController() and then waits for it to run to completion.
func (*Manager) TerminationChannel ¶
TerminationChannel returns a channel that is closed after the controller has been terminated
func (*Manager) TriggerController ¶
TriggerController triggers the controller with the specified name.
func (*Manager) UpdateController ¶
func (m *Manager) UpdateController(name string, params ControllerParams)
UpdateController installs or updates a controller in the manager. A controller is identified by its name. If a controller with the name already exists, the controller will be shut down and replaced with the provided controller. Updating a controller will cause the DoFunc to be run immediately regardless of any previous conditions. It will also cause any statistics to be reset.
Source Files