framework

Documentation

Overview

Package framework features the scheduler framework, which the scheduler runs to schedule a placement to most appropriate clusters.

Index

• type ClusterScore
  • func (s1 *ClusterScore) Add(s2 *ClusterScore)
  • func (s1 *ClusterScore) Equal(s2 *ClusterScore) bool
  • func (s1 *ClusterScore) Less(s2 *ClusterScore) bool
• type CycleState
  • func NewCycleState(clusters []clusterv1beta1.MemberCluster, ...) *CycleState
  • func (c *CycleState) Delete(key StateKey)
  • func (c *CycleState) HasObsoleteBindingFor(clusterName string) bool
  • func (c *CycleState) HasScheduledOrBoundBindingFor(clusterName string) bool
  • func (c *CycleState) ListClusters() []clusterv1beta1.MemberCluster
  • func (c *CycleState) Read(key StateKey) (StateValue, error)
  • func (c *CycleState) Write(key StateKey, val StateValue)
• type CycleStatePluginReadWriter
• type FilterPlugin
• type Framework
  • func NewFramework(profile *Profile, manager ctrl.Manager, opts ...Option) Framework
• type Handle
• type Option
  • func WithClusterEligibilityChecker(checker *clustereligibilitychecker.ClusterEligibilityChecker) Option
  • func WithMaxClusterDecisionCount(maxUnselectedClusterDecisionCount int) Option
  • func WithNumOfWorkers(numOfWorkers int) Option
• type Plugin
• type PostBatchPlugin
• type PreFilterPlugin
• type PreScorePlugin
• type Profile
  • func NewProfile(name string) *Profile
  • func (profile *Profile) Name() string
  • func (profile *Profile) WithFilterPlugin(plugin FilterPlugin) *Profile
  • func (profile *Profile) WithPostBatchPlugin(plugin PostBatchPlugin) *Profile
  • func (profile *Profile) WithPreFilterPlugin(plugin PreFilterPlugin) *Profile
  • func (profile *Profile) WithPreScorePlugin(plugin PreScorePlugin) *Profile
  • func (profile *Profile) WithScorePlugin(plugin ScorePlugin) *Profile
• type ScorePlugin
• type ScoredCluster
• type ScoredClusters
  • func (sc ScoredClusters) Len() int
  • func (sc ScoredClusters) Less(i, j int) bool
  • func (sc ScoredClusters) Swap(i, j int)
• type StateKey
• type StateValue
• type Status
  • func FromError(err error, sourcePlugin string, reasons ...string) *Status
  • func NewNonErrorStatus(code StatusCode, sourcePlugin string, reasons ...string) *Status
  • func (s *Status) AsError() error
  • func (s *Status) InternalError() error
  • func (s *Status) IsClusterUnschedulable() bool
  • func (s *Status) IsInteralError() bool
  • func (s *Status) IsSkip() bool
  • func (s *Status) IsSuccess() bool
  • func (s *Status) Reasons() []string
  • func (s *Status) SourcePlugin() string
  • func (s *Status) String() string
• type StatusCode
  • func (sc StatusCode) Name() string

Types

type ClusterScore

type ClusterScore struct {
	// TopologySpreadScore determines how much a binding would satisfy the topology spread
	// constraints specified by the user.
	TopologySpreadScore int
	// AffinityScore determines how much a binding would satisfy the affinity terms
	// specified by the user.
	AffinityScore int
	// ObsoletePlacementAffinityScore reflects if there has already been an obsolete binding from
	// the same cluster resource placement associated with the cluster; it value range should
	// be [0, 1], where 1 signals that an obsolete binding is present.
	//
	// Note that this score is for internal usage only; it serves the purpose of implementing
	// a preference for already selected clusters when all the other conditions are the same,
	// so as to minimize interruption between different scheduling runs.
	ObsoletePlacementAffinityScore int
}

ClusterScore is the scores the scheduler assigns to a cluster.

func (*ClusterScore) Add

func (s1 *ClusterScore) Add(s2 *ClusterScore)

Add adds a ClusterScore to another ClusterScore.

Note that this will panic if either score is nil.

func (*ClusterScore) Equal

func (s1 *ClusterScore) Equal(s2 *ClusterScore) bool

Equal returns true if a ClusterScore is equal to another.

func (*ClusterScore) Less

func (s1 *ClusterScore) Less(s2 *ClusterScore) bool

Less returns true if a ClusterScore is less than another.

Note that this will panic if either score is nil.

type CycleState

type CycleState struct {
	// contains filtered or unexported fields
}

CycleState is, similar to its namesake in kube-scheduler, provides a way for plugins to store and retrieve arbitrary data during a scheduling cycle. The scheduler also uses this struct to keep some global states during a scheduling cycle; note that these state are only accessible to the scheduler itself, not to plugins.

It uses a sync.Map for concurrency-safe storage.

func NewCycleState

func NewCycleState(clusters []clusterv1beta1.MemberCluster, obsoleteBindings []*placementv1beta1.ClusterResourceBinding, scheduledOrBoundBindings ...[]*placementv1beta1.ClusterResourceBinding) *CycleState

NewCycleState creates a CycleState.

func (*CycleState) Delete

func (c *CycleState) Delete(key StateKey)

Delete deletes a key from CycleState.

func (*CycleState) HasObsoleteBindingFor

func (c *CycleState) HasObsoleteBindingFor(clusterName string) bool

HasObsoleteBindingFor returns whether a cluster already has an obsolete binding associated.

This helps maintain consistence in a scheduling run and improve performance, i.e., the scheduler and all plugins can have the same view of current spread of bindings. and any plugin which requires the view no longer needs to list bindings on its own.

func (*CycleState) HasScheduledOrBoundBindingFor

func (c *CycleState) HasScheduledOrBoundBindingFor(clusterName string) bool

HasScheduledOrBoundBindingFor returns whether a cluster already has a scheduled or bound binding associated.

This helps maintain consistence in a scheduling run and improve performance, i.e., the scheduler and all plugins can have the same view of current spread of bindings. and any plugin which requires the view no longer needs to list bindings on its own.

func (*CycleState) ListClusters

func (c *CycleState) ListClusters() []clusterv1beta1.MemberCluster

ListClusters returns the list of clusters that the scheduler will inspect and evaluate in the current scheduling cycle.

This helps maintain consistency in a scheduling run and improve performance, i.e., the scheduler and all plugins can have the same view of clusters being evaluated, and any plugin which requires the view no longer needs to list clusters on its own.

Note that this is a relatively expensive op, as it returns the deep copy of the cluster list.

func (*CycleState) Read

func (c *CycleState) Read(key StateKey) (StateValue, error)

Read retrieves a value from CycleState by a key.

func (*CycleState) Write

func (c *CycleState) Write(key StateKey, val StateValue)

Write stores a value in CycleState under a key.

type CycleStatePluginReadWriter

type CycleStatePluginReadWriter interface {
	Read(key StateKey) (StateValue, error)
	Write(key StateKey, val StateValue)
	Delete(key StateKey)

	ListClusters() []clusterv1beta1.MemberCluster
	HasScheduledOrBoundBindingFor(clusterName string) bool
	HasObsoleteBindingFor(clusterName string) bool
}

CycleStatePluginReadWriter is an interface through which plugins can store and retrieve data.

TO-DO (chenyu1): Add methods which allow plugins to query for bindings of different types being evaluated in the current scheduling cycle.

type FilterPlugin

type FilterPlugin interface {
	Plugin

	// Filter runs at the Filter stage, to check if a placement can be bound to a specific cluster.
	// A plugin which registers at this extension point must return one of the follows:
	// * A Success status, if the placement can be bound to the cluster; or
	// * A ClusterUnschedulable status, if the placement cannot be bound to the cluster; or
	// * An InternalError status, if an expected error has occurred
	Filter(ctx context.Context, state CycleStatePluginReadWriter, policy *placementv1beta1.ClusterSchedulingPolicySnapshot, cluster *clusterv1beta1.MemberCluster) (status *Status)
}

FilterPlugin is the interface which all plugins that would like to run at the Filter extension point should implement.

type Framework

type Framework interface {
	Handle

	// RunSchedulingCycleFor performs scheduling for a cluster resource placement, specifically
	// its associated latest scheduling policy snapshot.
	RunSchedulingCycleFor(ctx context.Context, crpName string, policy *placementv1beta1.ClusterSchedulingPolicySnapshot) (result ctrl.Result, err error)
}

Framework is an interface which scheduler framework should implement.

func NewFramework

func NewFramework(profile *Profile, manager ctrl.Manager, opts ...Option) Framework

NewFramework returns a new scheduler framework.

type Handle

type Handle interface {
	// Client returns a cached client.
	Client() client.Client
	// Manager returns a controller manager; this is mostly used for setting up a new informer
	// (indirectly) via a reconciler.
	Manager() ctrl.Manager
	// UncachedReader returns an uncached read-only client, which allows direct (uncached) access to the API server.
	UncachedReader() client.Reader
	// EventRecorder returns an event recorder.
	EventRecorder() record.EventRecorder
	// ClusterEligibilityChecker returns the cluster eligibility checker associated with the scheduler.
	ClusterEligibilityChecker() *clustereligibilitychecker.ClusterEligibilityChecker
}

Handle is an interface which allows plugins to access some shared structs (e.g., client, manager) and set themselves up with the scheduler framework (e.g., sign up for an informer).

type Option

type Option func(*frameworkOptions)

Option is the function for configuring a scheduler framework.

func WithClusterEligibilityChecker

func WithClusterEligibilityChecker(checker *clustereligibilitychecker.ClusterEligibilityChecker) Option

WithClusterEligibilityChecker sets the cluster eligibility checker for a scheduler framework.

func WithMaxClusterDecisionCount

func WithMaxClusterDecisionCount(maxUnselectedClusterDecisionCount int) Option

WithMaxClusterDecisionCount sets the maximum number of decisions added to the policy snapshot status.

func WithNumOfWorkers

func WithNumOfWorkers(numOfWorkers int) Option

WithNumOfWorkers sets the number of workers to use for a scheduler framework.

type Plugin

type Plugin interface {
	Name() string

	// SetUpWithFramework helps a plugin to set it up with a scheduler framework, such as
	// spinning up an informer.
	SetUpWithFramework(handle Handle)
}

Plugin is the interface which all scheduler plugins should implement.

type PostBatchPlugin

type PostBatchPlugin interface {
	Plugin

	// PostBatch runs after the scheduler has determined the number of bindings to create;
	// a plugin which registers at this extension point must return one of the follows:
	// * A Success status with a new batch size; or
	// * A Skip status, if no changes in batch size is needed; or
	// * An InternalError status, if an expected error has occurred
	PostBatch(ctx context.Context, state CycleStatePluginReadWriter, policy *placementv1beta1.ClusterSchedulingPolicySnapshot) (size int, status *Status)
}

PostBatchPlugin is the interface which all plugins that would like to run at the PostBatch extension point should implement.

type PreFilterPlugin

type PreFilterPlugin interface {
	Plugin

	// PreFilter runs before the scheduler enters the Filter stage; a plugin may perform
	// some setup at this extension point, such as caching the results that will be used in
	// following Filter calls, and/or run some checks to determine if it should be skipped in
	// the Filter stage.
	//
	// A plugin which registers at this extension point must return one of the follows:
	// * A Success status, if the plugin should run at the Filter stage; or
	// * A Skip status, if the plugin should be skipped at the Filter stage; or
	// * An InternalError status, if an expected error has occurred
	PreFilter(ctx context.Context, state CycleStatePluginReadWriter, policy *placementv1beta1.ClusterSchedulingPolicySnapshot) (status *Status)
}

PreFilterPlugin is the interface which all plugins that would like to run at the PreFilter extension point should implement.

type PreScorePlugin

type PreScorePlugin interface {
	Plugin

	// PreScore runs before the scheduler enters the Score stage; a plugin may perform
	// some setup at this extension point, such as caching the results that will be used in
	// following Score calls, and/or run some checks to determine if it should be skipped in
	// the Filter stage.
	//
	// A plugin which registers at this extension point must return one of the follows:
	// * A Success status, if the plugin should run at the Score stage; or
	// * A Skip status, if the plugin should be skipped at the Score stage; or
	// * An InternalError status, if an expected error has occurred
	PreScore(ctx context.Context, state CycleStatePluginReadWriter, policy *placementv1beta1.ClusterSchedulingPolicySnapshot) (status *Status)
}

PreScorePlugin is the interface which all plugins that would like to run at the PreScore extension point should implement.

type Profile

type Profile struct {
	// contains filtered or unexported fields
}

Profile specifies the scheduling profile a framework uses; it includes the plugins in use by the framework at each extension point in order.

At this moment, since Fleet does not support runtime profiles, all plugins are registered directly to one universal profile, in their instantiated forms, rather than decoupled using a factory registry and instantiated along with the profile's associated framework.

func NewProfile

func NewProfile(name string) *Profile

NewProfile creates scheduling profile.

func (*Profile) Name

func (profile *Profile) Name() string

Name returns the name of the profile.

func (*Profile) WithFilterPlugin

func (profile *Profile) WithFilterPlugin(plugin FilterPlugin) *Profile

WithFilterPlugin registers a FilterPlugin to the profile.

func (*Profile) WithPostBatchPlugin

func (profile *Profile) WithPostBatchPlugin(plugin PostBatchPlugin) *Profile

WithPostBatchPlugin registers a PostBatchPlugin to the profile.

func (*Profile) WithPreFilterPlugin

func (profile *Profile) WithPreFilterPlugin(plugin PreFilterPlugin) *Profile

WithPreFilterPlugin registers a PreFilterPlugin to the profile.

func (*Profile) WithPreScorePlugin

func (profile *Profile) WithPreScorePlugin(plugin PreScorePlugin) *Profile

WithPreScorePlugin registers a PreScorePlugin to the profile.

func (*Profile) WithScorePlugin

func (profile *Profile) WithScorePlugin(plugin ScorePlugin) *Profile

WithScorePlugin registers a ScorePlugin to the profile.

type ScorePlugin

type ScorePlugin interface {
	Plugin

	// Score runs at the Score stage, to score a cluster for a specific placement.
	// A plugin which registers at this extension point must return one of the follows:
	// * A Success status, with the score for the cluster; or
	// * An InternalError status, if an expected error has occurred
	Score(ctx context.Context, state CycleStatePluginReadWriter, policy *placementv1beta1.ClusterSchedulingPolicySnapshot, cluster *clusterv1beta1.MemberCluster) (score *ClusterScore, status *Status)
}

ScorePlugin is the interface which all plugins that would like to run at the Score extension point should implement.

type ScoredCluster

type ScoredCluster struct {
	Cluster *clusterv1beta1.MemberCluster
	Score   *ClusterScore
}

ScoredCluster is a cluster with a score.

type ScoredClusters

type ScoredClusters []*ScoredCluster

ScoredClusters is a list of ScoredClusters; this type implements the sort.Interface.

func (ScoredClusters) Len

func (sc ScoredClusters) Len() int

Len returns the length of a ScoredClusters; it implemented sort.Interface.Len().

func (ScoredClusters) Less

func (sc ScoredClusters) Less(i, j int) bool

Less returns true if a ScoredCluster is of a lower score than another; when two clusters have the same score, the one with a name that is lexicographically smaller is considered to be the smaller one.

It implemented sort.Interface.Less().

Note that this will panic if there is a reference to nil scores and/or clusters; caller should verify if the list is valid.

func (ScoredClusters) Swap

func (sc ScoredClusters) Swap(i, j int)

Swap swaps two ScoredClusters in the list; it implemented sort.Interface.Swap().

type StateKey

type StateKey string

StateKey is the key for a state value stored in a CycleState.

type StateValue

type StateValue interface{}

StateValue is the value stored in a CycleState under a specific key.

type Status

type Status struct {
	// contains filtered or unexported fields
}

Status is the result yielded by a plugin.

func FromError

func FromError(err error, sourcePlugin string, reasons ...string) *Status

FromError returns a Status from an error.

func NewNonErrorStatus

func NewNonErrorStatus(code StatusCode, sourcePlugin string, reasons ...string) *Status

NewNonErrorStatus returns a Status with a non-error status code. To return a Status of the internalError status code, use FromError() instead.

func (*Status) AsError

func (s *Status) AsError() error

AsError returns a status as an error; it returns nil if the status is of the internalError code.

func (*Status) InternalError

func (s *Status) InternalError() error

InternalError returns the error associated with a Status.

func (*Status) IsClusterUnschedulable

func (s *Status) IsClusterUnschedulable() bool

IsClusterUnschedulable returns if a Status is of the status code ClusterUnschedulable.

func (*Status) IsInteralError

func (s *Status) IsInteralError() bool

IsInternalError returns if a Status is of the status code interalError.

func (*Status) IsSkip

func (s *Status) IsSkip() bool

IsPreSkip returns if a Status is of the status code Skip.

func (*Status) IsSuccess

func (s *Status) IsSuccess() bool

IsSuccess returns if a Status is of the status code Success.

func (*Status) Reasons

func (s *Status) Reasons() []string

Reasons returns the reasons of a Status.

func (*Status) SourcePlugin

func (s *Status) SourcePlugin() string

SourcePlugin returns the source plugin associated with a Status.

func (*Status) String

func (s *Status) String() string

String returns the description of a Status.

type StatusCode

type StatusCode int

StatusCode is the status code of a Status, returned by a plugin.

const (
	// Success signals that a plugin has completed its run successfully.
	// Note that a nil *Status is also considered as a Success Status.
	Success StatusCode = iota

	// ClusterUnschedulable signals that a plugin has found that a placement should not be bound
	// to a specific cluster.
	ClusterUnschedulable
	// Skip signals that no action is needed for the plugin to take at the stage.
	// If this is returned by a plugin at the Pre- stages (PreFilter or PreScore), the associated
	// plugin will be skipped at the following stages (Filter or Score) as well. This helps
	// reduce the overhead of having to repeatedly call a plugin that is not needed for every
	// cluster in the Filter or Score stage.
	Skip
)

Pre-defined status codes.

func (StatusCode) Name

func (sc StatusCode) Name() string

Name returns the name of a status code.