cache

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 27, 2020 License: Apache-2.0 Imports: 28 Imported by: 0

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

Examples

Constants

View Source 
const (
	ClusterRetryTimeout = 10 * time.Second
)

Variables

This section is empty.

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.GetNamespaceTopLevelResources("default") {
	clusterCache.IterateHierarchy(root.ResourceKey(), func(resource *Resource, _ map[kube.ResourceKey]*Resource) {
		fmt.Printf("resource: %s, info: %v\n", resource.Ref.String(), resource.Info)
	})
}

Output:
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)

Output:

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
	// Invalidate cache and executes callback that optionally might update cache settings
	Invalidate(opts ...UpdateSettingsFunc)
	// GetNamespaceTopLevelResources returns top level resources in the specified namespace
	GetNamespaceTopLevelResources(namespace string) 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
}

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 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 added in v0.1.5 

func SetListPageBufferSize(listPageBufferSize int32) UpdateSettingsFunc

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

func SetListPageSize added in v0.1.5 

func SetListPageSize(listPageSize int64) UpdateSettingsFunc

SetListPageSize sets the page size for list pager.

func SetListSemaphore added in v0.1.5 

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 added in v0.2.1 

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 added in v0.1.5 

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 added in v0.2.1 

func SetTracer(tracer tracing.Tracer) UpdateSettingsFunc

SetTracer sets the tracer to use.

type WeightedSemaphore added in v0.1.5 

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.