cache

Documentation

Overview

Package cache implements lightweight Kubernetes cluster caching that stores only resource references and ownership references. In addition to references cache might be configured to store custom metadata and whole body of selected resources.

The library uses Kubernetes watch API to maintain cache up to date. This approach reduces number of Kubernetes API requests and provides instant access to the required Kubernetes resources.

Index

• Constants
• func NewClusterCache(config *rest.Config, opts ...UpdateSettingsFunc) *clusterCache
• func ResourceOfGroupKind(group string, kind string) func(r *Resource) bool
• func TopLevelResource(r *Resource) bool
• type ClusterCache
• type ClusterInfo
• type OnEventHandler
• type OnPopulateResourceInfoHandler
• type OnResourceUpdatedHandler
• type Resource
  • func (r *Resource) ResourceKey() kube.ResourceKey
• type Settings
• type Unsubscribe
• type UpdateSettingsFunc
  • func SetClusterResources(val bool) UpdateSettingsFunc
  • func SetConfig(config *rest.Config) UpdateSettingsFunc
  • func SetKubectl(kubectl kube.Kubectl) UpdateSettingsFunc
  • func SetListPageBufferSize(listPageBufferSize int32) UpdateSettingsFunc
  • func SetListPageSize(listPageSize int64) UpdateSettingsFunc
  • func SetListSemaphore(listSemaphore WeightedSemaphore) UpdateSettingsFunc
  • func SetLogr(log logr.Logger) UpdateSettingsFunc
  • func SetNamespaces(namespaces []string) UpdateSettingsFunc
  • func SetPopulateResourceInfoHandler(handler OnPopulateResourceInfoHandler) UpdateSettingsFunc
  • func SetResyncTimeout(timeout time.Duration) UpdateSettingsFunc
  • func SetSettings(settings Settings) UpdateSettingsFunc
  • func SetTracer(tracer tracing.Tracer) UpdateSettingsFunc
• type WeightedSemaphore

Examples

• NewClusterCache (InspectNamespaceResources)
• NewClusterCache (ResourceUpdatedEvents)

Constants

const (
	ClusterRetryTimeout = 10 * time.Second
)

Functions

func NewClusterCache

func NewClusterCache(config *rest.Config, opts ...UpdateSettingsFunc) *clusterCache

NewClusterCache creates new instance of cluster cache

Example (InspectNamespaceResources)

// kubernetes cluster config here
config := &rest.Config{}

clusterCache := NewClusterCache(config,
	// cache default namespace only
	SetNamespaces([]string{"default", "kube-system"}),
	// configure custom logic to cache resources manifest and additional metadata
	SetPopulateResourceInfoHandler(func(un *unstructured.Unstructured, isRoot bool) (info interface{}, cacheManifest bool) {
		// if resource belongs to 'extensions' group then mark if with 'deprecated' label
		if un.GroupVersionKind().Group == "extensions" {
			info = []string{"deprecated"}
		}
		_, ok := un.GetLabels()["acme.io/my-label"]
		// cache whole manifest if resource has label
		cacheManifest = ok
		return
	}),
)
// Ensure cluster is synced before using it
if err := clusterCache.EnsureSynced(); err != nil {
	panic(err)
}
// Iterate default namespace resources tree
for _, root := range clusterCache.FindResources("default", TopLevelResource) {
	clusterCache.IterateHierarchy(root.ResourceKey(), func(resource *Resource, _ map[kube.ResourceKey]*Resource) {
		fmt.Printf("resource: %s, info: %v\n", resource.Ref.String(), resource.Info)
	})
}

Example (ResourceUpdatedEvents)

// kubernetes cluster config here
config := &rest.Config{}

clusterCache := NewClusterCache(config)
// Ensure cluster is synced before using it
if err := clusterCache.EnsureSynced(); err != nil {
	panic(err)
}
unsubscribe := clusterCache.OnResourceUpdated(func(newRes *Resource, oldRes *Resource, _ map[kube.ResourceKey]*Resource) {
	if newRes == nil {
		fmt.Printf("%s deleted\n", oldRes.Ref.String())
	} else if oldRes == nil {
		fmt.Printf("%s created\n", newRes.Ref.String())
	} else {
		fmt.Printf("%s updated\n", newRes.Ref.String())
	}
})
defer unsubscribe()
// observe resource modifications for 1 minute
time.Sleep(time.Minute)

func ResourceOfGroupKind

func ResourceOfGroupKind(group string, kind string) func(r *Resource) bool

ResourceOfGroupKind returns predicate that matches resource by specified group and kind

func TopLevelResource

func TopLevelResource(r *Resource) bool

TopLevelResource returns true if resource has no parents

Types

type ClusterCache

type ClusterCache interface {
	// EnsureSynced checks cache state and synchronizes it if necessary
	EnsureSynced() error
	// GetServerVersion returns observed cluster version
	GetServerVersion() string
	// GetAPIGroups returns information about observed API groups
	GetAPIGroups() []metav1.APIGroup
	// GetOpenAPISchema returns open API schema of supported API resources
	GetOpenAPISchema() openapi.Resources
	// Invalidate cache and executes callback that optionally might update cache settings
	Invalidate(opts ...UpdateSettingsFunc)
	// FindResources returns resources that matches given list of predicates from specified namespace or everywhere if specified namespace is empty
	FindResources(namespace string, predicates ...func(r *Resource) bool) map[kube.ResourceKey]*Resource
	// IterateHierarchy iterates resource tree starting from the specified top level resource and executes callback for each resource in the tree
	IterateHierarchy(key kube.ResourceKey, action func(resource *Resource, namespaceResources map[kube.ResourceKey]*Resource))
	// IsNamespaced answers if specified group/kind is a namespaced resource API or not
	IsNamespaced(gk schema.GroupKind) (bool, error)
	// GetManagedLiveObjs helps finding matching live K8S resources for a given resources list.
	// The function returns all resources from cache for those `isManaged` function returns true and resources
	// specified in targetObjs list.
	GetManagedLiveObjs(targetObjs []*unstructured.Unstructured, isManaged func(r *Resource) bool) (map[kube.ResourceKey]*unstructured.Unstructured, error)
	// GetClusterInfo returns cluster cache statistics
	GetClusterInfo() ClusterInfo
	// OnResourceUpdated register event handler that is executed every time when resource get's updated in the cache
	OnResourceUpdated(handler OnResourceUpdatedHandler) Unsubscribe
	// OnEvent register event handler that is executed every time when new K8S event received
	OnEvent(handler OnEventHandler) Unsubscribe
}

type ClusterInfo

type ClusterInfo struct {
	// Server holds cluster API server URL
	Server string
	// K8SVersion holds Kubernetes version
	K8SVersion string
	// ResourcesCount holds number of observed Kubernetes resources
	ResourcesCount int
	// APIsCount holds number of observed Kubernetes API count
	APIsCount int
	// LastCacheSyncTime holds time of most recent cache synchronization
	LastCacheSyncTime *time.Time
	// SyncError holds most recent cache synchronization error
	SyncError error
	// APIGroups holds list of API groups supported by the cluster
	APIGroups []metav1.APIGroup
}

ClusterInfo holds cluster cache stats

type OnEventHandler

type OnEventHandler func(event watch.EventType, un *unstructured.Unstructured)

OnEventHandler is a function that handles Kubernetes event

type OnPopulateResourceInfoHandler

type OnPopulateResourceInfoHandler func(un *unstructured.Unstructured, isRoot bool) (info interface{}, cacheManifest bool)

OnPopulateResourceInfoHandler returns additional resource metadata that should be stored in cache

type OnResourceUpdatedHandler

type OnResourceUpdatedHandler func(newRes *Resource, oldRes *Resource, namespaceResources map[kube.ResourceKey]*Resource)

OnResourceUpdatedHandler handlers resource update event

type Resource

type Resource struct {
	// ResourceVersion holds most recent observed resource version
	ResourceVersion string
	// Resource reference
	Ref v1.ObjectReference
	// References to resource owners
	OwnerRefs []metav1.OwnerReference
	// Optional creation timestamp of the resource
	CreationTimestamp *metav1.Time
	// Optional additional information about the resource
	Info interface{}
	// Optional whole resource manifest
	Resource *unstructured.Unstructured
	// contains filtered or unexported fields
}

Resource holds the information about Kubernetes resource, ownership references and optional information

func (*Resource) ResourceKey

func (r *Resource) ResourceKey() kube.ResourceKey

type Settings

type Settings struct {
	// ResourceHealthOverride contains health assessment overrides
	ResourceHealthOverride health.HealthOverride
	// ResourcesFilter holds filter that excludes resources
	ResourcesFilter kube.ResourceFilter
}

Settings caching customizations

type Unsubscribe

type Unsubscribe func()

type UpdateSettingsFunc

type UpdateSettingsFunc func(cache *clusterCache)

func SetClusterResources

func SetClusterResources(val bool) UpdateSettingsFunc

SetClusterResources specifies if cluster level resource included or not. Flag is used only if cluster is changed to namespaced mode using SetNamespaces setting

func SetConfig

func SetConfig(config *rest.Config) UpdateSettingsFunc

SetConfig updates cluster rest config

func SetKubectl

func SetKubectl(kubectl kube.Kubectl) UpdateSettingsFunc

SetKubectl allows to override kubectl wrapper implementation

func SetListPageBufferSize

func SetListPageBufferSize(listPageBufferSize int32) UpdateSettingsFunc

SetListPageBufferSize sets the number of pages to prefetch for list pager.

func SetListPageSize

func SetListPageSize(listPageSize int64) UpdateSettingsFunc

SetListPageSize sets the page size for list pager.

func SetListSemaphore

func SetListSemaphore(listSemaphore WeightedSemaphore) UpdateSettingsFunc

SetListSemaphore sets the semaphore for list operations. Taking an object rather than a number allows to share a semaphore among multiple caches if necessary.

func SetLogr

func SetLogr(log logr.Logger) UpdateSettingsFunc

SetLogr sets the logger to use.

func SetNamespaces

func SetNamespaces(namespaces []string) UpdateSettingsFunc

SetNamespaces updates list of monitored namespaces

func SetPopulateResourceInfoHandler

func SetPopulateResourceInfoHandler(handler OnPopulateResourceInfoHandler) UpdateSettingsFunc

SetPopulateResourceInfoHandler updates handler that populates resource info

func SetResyncTimeout

func SetResyncTimeout(timeout time.Duration) UpdateSettingsFunc

SetResyncTimeout updates cluster re-sync timeout

func SetSettings

func SetSettings(settings Settings) UpdateSettingsFunc

SetSettings updates caching settings

func SetTracer

func SetTracer(tracer tracing.Tracer) UpdateSettingsFunc

SetTracer sets the tracer to use.

type WeightedSemaphore

type WeightedSemaphore interface {
	Acquire(ctx context.Context, n int64) error
	TryAcquire(n int64) bool
	Release(n int64)
}