controller

Documentation

Overview

Package controller provides an API for implementing control loops on top of Consul resources. It is heavily inspired by Kubebuilder and the Kubernetes controller runtime.

Index

• func RequeueAfter(after time.Duration) error
• func RequeueNow() error
• type Controller
  • func ForType(managedType *pbresource.Type) Controller
  • func (c Controller) String() string
  • func (c Controller) WithBackoff(base, max time.Duration) Controller
  • func (c Controller) WithLogger(logger hclog.Logger) Controller
  • func (c Controller) WithPlacement(placement Placement) Controller
  • func (c Controller) WithReconciler(reconciler Reconciler) Controller
  • func (c Controller) WithWatch(watchedType *pbresource.Type, mapper DependencyMapper) Controller
• type DependencyMapper
  • func MapOwnerFiltered(filter *pbresource.Type) DependencyMapper
  • func ReplaceType(desiredType *pbresource.Type) DependencyMapper
• type Lease
• type Manager
  • func NewManager(client pbresource.ResourceServiceClient, logger hclog.Logger) *Manager
  • func (m *Manager) Register(ctrl Controller)
  • func (m *Manager) Run(ctx context.Context)
  • func (m *Manager) SetRaftLeader(leader bool)
• type Placement
  • func (p Placement) String() string
• type Reconciler
• type Request
  • func MapOwner(_ context.Context, _ Runtime, res *pbresource.Resource) ([]Request, error)
  • func (r Request) Key() string
• type RequeueAfterError
  • func (r RequeueAfterError) Error() string
• type Runtime

Functions

func RequeueAfter

func RequeueAfter(after time.Duration) error

RequeueAfter constructs a RequeueAfterError with the given duration setting.

func RequeueNow

func RequeueNow() error

RequeueNow constructs a RequeueAfterError that reschedules the Request immediately.

Types

type Controller

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

Controller runs a reconciliation loop to respond to changes in resources and their dependencies. It is heavily inspired by Kubernetes' controller pattern: https://kubernetes.io/docs/concepts/architecture/controller/

Use the builder methods in this package (starting with ForType) to construct a controller, and then pass it to a Manager to be executed.

func ForType

func ForType(managedType *pbresource.Type) Controller

ForType begins building a Controller for the given resource type.

func (Controller) String

func (c Controller) String() string

String returns a textual description of the controller, useful for debugging.

func (Controller) WithBackoff

func (c Controller) WithBackoff(base, max time.Duration) Controller

WithBackoff changes the base and maximum backoff values for the controller's retry rate limiter.

func (Controller) WithLogger

func (c Controller) WithLogger(logger hclog.Logger) Controller

WithLogger changes the controller's logger.

func (Controller) WithPlacement

func (c Controller) WithPlacement(placement Placement) Controller

WithPlacement changes where and how many replicas of the controller will run. In the majority of cases, the default placement (one leader elected instance per cluster) is the most appropriate and you shouldn't need to override it.

func (Controller) WithReconciler

func (c Controller) WithReconciler(reconciler Reconciler) Controller

WithReconciler changes the controller's reconciler.

func (Controller) WithWatch

func (c Controller) WithWatch(watchedType *pbresource.Type, mapper DependencyMapper) Controller

WithWatch adds a watch on the given type/dependency to the controller. mapper will be called to determine which resources must be reconciled as a result of a watched resource changing.

type DependencyMapper

type DependencyMapper func(
	ctx context.Context,
	rt Runtime,
	res *pbresource.Resource,
) ([]Request, error)

DependencyMapper is called when a dependency watched via WithWatch is changed to determine which of the controller's managed resources need to be reconciled.

func MapOwnerFiltered

func MapOwnerFiltered(filter *pbresource.Type) DependencyMapper

MapOwnerFiltered creates a DependencyMapper that returns owner IDs as Requests if the type of the owner ID matches the given filter type.

func ReplaceType

func ReplaceType(desiredType *pbresource.Type) DependencyMapper

ReplaceType creates a DependencyMapper that returns request IDs with the same name and tenancy as the original resource but with the type replaced with the type specified as this functions parameter.

type Lease

type Lease interface {
	// Held returns whether we are the current lease-holders.
	Held() bool

	// Changed returns a channel on which you can receive notifications whenever
	// the lease is acquired or lost.
	Changed() <-chan struct{}
}

Lease is used to ensure controllers are run as singletons (i.e. one leader- elected instance per cluster).

Currently, this is just an abstraction over Raft leadership. In the future, we'll build a backend-agnostic leasing system into the Resource Service which will allow us to balance controllers between many servers.

type Manager

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

Manager is responsible for scheduling the execution of controllers.

func NewManager

func NewManager(client pbresource.ResourceServiceClient, logger hclog.Logger) *Manager

NewManager creates a Manager. logger will be used by the Manager, and as the base logger for controllers when one is not specified using WithLogger.

func (*Manager) Register

func (m *Manager) Register(ctrl Controller)

Register the given controller to be executed by the Manager. Cannot be called once the Manager is running.

func (*Manager) Run

func (m *Manager) Run(ctx context.Context)

Run the Manager and start executing controllers until the given context is canceled. Cannot be called more than once.

func (*Manager) SetRaftLeader

func (m *Manager) SetRaftLeader(leader bool)

SetRaftLeader notifies the Manager of Raft leadership changes. Controllers are currently only executed on the Raft leader, so calling this method will cause the Manager to spin them up/down accordingly.

type Placement

type Placement int

Placement determines where and how many replicas of the controller will run.

const (
	// PlacementSingleton ensures there is a single, leader-elected, instance of
	// the controller running in the cluster at any time. It's the default and is
	// suitable for most use-cases.
	PlacementSingleton Placement = iota

	// PlacementEachServer ensures there is a replica of the controller running on
	// each server in the cluster. It is useful for cases where the controller is
	// responsible for applying some configuration resource to the server whenever
	// it changes (e.g. rate-limit configuration). Generally, controllers in this
	// placement mode should not modify resources.
	PlacementEachServer
)

func (Placement) String

func (p Placement) String() string

String satisfies the fmt.Stringer interface.

type Reconciler

type Reconciler interface {
	// Reconcile the resource identified by req.ID.
	Reconcile(ctx context.Context, rt Runtime, req Request) error
}

Reconciler implements the business logic of a controller.

type Request

type Request struct {
	// ID of the resource that needs to be reconciled.
	ID *pbresource.ID
}

Request represents a request to reconcile the resource with the given ID.

func MapOwner

func MapOwner(_ context.Context, _ Runtime, res *pbresource.Resource) ([]Request, error)

MapOwner implements a DependencyMapper that returns the updated resource's owner.

func (Request) Key

func (r Request) Key() string

Key satisfies the queue.ItemType interface. It returns a string which will be used to de-duplicate requests in the queue.

type RequeueAfterError

type RequeueAfterError time.Duration

RequeueAfterError is an error that allows a Reconciler to override the exponential backoff behavior of the Controller, rather than applying the backoff algorithm, returning a RequeueAfterError will cause the Controller to reschedule the Request at a given time in the future.

func (RequeueAfterError) Error

func (r RequeueAfterError) Error() string

Error implements the error interface.

type Runtime

type Runtime struct {
	Client pbresource.ResourceServiceClient
	Logger hclog.Logger
}

Runtime contains the dependencies required by reconcilers.