kubernetes/pkg/scheduler/backend/cache/interface.go

/*
Copyright 2015 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package cache

import (
	v1 "k8s.io/api/core/v1"
	schedulingv1alpha3 "k8s.io/api/scheduling/v1alpha3"
	"k8s.io/apimachinery/pkg/util/sets"
	"k8s.io/klog/v2"
	fwk "k8s.io/kube-scheduler/framework"
	"k8s.io/kubernetes/pkg/scheduler/framework"
)

// Cache collects pods' information and provides node-level aggregated information.
// It's intended for generic scheduler to do efficient lookup.
// Cache's operations are pod centric. It does incremental updates based on pod events.
// Pod events are sent via network. We don't have guaranteed delivery of all events:
// We use Reflector to list and watch from remote.
// Reflector might be slow and do a relist, which would lead to missing events.
//
// State Machine of a pod's events in scheduler's cache:
//
//	+-------------------------------------------+  +----+
//	|                            Add            |  |    |
//	|                                           |  |    | Update
//	+      Assume                Add            v  v    |
//
// Initial +--------> Assumed +----------- ---> Added <--+
//
//	^                    +                        +
//	|                    |                        |
//	|                    |                        | Remove
//	|                    |                        |
//	|                    |                        v
//	+--------------------+                     Deleted
//	      Forget
//
// Note that "Initial" and "Deleted" pods do not actually exist in cache.
// Based on existing use cases, we are making the following assumptions:
//   - No pod would be assumed twice
//   - A pod could be added without going through scheduler. In this case, we will see Add but not Assume event.
//   - If a pod wasn't added, it wouldn't be removed or updated.
type Cache interface {
	// NodeCount returns the number of nodes in the cache.
	// DO NOT use outside of tests.
	NodeCount() int

	// PodCount returns the number of pods in the cache (including those from deleted nodes).
	// DO NOT use outside of tests.
	PodCount() (int, error)

	// GetNode returns the copy of node stored in the cache.
	// DO NOT use outside of tests.
	GetNode(name string) (*framework.NodeInfo, error)

	// AssumePod assumes a pod scheduled and aggregates the pod's information into its node.
	AssumePod(logger klog.Logger, pod *v1.Pod) error

	// ForgetPod forgets an assumed pod from the cache. It should be called when the pod
	// still exists, as an undo operation for AssumePod.
	ForgetPod(logger klog.Logger, pod *v1.Pod) error

	// RemoveAssumedPod removes an assumed pod from the cache. It should be called when the assumed
	// pod was removed from the cluster to correctly clean up internal state.
	RemoveAssumedPod(logger klog.Logger, pod *v1.Pod) error

	// AddPod confirms an assumed pod, or adds a newly assigned pod to the cache.
	AddPod(logger klog.Logger, pod *v1.Pod) error

	// UpdatePod removes oldPod's information and adds newPod's information.
	UpdatePod(logger klog.Logger, oldPod, newPod *v1.Pod) error

	// RemovePod removes a pod. The pod's information would be subtracted from assigned node.
	RemovePod(logger klog.Logger, pod *v1.Pod) error

	// GetPod returns the pod from the cache with the same namespace and the
	// same name of the specified pod.
	GetPod(pod *v1.Pod) (*v1.Pod, error)

	// IsAssumedPod returns true if the pod is assumed.
	IsAssumedPod(pod *v1.Pod) (bool, error)

	// AddNode adds overall information about node.
	AddNode(logger klog.Logger, node *v1.Node)

	// UpdateNode updates overall information about node.
	UpdateNode(logger klog.Logger, oldNode, newNode *v1.Node)

	// RemoveNode removes overall information about node.
	RemoveNode(logger klog.Logger, node *v1.Node) error

	// UpdateSnapshot updates the passed infoSnapshot to the current contents of Cache.
	// The node info contains aggregated information of pods scheduled (including assumed to be)
	// on this node.
	// The snapshot only includes Nodes that are not deleted at the time this function is called.
	// nodeinfo.Node() is guaranteed to be not nil for all the nodes in the snapshot.
	UpdateSnapshot(logger klog.Logger, nodeSnapshot *Snapshot) error

	// Dump produces a dump of the current cache.
	Dump() *Dump

	// BindPod handles the pod binding by adding a bind API call to the dispatcher.
	// This method should be used only if the SchedulerAsyncAPICalls feature gate is enabled.
	BindPod(binding *v1.Binding) (<-chan error, error)

	// PodGroupStates returns a PodGroupStateLister.
	PodGroupStates() fwk.PodGroupStateLister

	// PodGroups returns a PodGroupLister used to access the cached PodGroup objects.
	PodGroups() fwk.PodGroupLister

	// AddPodGroupMember adds not assigned and not assumed pod to its pod group state.
	AddPodGroupMember(pod *v1.Pod)

	// UpdatePodGroupMember updates a pod in its pod group state.
	UpdatePodGroupMember(logger klog.Logger, oldPod, newPod *v1.Pod)

	// RemovePodGroupMember removes a pod from its pod group state.
	RemovePodGroupMember(pod *v1.Pod)

	// AddPodGroup adds a pod group object to the cache.
	AddPodGroup(podGroup *schedulingv1alpha3.PodGroup)

	// UpdatePodGroup updates a pod group object in the cache.
	UpdatePodGroup(logger klog.Logger, oldPodGroup, newPodGroup *schedulingv1alpha3.PodGroup)

	// RemovePodGroup removes a pod group object from the cache.
	RemovePodGroup(podGroup *schedulingv1alpha3.PodGroup)
}

// Dump is a dump of the cache state.
type Dump struct {
	AssumedPods sets.Set[string]
	Nodes       map[string]*framework.NodeInfo
}