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(config *rest.Config, opts Options) (Cache, error)
• type ErrCacheNotStarted
  • func (*ErrCacheNotStarted) Error() string
• type Informer
• type Informers
• type NewCacheFunc
  • func MultiNamespacedCacheBuilder(namespaces []string) NewCacheFunc
• type Options

Types

type ByObject

type ByObject struct {
	// 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 map from objects to transformer functions which
	// get applied when objects of the transformation are about to be committed
	// to 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 {
	// Cache acts as a client to objects stored in the cache.
	client.Reader

	// Cache 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(config *rest.Config, opts Options) (Cache, error)

New initializes and returns a new Cache.

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 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.
	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 formerly 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 more indexers to this store.  If you call this after you already have 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 - informer allows you interact with the underlying informer.

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) (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) (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

	// Informers knows how to add indices to the caches (informers) that it manages.
	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.

func MultiNamespacedCacheBuilder

func MultiNamespacedCacheBuilder(namespaces []string) NewCacheFunc

MultiNamespacedCacheBuilder - Builder function to create a new multi-namespaced cache. This will scope the cache to a list of namespaces. Listing for all namespaces will list for all the namespaces that this knows about. By default this will create a global cache for cluster scoped resource. Note that this is not intended to be used for excluding namespaces, this is better done via a Predicate. Also note that you may face performance issues when using this with a high number of namespaces.

Deprecated: Use cache.Options.Namespaces instead.

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

	// Namespaces restricts the cache's ListWatch to the desired namespaces
	// Default watches all namespaces
	Namespaces []string

	// DefaultLabelSelector will be used as a label selectors for all object types
	// unless they have a more specific selector set in ByObject.
	DefaultLabelSelector labels.Selector

	// DefaultFieldSelector will be used as a field selectors for all object types
	// unless they have a more specific selector set in ByObject.
	DefaultFieldSelector fields.Selector

	// DefaultTransform will be used as transform for all object types
	// unless they have a more specific transform set in ByObject.
	DefaultTransform toolscache.TransformFunc

	// ByObject restricts the cache's ListWatch to the desired fields per GVK at the specified object.
	ByObject map[client.Object]ByObject

	// UnsafeDisableDeepCopy indicates not to deep copy objects during get or
	// list objects for EVERY 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.
	//
	// This is a global setting for all objects, and can be overridden by the ByObject setting.
	UnsafeDisableDeepCopy *bool
}

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