controller

Documentation

Overview

Package controller defines common interfaces to be implemented by the controllers and controller runtime.

Index

• type Controller
• type DependencyEdge
• type DependencyEdgeType
• type DependencyGraph
• type Engine
• type Input
  • func (a Input) Compare(b Input) int
  • func (a Input) EqualKeys(b Input) bool
• type InputKind
• type Option
  • func WithOwner(owner string) Option
• type Options
  • func ToOptions(opts ...Option) Options
• type Output
• type OutputKind
• type OutputTracker
• type QController
• type QRuntime
• type QSettings
• type Reader
• type ReaderWriter
• type ReconcileEvent
• type RequeueError
  • func NewRequeueError(err error, interval time.Duration) *RequeueError
  • func NewRequeueErrorf(interval time.Duration, format string, args ...interface{}) *RequeueError
  • func NewRequeueInterval(interval time.Duration) *RequeueError
  • func (err *RequeueError) Err() error
  • func (err *RequeueError) Error() string
  • func (err *RequeueError) Interval() time.Duration
  • func (err *RequeueError) Unwrap() error
• type Runtime
• type UncachedReader
• type Writer

Types

type Controller

type Controller interface {
	Name() string
	Inputs() []Input
	Outputs() []Output

	Run(context.Context, Runtime, *zap.Logger) error
}

Controller interface should be implemented by Controllers.

type DependencyEdge

type DependencyEdge struct {
	ControllerName string

	ResourceNamespace resource.Namespace
	ResourceType      resource.Type
	ResourceID        resource.ID

	EdgeType DependencyEdgeType
}

DependencyEdge represents relationship between controller and resource(s).

type DependencyEdgeType

type DependencyEdgeType int

DependencyEdgeType is edge type in controller graph.

const (
	EdgeOutputExclusive DependencyEdgeType = iota
	EdgeOutputShared
	EdgeInputStrong
	EdgeInputWeak
	EdgeInputDestroyReady
	EdgeInputQPrimary
	EdgeInputQMapped
	EdgeInputQMappedDestroyReady
)

Controller graph edge types.

type DependencyGraph

type DependencyGraph struct {
	Edges []DependencyEdge
}

DependencyGraph is the exported information about controller/resources dependencies.

type Engine

type Engine interface {
	// RegisterController registers new controller.
	RegisterController(ctrl Controller) error
	// RegisterQController registers new QController.
	RegisterQController(ctrl QController) error
	// Run the controllers.
	Run(ctx context.Context) error
}

Engine is the entrypoint into Controller Runtime.

type Input

type Input struct {
	Namespace resource.Namespace
	Type      resource.Type
	ID        optional.Optional[resource.ID]
	Kind      InputKind
}

Input of the controller (dependency on some resource(s)).

Each controller might have multiple inputs, it might depend on all the objects of some type under namespace, or on specific object by ID.

Input might be either Weak or Strong. Any kind of input triggers cascading reconcile on changes, Strong dependencies in addition block deletion of parent object until all the dependencies are torn down.

Input can also be "DestroyReady" which means that the controller is watching some of its outputs to be ready to be destroyed. Controller will be notified when the resource enters "teardown" phase and has no finalizers attached. Resources are filtered to be owned by the controller.

func (Input) Compare

func (a Input) Compare(b Input) int

Compare defines Input sort order.

func (Input) EqualKeys

func (a Input) EqualKeys(b Input) bool

EqualKeys checks if two Inputs have equal (conflicting) keys.

type InputKind

type InputKind = int

InputKind for inputs.

const (
	InputWeak InputKind = iota
	InputStrong
	InputDestroyReady
	// InputQPrimary is put to the queue of the QController directly by metadata.
	InputQPrimary
	// InputQMapped is mapped by the QController to one of the primary inputs.
	InputQMapped
	// InputQMappedDestroyReady is mapped by the QController to one of the primary inputs.
	//
	// On top of mapping, filtered by FilterDestroyReady.
	InputQMappedDestroyReady
)

Input kinds.

type Option

type Option func(*Options)

Option for operation.

func WithOwner

func WithOwner(owner string) Option

WithOwner allows to specify owner of the resource.

type Options

type Options struct {
	Owner *string
}

Options for operation.

func ToOptions

func ToOptions(opts ...Option) Options

ToOptions converts variadic options to Options.

type Output

type Output struct {
	Type resource.Type
	Kind OutputKind
}

Output of the controller.

Controller can only modify resources which are declared as outputs.

type OutputKind

type OutputKind = int

OutputKind for outputs.

const (
	OutputExclusive OutputKind = iota
	OutputShared
)

Output kinds.

type OutputTracker

type OutputTracker interface {
	StartTrackingOutputs()
	CleanupOutputs(ctx context.Context, outputs ...resource.Kind) error
}

OutputTracker provides automatic cleanup of the outputs based on the calls to Modify function.

OutputTracker is optional, it is enabled by calling StartTrackingOutputs at the beginning of the reconcile cycle. Every call to Modify will be tracked and the outputs which are not touched will be destroyed. Finalize the cleanup by calling CleanupOutputs at the end of the reconcile cycle, it also automatically calls ResetRestartBackoff.

CleanupOutputs doesn't support finalizers on output resources.

type QController

type QController interface {
	// Name returns the name of the controller.
	Name() string

	// Settings is called exactly once before the controller is started.
	Settings() QSettings

	// Reconcile is called for each item in the queue.
	//
	// Reconcile might be called concurrently for different resource.Pointers.
	// If Reconcile succeeds, the item is removed from the queue.
	// If Reconcile fails, the item is requeued with exponential backoff.
	Reconcile(context.Context, *zap.Logger, QRuntime, resource.Pointer) error

	// MapInput is called for each input of kind ItemQMapped.
	//
	// MapInput returns the item(s) which should be put to the queue for the mapped input.
	// For example, MapInput might convert watch events in secondary input to primary input items.
	//
	// MapInput failures are treated in the same way as Reconcile failures.
	MapInput(context.Context, *zap.Logger, QRuntime, resource.Pointer) ([]resource.Pointer, error)
}

QController interface should be implemented by queue-based Controllers.

What is difference between Controller and QController?

Controller is triggered for any change in inputs, and the change is unspecified. Multiple changes in inputs are coalesced into a single change as long as the controller is busy reconciling previous changes. Controller always processes all inputs (i.e. it lists and transforms the all in a single reconcile loop). If the Controller fails, it is retried with exponential backoff, but for all inputs.

QController always processes a single input, but different inputs might be processed in parallel (in goroutines). QController has a queue of items to be reconciled, with an optional backoff for each item. QController can return an error (fail) for a single item, and the item will be retried with exponential backoff (requeue after). QController should use finalizers on inputs to ensure that outputs are cleaned up properly. On startup, QController queue is filled with all inputs.

Controller might be triggered by events not related to the controller runtime (e.g. Linux inotify), QController doesn't support that.

type QRuntime

type QRuntime interface {
	ReaderWriter
	UncachedReader
}

QRuntime interface as presented to the QController.

type QSettings

type QSettings struct {
	RunHook      func(context.Context, *zap.Logger, QRuntime) error
	ShutdownHook func()
	Inputs       []Input
	Outputs      []Output
	Concurrency  optional.Optional[uint]
}

QSettings configures runtime for the QController.

type Reader

type Reader interface {
	Get(context.Context, resource.Pointer, ...state.GetOption) (resource.Resource, error)
	List(context.Context, resource.Kind, ...state.ListOption) (resource.List, error)
	ContextWithTeardown(context.Context, resource.Pointer) (context.Context, error)
}

Reader provides read-only access to the state.

Interface state.State also satisfies this interface.

type ReaderWriter

type ReaderWriter interface {
	Reader
	Writer
}

ReaderWriter combines Reader and Writer interfaces.

type ReconcileEvent

type ReconcileEvent struct{}

ReconcileEvent is a signal for controller to reconcile its resources.

type RequeueError

type RequeueError struct {
	// contains filtered or unexported fields
}

RequeueError is returned by QController.Reconcile to requeue the item with specified backoff.

RequeueError might contain or might not contain an actual error, in either case the item is requeued with specified backoff. If the error is not nil, the error is logged and counted as a controller crash.

func NewRequeueError

func NewRequeueError(err error, interval time.Duration) *RequeueError

NewRequeueError creates a new RequeueError.

func NewRequeueErrorf

func NewRequeueErrorf(interval time.Duration, format string, args ...interface{}) *RequeueError

NewRequeueErrorf creates a new RequeueError with specified backoff interval.

func NewRequeueInterval

func NewRequeueInterval(interval time.Duration) *RequeueError

NewRequeueInterval creates a new RequeueError with specified backoff interval.

func (*RequeueError) Err

func (err *RequeueError) Err() error

Err returns the error.

func (*RequeueError) Error

func (err *RequeueError) Error() string

Error implements error interface.

func (*RequeueError) Interval

func (err *RequeueError) Interval() time.Duration

Interval returns the backoff interval.

func (*RequeueError) Unwrap

func (err *RequeueError) Unwrap() error

Unwrap implements errors.Unwrap interface.

type Runtime

type Runtime interface {
	EventCh() <-chan ReconcileEvent
	QueueReconcile()
	ResetRestartBackoff()

	UpdateInputs([]Input) error

	Reader
	UncachedReader
	Writer
	OutputTracker
}

Runtime interface as presented to the controller.

type UncachedReader

type UncachedReader interface {
	GetUncached(context.Context, resource.Pointer, ...state.GetOption) (resource.Resource, error)
	ListUncached(context.Context, resource.Kind, ...state.ListOption) (resource.List, error)
}

UncachedReader provides read-only access to the state without cache.

It might cause performance penalty, use only when necessary.

type Writer

type Writer interface {
	Create(context.Context, resource.Resource) error
	Update(context.Context, resource.Resource) error
	Modify(context.Context, resource.Resource, func(resource.Resource) error) error
	ModifyWithResult(context.Context, resource.Resource, func(resource.Resource) error) (resource.Resource, error)
	Teardown(context.Context, resource.Pointer, ...Option) (bool, error)
	Destroy(context.Context, resource.Pointer, ...Option) error

	AddFinalizer(context.Context, resource.Pointer, ...resource.Finalizer) error
	RemoveFinalizer(context.Context, resource.Pointer, ...resource.Finalizer) error
}

Writer provides write access to the state.

Only output objects can be written to by the controller.