cache

Documentation

Overview

Package cache provides object caches that act as caching client.Reader instances and help drive Kubernetes-object-based event handlers.

Index

• type ByObject
• type Cache
  • func New(cfg *rest.Config, opts Options) (Cache, error)
• type Config
• type ErrCacheNotStarted
  • func (*ErrCacheNotStarted) Error() string
• type ErrResourceNotCached
  • func (r ErrResourceNotCached) Error() string
• type Informer
• type InformerGetOption
  • func BlockUntilSynced(shouldBlock bool) InformerGetOption
• type InformerGetOptions
• type Informers
• type NewCacheFunc
• type Options

Types

type ByObject

type ByObject struct {
	// Namespaces maps a namespace name to cache configs. If set, only the
	// namespaces in this map will be cached.
	//
	// Settings in the map value that are unset will be defaulted.
	// Use an empty value for the specific setting to prevent that.
	//
	// A nil map allows to default this to the cache's DefaultNamespaces setting.
	// An empty map prevents this and means that all namespaces will be cached.
	//
	// The defaulting follows the following precedence order:
	// 1. ByObject
	// 2. DefaultNamespaces[namespace]
	// 3. Default*
	//
	// This must be unset for cluster-scoped objects.
	Namespaces map[string]Config

	// Label represents a label selector for the object.
	Label labels.Selector

	// Field represents a field selector for the object.
	Field fields.Selector

	// Transform is a transformer function for the object which gets applied
	// when objects of the transformation are about to be committed to the cache.
	//
	// This function is called both for new objects to enter the cache,
	// and for updated objects.
	Transform toolscache.TransformFunc

	// UnsafeDisableDeepCopy indicates not to deep copy objects during get or
	// list objects per GVK at the specified object.
	// Be very careful with this, when enabled you must DeepCopy any object before mutating it,
	// otherwise you will mutate the object in the cache.
	UnsafeDisableDeepCopy *bool
}

ByObject offers more fine-grained control over the cache's ListWatch by object.

type Cache

type Cache interface {
	// Reader acts as a client to objects stored in the cache.
	client.Reader

	// Informers loads informers and adds field indices.
	Informers
}

Cache knows how to load Kubernetes objects, fetch informers to request to receive events for Kubernetes objects (at a low-level), and add indices to fields on the objects stored in the cache.

func New

func New(cfg *rest.Config, opts Options) (Cache, error)

New initializes and returns a new Cache.

type Config

type Config struct {
	// LabelSelector specifies a label selector. A nil value allows to
	// default this.
	//
	// Set to labels.Everything() if you don't want this defaulted.
	LabelSelector labels.Selector

	// FieldSelector specifics a field selector. A nil value allows to
	// default this.
	//
	// Set to fields.Everything() if you don't want this defaulted.
	FieldSelector fields.Selector

	// Transform specifies a transform func. A nil value allows to default
	// this.
	//
	// Set to an empty func to prevent this:
	// func(in interface{}) (interface{}, error) { return in, nil }
	Transform toolscache.TransformFunc

	// UnsafeDisableDeepCopy specifies if List and Get requests against the
	// cache should not DeepCopy. A nil value allows to default this.
	UnsafeDisableDeepCopy *bool
}

Config describes all potential options for a given watch.

type ErrCacheNotStarted

type ErrCacheNotStarted struct{}

ErrCacheNotStarted is returned when trying to read from the cache that wasn't started.

func (*ErrCacheNotStarted) Error

func (*ErrCacheNotStarted) Error() string

type ErrResourceNotCached

type ErrResourceNotCached struct {
	GVK schema.GroupVersionKind
}

ErrResourceNotCached indicates that the resource type the client asked the cache for is not cached, i.e. the corresponding informer does not exist yet.

func (ErrResourceNotCached) Error

func (r ErrResourceNotCached) Error() string

Error returns the error

type Informer

type Informer interface {
	// AddEventHandler adds an event handler to the shared informer using the shared informer's resync
	// period. Events to a single handler are delivered sequentially, but there is no coordination
	// between different handlers.
	// It returns a registration handle for the handler that can be used to remove
	// the handler again and an error if the handler cannot be added.
	AddEventHandler(handler toolscache.ResourceEventHandler) (toolscache.ResourceEventHandlerRegistration, error)

	// AddEventHandlerWithResyncPeriod adds an event handler to the shared informer using the
	// specified resync period. Events to a single handler are delivered sequentially, but there is
	// no coordination between different handlers.
	// It returns a registration handle for the handler that can be used to remove
	// the handler again and an error if the handler cannot be added.
	AddEventHandlerWithResyncPeriod(handler toolscache.ResourceEventHandler, resyncPeriod time.Duration) (toolscache.ResourceEventHandlerRegistration, error)

	// RemoveEventHandler removes a previously added event handler given by
	// its registration handle.
	// This function is guaranteed to be idempotent and thread-safe.
	RemoveEventHandler(handle toolscache.ResourceEventHandlerRegistration) error

	// AddIndexers adds indexers to this store. If this is called after there is already data
	// in the store, the results are undefined.
	AddIndexers(indexers toolscache.Indexers) error

	// HasSynced return true if the informers underlying store has synced.
	HasSynced() bool
}

Informer allows you to interact with the underlying informer.

type InformerGetOption

type InformerGetOption func(*InformerGetOptions)

InformerGetOption defines an option that alters the behavior of how informers are retrieved.

func BlockUntilSynced

func BlockUntilSynced(shouldBlock bool) InformerGetOption

BlockUntilSynced determines whether a get request for an informer should block until the informer's cache has synced.

type InformerGetOptions

type InformerGetOptions internal.GetOptions

InformerGetOptions defines the behavior of how informers are retrieved.

type Informers

type Informers interface {
	// GetInformer fetches or constructs an informer for the given object that corresponds to a single
	// API kind and resource.
	GetInformer(ctx context.Context, obj client.Object, opts ...InformerGetOption) (Informer, error)

	// GetInformerForKind is similar to GetInformer, except that it takes a group-version-kind, instead
	// of the underlying object.
	GetInformerForKind(ctx context.Context, gvk schema.GroupVersionKind, opts ...InformerGetOption) (Informer, error)

	// Start runs all the informers known to this cache until the context is closed.
	// It blocks.
	Start(ctx context.Context) error

	// WaitForCacheSync waits for all the caches to sync. Returns false if it could not sync a cache.
	WaitForCacheSync(ctx context.Context) bool

	// FieldIndexer adds indices to the managed informers.
	client.FieldIndexer
}

Informers knows how to create or fetch informers for different group-version-kinds, and add indices to those informers. It's safe to call GetInformer from multiple threads.

type NewCacheFunc

type NewCacheFunc func(config *rest.Config, opts Options) (Cache, error)

NewCacheFunc - Function for creating a new cache from the options and a rest config.

type Options

type Options struct {
	// HTTPClient is the http client to use for the REST client
	HTTPClient *http.Client

	// Scheme is the scheme to use for mapping objects to GroupVersionKinds
	Scheme *runtime.Scheme

	// Mapper is the RESTMapper to use for mapping GroupVersionKinds to Resources
	Mapper meta.RESTMapper

	// SyncPeriod determines the minimum frequency at which watched resources are
	// reconciled. A lower period will correct entropy more quickly, but reduce
	// responsiveness to change if there are many watched resources. Change this
	// value only if you know what you are doing. Defaults to 10 hours if unset.
	// there will a 10 percent jitter between the SyncPeriod of all controllers
	// so that all controllers will not send list requests simultaneously.
	//
	// This applies to all controllers.
	//
	// A period sync happens for two reasons:
	// 1. To insure against a bug in the controller that causes an object to not
	// be requeued, when it otherwise should be requeued.
	// 2. To insure against an unknown bug in controller-runtime, or its dependencies,
	// that causes an object to not be requeued, when it otherwise should be
	// requeued, or to be removed from the queue, when it otherwise should not
	// be removed.
	//
	// If you want
	// 1. to insure against missed watch events, or
	// 2. to poll services that cannot be watched,
	// then we recommend that, instead of changing the default period, the
	// controller requeue, with a constant duration `t`, whenever the controller
	// is "done" with an object, and would otherwise not requeue it, i.e., we
	// recommend the `Reconcile` function return `reconcile.Result{RequeueAfter: t}`,
	// instead of `reconcile.Result{}`.
	SyncPeriod *time.Duration

	// ReaderFailOnMissingInformer configures the cache to return a ErrResourceNotCached error when a user
	// requests, using Get() and List(), a resource the cache does not already have an informer for.
	//
	// This error is distinct from an errors.NotFound.
	//
	// Defaults to false, which means that the cache will start a new informer
	// for every new requested resource.
	ReaderFailOnMissingInformer bool

	// DefaultNamespaces maps namespace names to cache configs. If set, only
	// the namespaces in here will be watched and it will by used to default
	// ByObject.Namespaces for all objects if that is nil.
	//
	// The options in the Config that are nil will be defaulted from
	// the respective Default* settings.
	DefaultNamespaces map[string]Config

	// DefaultLabelSelector will be used as a label selector for all objects
	// unless there is already one set in ByObject or DefaultNamespaces.
	DefaultLabelSelector labels.Selector

	// DefaultFieldSelector will be used as a field selector for all object types
	// unless there is already one set in ByObject or DefaultNamespaces.
	DefaultFieldSelector fields.Selector

	// DefaultTransform will be used as transform for all object types
	// unless there is already one set in ByObject or DefaultNamespaces.
	DefaultTransform toolscache.TransformFunc

	// DefaultUnsafeDisableDeepCopy is the default for UnsafeDisableDeepCopy
	// for everything that doesn't specify this.
	//
	// Be very careful with this, when enabled you must DeepCopy any object before mutating it,
	// otherwise you will mutate the object in the cache.
	//
	// This will be used for all object types, unless it is set in ByObject or
	// DefaultNamespaces.
	DefaultUnsafeDisableDeepCopy *bool

	// ByObject restricts the cache's ListWatch to the desired fields per GVK at the specified object.
	// object, this will fall through to Default* settings.
	ByObject map[client.Object]ByObject
	// contains filtered or unexported fields
}

Options are the optional arguments for creating a new Cache object.