controller

Documentation

Overview

Package controller provide a simple pattern for async operations that require retries and/or regular intervals.

Index

• Variables
• func GetGlobalStatus() models.ControllerStatuses
• func Init(cfg Config, m Metrics)
• func NoopFunc(ctx context.Context) error
• type Config
  • func (cfg Config) Flags(flags *pflag.FlagSet)
• type ControllerFunc
• type ControllerParams
• type ExitReason
  • func NewExitReason(reason string) ExitReason
• type Group
  • func NewGroup(name string) Group
• 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) TriggerController(name string)
  • func (m *Manager) UpdateController(name string, params ControllerParams)
• type Metrics
  • func NewMetrics() Metrics

Variables

var Cell = cell.Module(
	"controller",
	"Controllers and Controller Lifecycle management",
	cell.Config(Config{}),
	cell.Metric(NewMetrics),
	cell.Invoke(Init),
)

var (

	// GroupRuns is a Prometheus-compatible metric for Controller
	// runs, labeled by completion status and Group name
	GroupRuns = metrics.NoOpCounterVec
)

Functions

func GetGlobalStatus

func GetGlobalStatus() models.ControllerStatuses

GetGlobalStatus returns the status of all controllers

func Init

func Init(cfg Config, m Metrics)

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 Config

type Config struct {
	// ControllerGroupMetrics is an option which specifies the set of ControllerGroups names
	// for which metrics will be enabled. The special values 'all' and 'none' are supported.
	ControllerGroupMetrics []string
}

func (Config) Flags

func (cfg Config) Flags(flags *pflag.FlagSet)

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 {
	// Group is used for aggregate metrics collection.
	// The Group.Name must NOT be dynamically generated from a
	// resource identifier in order to limit metrics cardinality.
	Group Group

	HealthReporter cell.HealthReporter

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

type Group struct {
	// Name of the controller group.
	//
	// This name MUST NOT be dynamically generated based on
	// resource identifier in order to limit metrics cardinality.
	Name string
}

Group contains metadata about a group of controllers

func NewGroup

func NewGroup(name string) Group

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. Used for testing only.

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) 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 primarily 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.

type Metrics

type Metrics struct {
	ControllerGroupRuns metric.Vec[metric.Counter]
}

func NewMetrics

func NewMetrics() Metrics