ctrl

README

ctrl

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

Contributing

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.

• CLA for corporate contributors
• CLA for individuals

License

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

Documentation

Index

• type Config
• type Constructed
• type Constructor
• type Context
  • func (c *Context) MainClusterInformer(config *Config, gvk schema.GroupVersionKind, ...) (cache.SharedIndexInformer, error)
  • func (c *Context) MainInformer(config *Config, gvk schema.GroupVersionKind, ...) (cache.SharedIndexInformer, error)
  • func (c *Context) RegisterInformer(gvk schema.GroupVersionKind, inf cache.SharedIndexInformer) error
• type Descriptor
• type FlagSet
• type Interface
• type Operation
  • func (o Operation) String() string
• type ProcessContext
• type QueueKey
• type Server
• type WorkQueueProducer

Types

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 {
	AddFlags(FlagSet)
	// 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) MainClusterInformer

func (c *Context) MainClusterInformer(config *Config, gvk schema.GroupVersionKind, f func(kubernetes.Interface, time.Duration, cache.Indexers) cache.SharedIndexInformer) (cache.SharedIndexInformer, error)

func (*Context) MainInformer

func (c *Context) MainInformer(config *Config, gvk schema.GroupVersionKind, f func(kubernetes.Interface, string, time.Duration, cache.Indexers) cache.SharedIndexInformer) (cache.SharedIndexInformer, error)

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 {
	Run(context.Context)

	// 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.
	Add(QueueKey)
}