cache

package
v0.9.1 Latest Latest
Warning

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

 Go to latest Published: Sep 6, 2024 License: Apache-2.0 Imports: 25 Imported by: 12

Documentation

Index

Constants

View Source 
const (
	// UserWeightCutoff is the cutoff we clamp user-provided weights to.
	UserWeightCutoff = 1000
	// DefaultWeight is the default assigned weight if omitted in annotations.
	DefaultWeight int32 = 1
)
View Source 
const (
	// CPU marks changes that can be applied by the CPU controller.
	CPU = "cpu"
	// CRI marks changes that can be applied by the CRI controller.
	CRI = "cri"
	// RDT marks changes that can be applied by the RDT controller.
	RDT = "rdt"
	// BlockIO marks changes that can be applied by the BlockIO controller.
	BlockIO = "blockio"
	// Memory marks changes that can be applied by the Memory controller.
	Memory = "memory"
	// PageMigration marks changes that can be applied by the PageMigration controller.
	PageMigration = "page-migration"

	// TagAVX512 tags containers that use AVX512 instructions.
	TagAVX512 = "AVX512"

	// RDTClassKey is the pod annotation key for specifying a container RDT class.
	RDTClassKey = "rdtclass" + "." + kubernetes.ResmgrKeyNamespace
	// BlockIOClassKey is the pod annotation key for specifying a container Block I/O class.
	BlockIOClassKey = "blockioclass" + "." + kubernetes.ResmgrKeyNamespace
	// ToptierLimitKey is the pod annotation key for specifying container top tier memory limits.
	ToptierLimitKey = "toptierlimit" + "." + kubernetes.ResmgrKeyNamespace

	// RDTClassPodQoS denotes that the RDTClass should be taken from PodQosClass
	RDTClassPodQoS = "/PodQos"

	// ToptierLimitUnset is the reserved value for indicating unset top tier limits.
	ToptierLimitUnset int64 = -1

	// TopologyHintsKey can be used to opt out from automatic topology hint generation.
	TopologyHintsKey = "topologyhints" + "." + kubernetes.ResmgrKeyNamespace
)
View Source 
const (
	// PodStateReady marks a pod ready.
	PodStateReady = PodState(int32(criv1.PodSandboxState_SANDBOX_READY))
	// PodStateNotReady marks a pod as not ready.
	PodStateNotReady = PodState(int32(criv1.PodSandboxState_SANDBOX_NOTREADY))
	// PodStateStale marks a pod as removed.
	PodStateStale = PodState(int32(PodStateNotReady) + 1)
)
View Source 
const (
	// ContainerStateCreated marks a container created, not running.
	ContainerStateCreated = ContainerState(int32(criv1.ContainerState_CONTAINER_CREATED))
	// ContainerStateRunning marks a container created, running.
	ContainerStateRunning = ContainerState(int32(criv1.ContainerState_CONTAINER_RUNNING))
	// ContainerStateExited marks a container exited.
	ContainerStateExited = ContainerState(int32(criv1.ContainerState_CONTAINER_EXITED))
	// ContainerStateUnknown marks a container to be in an unknown state.
	ContainerStateUnknown = ContainerState(int32(criv1.ContainerState_CONTAINER_UNKNOWN))
	// ContainerStateCreating marks a container as being created.
	ContainerStateCreating = ContainerState(int32(ContainerStateUnknown) + 1)
	// ContainerStateStale marks a container removed.
	ContainerStateStale = ContainerState(int32(ContainerStateUnknown) + 2)
)
View Source 
const (
	// CacheVersion is the running version of the cache.
	CacheVersion = "1"
)
View Source 
const (
	// KeyResourceAnnotation is the annotation key our webhook uses.
	KeyResourceAnnotation = "intel.com/resources"
)

Variables

View Source 
var (
	SharesToMilliCPU = kubernetes.SharesToMilliCPU
	QuotaToMilliCPU  = kubernetes.QuotaToMilliCPU
	MilliCPUToShares = kubernetes.MilliCPUToShares
	MilliCPUToQuota  = kubernetes.MilliCPUToQuota
)
View Source 
var CompareByQOSMemoryCPU = []CompareContainersFn{CompareQOS, CompareMemory, CompareCPU}

CompareByQOSMemoryCPU is a slice for comparing container by QOS, memory, and CPU.

Functions

func CompareCPU added in v0.5.0 

func CompareCPU(ci, cj Container) int

CompareCPU compares containers by CPU requests and limits.

func CompareMemory added in v0.5.0 

func CompareMemory(ci, cj Container) int

CompareMemory compares containers by memory requests and limits.

func CompareQOS added in v0.5.0 

func CompareQOS(ci, cj Container) int

CompareQOS compares containers by QOS class.

func IsPodQOSClassName added in v0.4.0 

func IsPodQOSClassName(class string) bool

IsPodQOSClassName returns true if the given class is one of the Pod QOS classes.

func SortContainers added in v0.5.0 

func SortContainers(containers []Container, compareFns ...CompareContainersFn)

SortContainers sorts a slice of containers using the given comparison functions. If the containers are otherwise equal they are sorted by pod and container name. If the comparison functions are omitted, containers are compared by QoS class, memory and cpuset size.

Types

type Affinity 

type Affinity struct {
	Scope  *resmgr.Expression `json:"scope,omitempty"`  // scope for evaluating this affinity
	Match  *resmgr.Expression `json:"match"`            // affinity expression
	Weight int32              `json:"weight,omitempty"` // (optional) weight for this affinity
}

Affinity specifies a single container affinity.

func GlobalAffinity 

func GlobalAffinity(key string, weight int32) *Affinity

GlobalAffinity creates an affinity with all containers in scope.

func GlobalAntiAffinity 

func GlobalAntiAffinity(key string, weight int32) *Affinity

GlobalAntiAffinity creates an anti-affinity with all containers in scope.

func (*Affinity) String 

func (a *Affinity) String() string

String returns the affinity as a string.

func (*Affinity) Validate 

func (a *Affinity) Validate() error

Validate checks the affinity for (obvious) invalidity.

type Cachable 

type Cachable interface {
	// Set value (via a pointer receiver) to the object.
	Set(value interface{})
	// Get the object that should be cached.
	Get() interface{}
}

Cachable is an interface opaque cachable data must implement.

type Cache 

type Cache interface {
	// InsertPod inserts a pod into the cache, using a runtime request or reply.
	InsertPod(id string, msg interface{}, status *PodStatus) (Pod, error)
	// DeletePod deletes a pod from the cache.
	DeletePod(id string) Pod
	// LookupPod looks up a pod in the cache.
	LookupPod(id string) (Pod, bool)
	// InsertContainer inserts a container into the cache, using a runtime request or reply.
	InsertContainer(msg interface{}) (Container, error)
	// UpdateContainerID updates a containers runtime id.
	UpdateContainerID(cacheID string, msg interface{}) (Container, error)
	// DeleteContainer deletes a container from the cache.
	DeleteContainer(id string) Container
	// LookupContainer looks up a container in the cache.
	LookupContainer(id string) (Container, bool)
	// LookupContainerByCgroup looks up a container for the given cgroup path.
	LookupContainerByCgroup(path string) (Container, bool)

	// GetPendingContainers returs all containers with pending changes.
	GetPendingContainers() []Container

	// GetPods returns all the pods known to the cache.
	GetPods() []Pod
	// GetContainers returns all the containers known to the cache.
	GetContainers() []Container

	// GetContainerCacheIds returns the cache ids of all containers.
	GetContainerCacheIds() []string
	// GetContaineIds return the ids of all containers.
	GetContainerIds() []string

	// FilterScope returns the containers selected by the scope expression.
	FilterScope(*resmgr.Expression) []Container
	// EvaluateAffinity evaluates the given affinity against all known in-scope containers
	EvaluateAffinity(*Affinity) map[string]int32
	// AddImplicitAffinities adds a set of implicit affinities (added to all containers).
	AddImplicitAffinities(map[string]ImplicitAffinity) error

	// GetActivePolicy returns the name of the active policy stored in the cache.
	GetActivePolicy() string
	// SetActivePolicy updates the name of the active policy stored in the cache.
	SetActivePolicy(string) error

	// ResetActivePolicy clears the active policy any any policy-specific data from the cache.
	ResetActivePolicy() error

	// SetPolicyEntry sets the policy entry for a key.
	SetPolicyEntry(string, interface{})
	// GetPolicyEntry gets the policy entry for a key.
	GetPolicyEntry(string, interface{}) bool

	// SetConfig caches the given configuration.
	SetConfig(*config.RawConfig) error
	// GetConfig returns the current/cached configuration.
	GetConfig() *config.RawConfig
	// ResetConfig clears any stored configuration from the cache.
	ResetConfig() error

	// SetAdjustment updates external adjustments and containers based this.
	SetAdjustment(*config.Adjustment) (bool, map[string]error)

	// Save requests a cache save.
	Save() error

	// RefreshPods purges/inserts stale/new pods/containers using a pod sandbox list response.
	RefreshPods(*criv1.ListPodSandboxResponse, map[string]*PodStatus) ([]Pod, []Pod, []Container)
	// RefreshContainers purges/inserts stale/new containers using a container list response.
	RefreshContainers(*criv1.ListContainersResponse) ([]Container, []Container)

	// Get the container (data) directory for a container.
	ContainerDirectory(string) string
	// OpenFile opens the names container data file, creating it if necessary.
	OpenFile(string, string, os.FileMode) (*os.File, error)
	// WriteFile writes a container data file, creating it if necessary.
	WriteFile(string, string, os.FileMode, []byte) error
}

Cache is the primary interface exposed for tracking pods and containers.

Cache tracks pods and containers in the runtime, mostly by processing CRI requests and responses which the cache is fed as these are being procesed. Cache also saves its state upon changes to secondary storage and restores itself upon startup.

func NewCache 

func NewCache(options Options) (Cache, error)

NewCache instantiates a new cache. Load it from the given path if it exists.

type CompareContainersFn added in v0.5.0 

type CompareContainersFn func(Container, Container) int

CompareContainersFn compares two containers by some arbitrary property. It returns a negative integer, 0, or a positive integer, depending on whether the first container is considered smaller, equal, or larger than the second.

type Container 

type Container interface {
	resmgr.Evaluable
	fmt.Stringer
	// PrettyName returns the user-friendly <podname>:<containername> for the container.
	PrettyName() string
	// GetPod returns the pod of the container and a boolean indicating if there was one.
	GetPod() (Pod, bool)
	// GetID returns the ID of the container.
	GetID() string
	// GetPodID returns the pod ID of the container.
	GetPodID() string
	// GetCacheID returns the cacheID of the container.
	GetCacheID() string
	// GetName returns the name of the container.
	GetName() string
	// GetNamespace returns the namespace of the container.
	GetNamespace() string
	// UpdateState updates the state of the container.
	UpdateState(ContainerState)
	// GetState returns the ContainerState of the container.
	GetState() ContainerState
	// GetQOSClass returns the QoS class the pod would have if this was its only container.
	GetQOSClass() v1.PodQOSClass
	// GetImage returns the image of the container.
	GetImage() string
	// GetCommand returns the container command.
	GetCommand() []string
	// GetArgs returns the container command arguments.
	GetArgs() []string
	// GetLabelKeys returns the keys of all labels of the container.
	GetLabelKeys() []string
	// GetLabel returns the value of a container label.
	GetLabel(string) (string, bool)
	// GetLabels returns a copy of all container labels.
	GetLabels() map[string]string
	// GetResmgrLabelKeys returns container label keys (without the namespace
	// part) in cri-resource-manager namespace.
	GetResmgrLabelKeys() []string
	// GetResmgrLabel returns the value of a container label from the
	// cri-resource-manager namespace.
	GetResmgrLabel(string) (string, bool)
	// GetAnnotationKeys returns the keys of all annotations of the container.
	GetAnnotationKeys() []string
	// GetAnnotation returns the value of a container annotation.
	GetAnnotation(key string, objPtr interface{}) (string, bool)
	// GetResmgrAnnotationKeys returns container annotation keys (without the
	// namespace part) in cri-resource-manager namespace.
	GetResmgrAnnotationKeys() []string
	// GetAnnotation returns the value of a container annotation from the
	// cri-resource-manager namespace.
	GetResmgrAnnotation(key string, objPtr interface{}) (string, bool)
	// GetEffectiveAnnotation returns the effective annotation for the container from the pod.
	GetEffectiveAnnotation(key string) (string, bool)
	// GetAnnotations returns a copy of all container annotations.
	GetAnnotations() map[string]string
	// GetEnvKeys returns the keys of all container environment variables.
	GetEnvKeys() []string
	// GetEnv returns the value of a container environment variable.
	GetEnv(string) (string, bool)
	// GetMounts returns all the mounts of the container.
	GetMounts() []Mount
	// GetMountByHost returns the container path corresponding to the host path.
	// XXX We should remove this as is might not be unique.
	GetMountByHost(string) *Mount
	// GetmountByContainer returns the host path mounted to a container path.
	GetMountByContainer(string) *Mount
	// GetDevices returns the devices of the container.
	GetDevices() []Device
	// GetDeviceByHost returns the device for a host path.
	GetDeviceByHost(string) *Device
	// GetDeviceByContainer returns the device for a container path.
	GetDeviceByContainer(string) *Device
	// GetResourceRequirements returns the webhook-annotated requirements for ths container.
	GetResourceRequirements() v1.ResourceRequirements
	// GetLinuxResources returns the CRI linux resource request of the container.
	GetLinuxResources() *criv1.LinuxContainerResources

	// SetCommand sets the container command.
	SetCommand([]string)
	// SetArgs sets the container command arguments.
	SetArgs([]string)
	// SetLabel sets the value for a container label.
	SetLabel(string, string)
	// DeleteLabel removes a container label.
	DeleteLabel(string)
	// SetAnnotation sets the value for a container annotation.
	SetAnnotation(string, string)
	// DeleteAnnotation removes a container annotation.
	DeleteAnnotation(string)
	// SetEnv sets a container environment variable.
	SetEnv(string, string)
	// UnsetEnv unsets a container environment variable.
	UnsetEnv(string)
	// InsertMount inserts a mount into the container.
	InsertMount(*Mount)
	// DeleteMount removes a mount from the container.
	DeleteMount(string)
	// InsertDevice inserts a device into the container.
	InsertDevice(*Device)
	// DeleteDevice removes a device from the container.
	DeleteDevice(string)

	// Get any attached topology hints.
	GetTopologyHints() topology.Hints

	// GetCPUPeriod gets the CFS CPU period of the container.
	GetCPUPeriod() int64
	// GetCpuQuota gets the CFS CPU quota of the container.
	GetCPUQuota() int64
	// GetCPUShares gets the CFS CPU shares of the container.
	GetCPUShares() int64
	// GetmemoryLimit gets the memory limit in bytes for the container.
	GetMemoryLimit() int64
	// GetOomScoreAdj gets the OOM score adjustment for the container.
	GetOomScoreAdj() int64
	// GetCpusetCPUs gets the cgroup cpuset.cpus of the container.
	GetCpusetCpus() string
	// GetCpusetMems gets the cgroup cpuset.mems of the container.
	GetCpusetMems() string

	// SetLinuxResources sets the Linux-specific resource request of the container.
	SetLinuxResources(*criv1.LinuxContainerResources)
	// SetCPUPeriod sets the CFS CPU period of the container.
	SetCPUPeriod(int64)
	// SetCPUQuota sets the CFS CPU quota of the container.
	SetCPUQuota(int64)
	// SetCPUShares sets the CFS CPU shares of the container.
	SetCPUShares(int64)
	// SetmemoryLimit sets the memory limit in bytes for the container.
	SetMemoryLimit(int64)
	// SetOomScoreAdj sets the OOM score adjustment for the container.
	SetOomScoreAdj(int64)
	// SetCpusetCpu sets the cgroup cpuset.cpus of the container.
	SetCpusetCpus(string)
	// SetCpusetMems sets the cgroup cpuset.mems of the container.
	SetCpusetMems(string)

	// GetAffinity returns the annotated affinity expressions for this container.
	GetAffinity() ([]*Affinity, error)

	// GetCgroupDir returns the relative path of the cgroup directory for the container.
	GetCgroupDir() string

	// SetRDTClass assigns this container to the given RDT class.
	SetRDTClass(string)
	// GetRDTClass returns the RDT class for this container.
	GetRDTClass() string

	// SetBlockIOClass assigns this container to the given BlockIO class.
	SetBlockIOClass(string)
	// GetBlockIOClass returns the BlockIO class for this container.
	GetBlockIOClass() string

	// SetToptierLimit sets the tier memory limit for the container.
	SetToptierLimit(int64)
	// GetToptierLimit returns the top tier memory limit for the container.
	GetToptierLimit() int64

	// SetPageMigration sets the page migration policy/options for the container.
	SetPageMigration(*PageMigrate)
	// GetPageMigration returns the current page migration policy/options for the container.
	GetPageMigration() *PageMigrate

	// GetProcesses returns the pids of processes in the container.
	GetProcesses() ([]string, error)
	// GetTasks returns the pids of threads in the container.
	GetTasks() ([]string, error)

	// SetCRIRequest sets the current pending CRI request of the container.
	SetCRIRequest(req interface{}) error
	// GetCRIRequest returns the current pending CRI request of the container.
	GetCRIRequest() (interface{}, bool)
	// ClearCRIRequest clears and returns the current pending CRI request of the container.
	ClearCRIRequest() (interface{}, bool)

	// GetCRIEnvs returns container environment variables.
	GetCRIEnvs() []*criv1.KeyValue
	// GetCRIMounts returns container mounts.
	GetCRIMounts() []*criv1.Mount
	// GetCRIDevices returns container devices.
	GetCRIDevices() []*criv1.Device

	// GetPending gets the names of the controllers with pending changes.
	GetPending() []string
	// HasPending checks if the container has pending chanhes for the given controller.
	HasPending(string) bool
	// ClearPending clears the pending change marker for the given controller.
	ClearPending(string)

	// GetTag gets the value of the given tag.
	GetTag(string) (string, bool)
	// SetTag sets the value of the given tag and returns its previous value..
	SetTag(string, string) (string, bool)
	// DeleteTag deletes the given tag, returning its deleted value.
	DeleteTag(string) (string, bool)
}

Container is the exposed interface from a cached container.

type ContainerState 

type ContainerState int32

ContainerState is the container state in the runtime.

type Device 

type Device struct {
	// Container is the device path inside the container.
	Container string
	// Host is the device path on the host side.
	Host string
	// Permissions specify the device permissions for the container.
	Permissions string
}

Device is a device exposed to a container.

type Expression 

type Expression struct {
	resmgr.Expression
}

Expression is used to describe affinity container scope and matching criteria.

type ImplicitAffinity 

type ImplicitAffinity func(Container, bool) *Affinity

ImplicitAffinity can implicitly inject affinities to containers.

type Mount 

type Mount struct {
	// Container is the path inside the container.
	Container string
	// Host is the path on the host.
	Host string
	// Readonly specifies if the mount is read-only or read-write.
	Readonly bool
	// Relabels denotes SELinux relabeling.
	Relabel bool
	// Propagation identifies the mount propagation type.
	Propagation MountType
}

Mount is a filesystem entry mounted inside a container.

type MountType 

type MountType int32

MountType is a propagation type. 

const (
	// MountPrivate is a private container mount.
	MountPrivate MountType = MountType(criv1.MountPropagation_PROPAGATION_PRIVATE)
	// MountHostToContainer is a host-to-container mount.
	MountHostToContainer MountType = MountType(criv1.MountPropagation_PROPAGATION_HOST_TO_CONTAINER)
	// MountBidirectional is a bidirectional mount.
	MountBidirectional MountType = MountType(criv1.MountPropagation_PROPAGATION_BIDIRECTIONAL)
)

type Options 

type Options struct {
	// CacheDir is the directory the cache should save its state in.
	CacheDir string
}

Options contains the configurable cache options.

type PageMigrate added in v0.4.1 

type PageMigrate struct {
	SourceNodes idset.IDSet // idle memory pages on these NUMA nodes
	TargetNodes idset.IDSet // should be migrated to these NUMA nodes
}

PageMigrate contains the policy/preferences for container page migration.

func (*PageMigrate) Clone added in v0.4.1 

func (pm *PageMigrate) Clone() *PageMigrate

Clone creates a copy of the page migration policy/preferences.

type Pod 

type Pod interface {
	resmgr.Evaluable
	fmt.Stringer
	// GetInitContainers returns the init containers of the pod.
	GetInitContainers() []Container
	// GetContainers returns the (non-init) containers of the pod.
	GetContainers() []Container
	// GetContainer returns the named container of the pod.
	GetContainer(string) (Container, bool)
	// GetId returns the pod id of the pod.
	GetID() string
	// GetUID returns the (kubernetes) unique id of the pod.
	GetUID() string
	// GetName returns the name of the pod.
	GetName() string
	// GetNamespace returns the namespace of the pod.
	GetNamespace() string
	// GetState returns the PodState of the pod.
	GetState() PodState
	// GetQOSClass returns the PodQOSClass of the pod.
	GetQOSClass() v1.PodQOSClass
	// GetLabelKeys returns the keys of all pod labels as a string slice.
	GetLabelKeys() []string
	// GetLabel returns the value of the given label and whether it was found.
	GetLabel(string) (string, bool)
	// GetResmgrLabelKeys returns pod label keys (without the namespace
	// part) in cri-resource-manager namespace.
	GetResmgrLabelKeys() []string
	// GetResmgrLabel returns the value of a pod label from the
	// cri-resource-manager namespace.
	GetResmgrLabel(string) (string, bool)
	// GetAnnotationKeys returns the keys of all pod annotations as a string slice.
	GetAnnotationKeys() []string
	// GetAnnotation returns the value of the given annotation and whether it was found.
	GetAnnotation(key string) (string, bool)
	// GetAnnotationObject decodes the value of the given annotation with the given function.
	GetAnnotationObject(key string, objPtr interface{},
		decode func([]byte, interface{}) error) (bool, error)
	// GetResmgrAnnotationKeys returns pod annotation keys (without the
	// namespace part) in cri-resource-manager namespace as a string slice.
	GetResmgrAnnotationKeys() []string
	// GetAnnotation returns the value of a pod annotation from the
	// cri-resource-manager namespace and whether it was found.
	GetResmgrAnnotation(key string) (string, bool)
	// GetResmgrAnnotationObject decodes the value of the given annotation in the
	// cri-resource-manager namespace.
	GetResmgrAnnotationObject(key string, objPtr interface{},
		decode func([]byte, interface{}) error) (bool, error)
	// GetEffectiveAnnotation returns the effective annotation for a container.
	// For any given key $K and container $C it will look for annotations in
	// this order and return the first one found:
	//     $K/container.$C
	//     $K/pod
	//     $K
	// and return the value of the first key found.
	GetEffectiveAnnotation(key, container string) (string, bool)
	// GetCgroupParentDir returns the pods cgroup parent directory.
	GetCgroupParentDir() string
	// GetPodResourceRequirements returns container resource requirements if the
	// necessary associated annotation put in place by the CRI resource manager
	// webhook was found.
	GetPodResourceRequirements() PodResourceRequirements
	// GetContainerAffinity returns the affinity expressions for the named container.
	GetContainerAffinity(string) ([]*Affinity, error)
	// ScopeExpression returns an affinity expression for defining this pod as the scope.
	ScopeExpression() *resmgr.Expression

	// GetProcesses returns the pids of all processes in the pod either excluding
	// container processes, if called with false, or including those if called with true.
	GetProcesses(bool) ([]string, error)
	// GetTasks returns the pids of all threads in the pod either excluding cotnainer
	// processes, if called with false, or including those if called with true.
	GetTasks(bool) ([]string, error)
}

Pod is the exposed interface from a cached pod.

type PodResourceRequirements 

type PodResourceRequirements struct {
	// InitContainers is the resource requirements by init containers.
	InitContainers map[string]v1.ResourceRequirements `json:"initContainers"`
	// Containers is the resource requirements by normal container.
	Containers map[string]v1.ResourceRequirements `json:"containers"`
}

PodResourceRequirements are per container resource requirements, annotated by our webhook.

type PodState 

type PodState int32

PodState is the pod state in the runtime.

type PodStatus added in v0.6.0 

type PodStatus struct {
	CgroupParent string // extracted CgroupParent
}

PodStatus wraps a PodSandboxStatus response for data extraction.

func ParsePodStatus added in v0.6.0 

func ParsePodStatus(response *criv1.PodSandboxStatusResponse) (*PodStatus, error)

ParsePodStatus parses a PodSandboxStatusResponse into a PodStatus.

Source Files

View all Source files

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.