A tiny framework for building a particular type of Kubernetes controllers. Opinionated, of course.


Pull requests, issues and comments welcome. For pull requests:

  • Add tests for new features and bug fixes
  • Follow the existing style
  • Separate unrelated changes into multiple pull requests

See the existing issues for things to start contributing.

For bigger changes, make sure you start a discussion first by creating an issue and explaining the intended change.

Atlassian requires contributors to sign a Contributor License Agreement, known as a CLA. This serves as a record stating that the contributor is entitled to contribute the code/documentation/translation to the project and is willing to have it used in distributions and derivative works (or is willing to transfer ownership).

Prior to accepting your contributions we ask that you please follow the appropriate link below to digitally sign the CLA. The Corporate CLA is for those who are contributing as a member of an organization and the individual CLA is for those contributing as an individual.


Copyright (c) 2018 Atlassian and others. Apache 2.0 licensed, see LICENSE file.

Expand ▾ Collapse ▴




This section is empty.


This section is empty.


This section is empty.


type Config

type Config struct {
	AppName      string
	Logger       *zap.Logger
	Namespace    string
	ResyncPeriod time.Duration
	Registry     prometheus.Registerer

	RestConfig *rest.Config
	MainClient kubernetes.Interface

type Constructed

type Constructed struct {
	// Interface holds an optional controller interface.
	Interface Interface
	// Server holds an optional server interface.
	Server Server

type Constructor

type Constructor interface {
	// New constructs a new controller and/or server.
	// If it constructs a controller, it must register an informer for the GVK controller
	// handles via Context.RegisterInformer().
	New(*Config, *Context) (*Constructed, error)
	Describe() Descriptor

type Context

type Context struct {
	// ReadyForWork is a function that the controller must call from its Run() method once it is ready to
	// process work using it's Process() method. This should be used to delay processing while some initialization
	// is being performed.
	ReadyForWork func()
	// Middleware is the standard middleware that is supposed to be used to wrap the http handler of the server.
	Middleware func(http.Handler) http.Handler
	// Will contain all informers once Generic controller constructs all controllers.
	// This is a read only field, must not be modified.
	Informers map[schema.GroupVersionKind]cache.SharedIndexInformer
	// Will contain all controllers once Generic controller constructs them.
	// This is a read only field, must not be modified.
	Controllers map[schema.GroupVersionKind]Interface
	WorkQueue   WorkQueueProducer

func (*Context) RegisterInformer

func (c *Context) RegisterInformer(gvk schema.GroupVersionKind, inf cache.SharedIndexInformer) error

type Descriptor

type Descriptor struct {
	// Group Version Kind of objects a controller can process.
	Gvk schema.GroupVersionKind

type FlagSet

type FlagSet interface {
	DurationVar(p *time.Duration, name string, value time.Duration, usage string)
	IntVar(p *int, name string, value int, usage string)
	Float64Var(p *float64, name string, value float64, usage string)
	StringVar(p *string, name string, value string, usage string)
	BoolVar(p *bool, name string, value bool, usage string)
	UintVar(p *uint, name string, value uint, usage string)
	Int64Var(p *int64, name string, value int64, usage string)
	Uint64Var(p *uint64, name string, value uint64, usage string)

type Interface

type Interface interface {

	// Process is implemented by the controller and returns:
	// - true for externalErr if the error is not an internal error
	// - true for retriableErr if the error is a retriable error (i.e. should be
	//   added back to the work queue). These are retried for limited number of
	//   attempts
	// - an error, if there is an error, or nil. If there is no error, the above
	//   two bools (externalErr and retriableErr) are ignored.
	Process(*ProcessContext) (externalErr bool, retriableErr bool, err error)

type Operation

type Operation string
const (
	UpdatedOperation Operation = "updated"
	DeletedOperation Operation = "deleted"
	AddedOperation   Operation = "added"

func (Operation) String

func (o Operation) String() string

type ProcessContext

type ProcessContext struct {
	Logger *zap.Logger
	Object runtime.Object

type QueueKey

type QueueKey struct {
	Namespace string
	Name      string

type Server

type Server interface {
	Run(context.Context) error

type WorkQueueProducer

type WorkQueueProducer interface {
	// Add adds an item to the workqueue.

Source Files