controller

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
  • func (c *Controller) GetFailureCount() int
  • func (c *Controller) GetLastError() error
  • func (c *Controller) GetLastErrorTimestamp() time.Time
  • func (c *Controller) GetStatusModel() *models.ControllerStatus
  • func (c *Controller) GetSuccessCount() int
  • func (c *Controller) Trigger()
• type ControllerFunc
• type ControllerParams
• type ExitReason
  • func NewExitReason(reason string) ExitReason
• type Manager
  • func FakeManager(failingControllers int) *Manager
  • func NewManager() *Manager
  • func (m *Manager) CreateController(name string, params ControllerParams) bool
  • 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)

Functions

func GetGlobalStatus

func GetGlobalStatus() models.ControllerStatuses

GetGlobalStatus returns the status of all controllers

func NoopFunc

func NoopFunc(ctx context.Context) error

NoopFunc is a no-op placeholder for DoFunc & StopFunc. It is automatically used when StopFunc is undefined, and can be used as a DoFunc stub when the controller should only run StopFunc.

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

func (*Controller) Trigger

func (c *Controller) Trigger()

Trigger triggers the controller

type ControllerFunc

type ControllerFunc func(ctx context.Context) error

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

	// CancelDoFuncOnUpdate when set to true cancels the controller context
	// (the DoFunc) to allow quick termination of controller
	CancelDoFuncOnUpdate bool

	// 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

	// If set to any other value than 0, will cap the error retry interval
	// to the specified interval.
	MaxRetryInterval 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

func FakeManager(failingControllers int) *Manager

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 NewManager

func NewManager() *Manager

NewManager allocates a new manager

func (*Manager) CreateController

func (m *Manager) CreateController(name string, params ControllerParams) bool

CreateController installs a new controller in the manager. If a controller with the name already exists this method returns false without triggering, otherwise creates the controller and runs it immediately.

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

func (m *Manager) RemoveController(name string) error

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

func (m *Manager) RemoveControllerAndWait(name string) error

RemoveControllerAndWait stops and removes a controller using RemoveController() and then waits for it to run to completion.

func (*Manager) TerminationChannel

func (m *Manager) TerminationChannel(name string) chan struct{}

TerminationChannel returns a channel that is closed after the controller has been terminated

func (*Manager) TriggerController

func (m *Manager) TriggerController(name string)

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.