controller

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
)

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 (a Input) Compare(b Input) int

func (a Input) EqualKeys(b Input) bool

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
)

type Option ¶ added in v0.3.1

type Option func(*Options)

Option for operation.

func WithOwner(owner string) Option

type Options ¶ added in v0.3.1

type Options struct {
	Owner *string
}

Options for operation.

func ToOptions(opts ...Option) 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
)

type OutputTracker ¶ added in v0.3.1

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 ¶ added in v0.4.0

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 ¶ added in v0.4.0

type QRuntime interface {
	ReaderWriter
}

QRuntime interface as presented to the QController.

type QSettings ¶ added in v0.4.0

type QSettings struct {
	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 ¶ added in v0.3.0

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 ¶ added in v0.4.0

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(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 Runtime interface {
	EventCh() <-chan ReconcileEvent
	QueueReconcile()
	ResetRestartBackoff()

	UpdateInputs([]Input) error

	Reader
	Writer
	OutputTracker
}

Runtime interface as presented to the controller.

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.