sdk

package
v0.4.5 Latest Latest
Warning

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

 Go to latest Published: Aug 13, 2024 License: MPL-2.0 Imports: 6 Imported by: 14

Documentation

Index

Constants

View Source 
const (
	// PluginTypeBase is plugin component that all plugins must implement.
	PluginTypeBase = "base"

	// PluginTypeAPM is a plugin which satisfies the APM interface.
	PluginTypeAPM = "apm"

	// PluginTypeTarget is a plugin which satisfies the Target interface.
	PluginTypeTarget = "target"

	// PluginTypeStrategy is a plugin which satisfies the Strategy interface.
	PluginTypeStrategy = "strategy"
)
View Source 
const (
	ScalingPolicyTypeCluster    = "cluster"
	ScalingPolicyTypeHorizontal = "horizontal"

	ScalingPolicyOnErrorFail   = "fail"
	ScalingPolicyOnErrorIgnore = "ignore"
)
View Source 
const (
	// ScaleDirectionDown indicates the target should lower the number of running
	// instances of the resource.
	ScaleDirectionDown = iota - 1

	// ScaleDirectionNone indicates no scaling is required.
	ScaleDirectionNone

	// ScaleDirectionUp indicates the target should increase the number of
	// running instances of the resource.
	ScaleDirectionUp
)

The following constants are used to standardize the possible scaling directions for an Action. They are ordered from riskier to safest, with ScaleDirectionNone as the default and zero value.

View Source 
const (
	// TargetStatusMetaKeyLastEvent is an optional meta key that can be added
	// to the status return. The value represents the last scaling event of the
	// target as seen by the remote providers view point. This helps enforce
	// cooldown where out-of-band scaling activities have been triggered.
	TargetStatusMetaKeyLastEvent = "nomad_autoscaler.last_event"

	// TargetConfigKeyNamespace is the config key used within horizontal app
	// scaling to identify the Nomad namespace targeted for autoscaling.
	TargetConfigKeyNamespace = "Namespace"

	// TargetConfigKeyJob is the config key used within horizontal app scaling
	// to identify the Nomad job targeted for autoscaling.
	TargetConfigKeyJob = "Job"

	// TargetConfigKeyTaskGroup is the config key used within horizontal app
	// scaling to identify the Nomad job group targeted for autoscaling.
	TargetConfigKeyTaskGroup = "Group"

	// TargetConfigKeyClass is the horizontal cluster scaling target
	// config key which identifies nodes as part of a pool of resources using
	// the clients node_class configuration param.
	TargetConfigKeyClass = "node_class"

	// TargetConfigKeyNodePool is the horizontal cluster scaling target config
	// key which identifies nodes as part of a pool of resources using the
	// clients node_pool configuration param.
	TargetConfigKeyNodePool = "node_pool"

	// TargetConfigKeyDatacenter is the horizontal cluster scaling target
	// config key which identifies nodes as part of a pool of resources using
	// the agents datacenter configuration param.
	TargetConfigKeyDatacenter = "datacenter"

	// TargetConfigKeyDrainDeadline is the config key which defines the
	// override value to use when draining a Nomad client during the scale in
	// action of horizontal cluster scaling.
	TargetConfigKeyDrainDeadline = "node_drain_deadline"

	// TargetConfigKeyIgnoreSystemJobs is the config key which defines whether or not
	// nomad system jobs are drained during the drain operation
	TargetConfigKeyIgnoreSystemJobs = "node_drain_ignore_system_jobs"

	// TargetConfigKeyNodePurge is the config key which defines whether or not
	// Nomad clients are purged from Nomad once they have been terminated
	// within their provider.
	TargetConfigKeyNodePurge = "node_purge"

	// TargetConfigNodeSelectorStrategy is the optional node target config
	// option which dictates how the Nomad Autoscaler selects nodes when
	// scaling in.
	TargetConfigNodeSelectorStrategy = "node_selector_strategy"
)
View Source 
const (
	// TargetNodeSelectorStrategyLeastBusy is the cluster scale-in node
	// selection strategy that identifies nodes based on their CPU and Memory
	// resource allocation. It picks those with lowest values and is the
	// default strategy.
	TargetNodeSelectorStrategyLeastBusy = "least_busy"

	// TargetNodeSelectorStrategyNewestCreateIndex is the cluster scale-in node
	// selection strategy that uses the sorting perform by the SDK. This
	// sorting is based on the nodes CreateIndex, where nodes with higher
	// indexes are selected. This is the fastest of the strategies and should
	// be used if you have performance concerns or do not care about node
	// selection.
	TargetNodeSelectorStrategyNewestCreateIndex = "newest_create_index"

	// TargetNodeSelectorStrategyEmpty is the cluster scale-in node selection
	// strategy that only picks nodes without non-terminal allocations.
	TargetNodeSelectorStrategyEmpty = "empty"

	// TargetNodeSelectorStrategyEmptyIgnoreSystemJobs is the cluster scale-in
	// node selection strategy that only picks nodes without non-terminal
	// allocations, without considering system jobs.
	TargetNodeSelectorStrategyEmptyIgnoreSystemJobs = "empty_ignore_system"
)
View Source 
const (

	// StrategyActionMetaValueDryRunCount is a special count value used when
	// performing dry-run scaling activities. The Autoscaler will never set a
	// count to a negative value during normal operation, so the agent is safe
	// to assume a count set to this value implies dry-run.
	StrategyActionMetaValueDryRunCount = -1
)

Variables

View Source 
var TargetConfigConflictingClusterParams = []string{TargetConfigKeyDatacenter, TargetConfigKeyClass}

TargetConfigConflictingClusterParams is a list containing horizontal cluster scaling target configuration options which conflict. This makes it easier to create error messages.

Functions

This section is empty.

Types

type FileDecodePolicyCheckDoc 

type FileDecodePolicyCheckDoc struct {
	Name                 string `hcl:"name,label"`
	Group                string `hcl:"group,optional"`
	Source               string `hcl:"source,optional"`
	Query                string `hcl:"query,optional"`
	QueryWindow          time.Duration
	QueryWindowHCL       string `hcl:"query_window,optional"`
	QueryWindowOffset    time.Duration
	QueryWindowOffsetHCL string                 `hcl:"query_window_offset,optional"`
	OnError              string                 `hcl:"on_error,optional"`
	Strategy             *ScalingPolicyStrategy `hcl:"strategy,block"`
}

func (*FileDecodePolicyCheckDoc) Translate 

func (fdc *FileDecodePolicyCheckDoc) Translate(c *ScalingPolicyCheck)

Translate all values from the decoded policy check into our internal policy check object.

type FileDecodePolicyDoc 

type FileDecodePolicyDoc struct {
	Cooldown              time.Duration
	CooldownHCL           string `hcl:"cooldown,optional"`
	EvaluationInterval    time.Duration
	EvaluationIntervalHCL string                      `hcl:"evaluation_interval,optional"`
	OnCheckError          string                      `hcl:"on_check_error,optional"`
	Checks                []*FileDecodePolicyCheckDoc `hcl:"check,block"`
	Target                *ScalingPolicyTarget        `hcl:"target,block"`
}

type FileDecodeScalingPolicies 

type FileDecodeScalingPolicies struct {
	ScalingPolicies []*FileDecodeScalingPolicy `hcl:"scaling,block"`
}

type FileDecodeScalingPolicy 

type FileDecodeScalingPolicy struct {
	Name    string               `hcl:"name,label"`
	Enabled bool                 `hcl:"enabled,optional"`
	Type    string               `hcl:"type,optional"`
	Min     int64                `hcl:"min,optional"`
	Max     int64                `hcl:"max"`
	Doc     *FileDecodePolicyDoc `hcl:"policy,block"`
}

FileDecodeScalingPolicy is used as an intermediate step when decoding a policy from a file. It is needed because the internal Policy object is flattened when compared to the literal HCL version. Therefore we cannot translate into the internal struct but use this.

func (*FileDecodeScalingPolicy) Translate 

func (fpd *FileDecodeScalingPolicy) Translate() *ScalingPolicy

Translate all values from the decoded policy file into our internal policy object.

type ScaleDirection 

type ScaleDirection int8

ScaleDirection is an identifier used by strategy plugins to identify how the target should scale the named resource.

func (ScaleDirection) String 

func (d ScaleDirection) String() string

String satisfies the Stringer interface and returns as string representation of the scaling direction.

type ScalingAction 

type ScalingAction struct {

	// Count represents the desired count of the target resource. It should
	// always be zero or above, expect in the event of dry-run where it can use
	// the StrategyActionMetaValueDryRunCount value.
	Count int64

	// Reason is the top level string that provides a user friendly description
	// of why the strategy decided the action was required.
	Reason string

	// Error indicates whether the Reason string is an error condition. This
	// allows the Reason to be flexible in its use.
	Error bool

	// Direction is the scaling direction the strategy has decided should
	// happen. This is particularly helpful for non-Nomad target
	// implementations whose APIs dead with increment changes rather than
	// absolute counts.
	Direction ScaleDirection

	// Meta
	Meta map[string]interface{}
}

ScalingAction represents a strategy plugins intention to change the current target state. It includes all the required information to enact the change, along with useful meta information for operators and admins.

func PreemptScalingAction 

func PreemptScalingAction(a *ScalingAction, b *ScalingAction) *ScalingAction

PreemptScalingAction determines which ScalingAction should take precedence.

The result is based on the scaling direction and count. The order of precedence for the scaling directions is defined by the order in which they are declared in the above enum.

If the scaling direction is the same, the priority is given to the safest option, where safest is defined as lowest impact in the underlying infrastructure:

* ScaleDirectionUp: Action with highest count * ScaleDirectionDown: Action with highest count

func (*ScalingAction) Canonicalize 

func (a *ScalingAction) Canonicalize()

Canonicalize ensures Action has proper default values.

func (*ScalingAction) CapCount 

func (a *ScalingAction) CapCount(min, max int64)

CapCount caps the value of Count so it remains within the specified limits. If Count is StrategyActionMetaValueDryRunCount this method has no effect.

func (*ScalingAction) SetDryRun 

func (a *ScalingAction) SetDryRun()

SetDryRun marks the Action to be executed in dry-run mode. Dry-run mode is indicated using Meta tags. A dry-run action doesn't modify the Target's count value.

type ScalingCheckEvaluation 

type ScalingCheckEvaluation struct {

	// Check is the individual ScalingPolicyCheck that this eval is concerned
	// with.
	Check *ScalingPolicyCheck

	// Metrics is the metric resulting from querying the APM.
	Metrics TimestampedMetrics

	// Action is the calculated desired state and is populated by strategy.Run.
	Action *ScalingAction
}

ScalingCheckEvaluation is the evaluation of an individual policy check. Each check eval within a ScalingEvaluation is performed concurrently and a single "winner" picked once all have returned.

type ScalingEvaluation 

type ScalingEvaluation struct {
	ID               string
	Policy           *ScalingPolicy
	CheckEvaluations []*ScalingCheckEvaluation
	CreateTime       time.Time
}

ScalingEvaluation forms an individual analysis undertaken by the autoscaler in order to determine the desired state of a target.

func NewScalingEvaluation 

func NewScalingEvaluation(p *ScalingPolicy) *ScalingEvaluation

NewScalingEvaluation creates a new ScalingEvaluation based off the passed policy and status. It is responsible for hydrating all the fields to a basic level for safe usage throughout the scaling evaluation phase.

type ScalingPolicy 

type ScalingPolicy struct {

	// ID is a UUID which uniquely identifies this scaling policy. Depending on
	// the policy source this will be sourced in different manners.
	ID string

	// Type is the type of scaling this policy will perform.
	Type string

	// Priority controls the order in which a policy is picked for evaluation.
	Priority int

	// Min forms a lower bound at which the target should never be asked to
	// break. The autoscaler will actively adjust recommendations to ensure
	// this value is not violated.
	Min int64

	// Max forms an upper bound at which the target should never be asked to
	// exceed. The autoscaler will actively adjust recommendations to ensure
	// this value is not violated.
	Max int64

	// Enabled indicates whether the autoscaler should actively evaluate the
	// policy or not.
	Enabled bool

	// OnCheckError defines how errors are handled by the Autoscaler when
	// running the policy checks. Possible values are "ignore" or "fail".
	//
	// If "ignore" the policy evaluation will continue even if a check fails.
	// If "fail" the the entire policy evaluation will stop and no action will
	// be taken.
	OnCheckError string

	// Cooldown is the time period after a scaling action if performed, during
	// which no policy evaluations will be started.
	Cooldown time.Duration

	// EvaluationInterval indicates the frequency at which the policy is
	// evaluated. A lower value means more frequent evaluation and can result
	// in a high rate of change in the target.
	EvaluationInterval time.Duration

	// Checks is an array of checks which will be triggered in parallel to
	// determine the desired state of the ScalingPolicyTarget.
	Checks []*ScalingPolicyCheck

	// Target identifies the scaling target which the autoscaler will interact
	// with to ensure it meets the desired state as determined by the Checks.
	Target *ScalingPolicyTarget
}

ScalingPolicy is the internal representation of a scaling document and encompasses all the required information for the autoscaler to perform scaling evaluations on a target.

func (*ScalingPolicy) Validate added in v0.3.4 

func (p *ScalingPolicy) Validate() error

Validate applies validation rules that are independent of policy source.

type ScalingPolicyCheck 

type ScalingPolicyCheck struct {

	// Name is a human readable name for this check and allows operators to
	// create clearly identified policy checks.
	Name string

	// Group is used to group related checks together. Their results will be
	// consolidated into a single action.
	Group string

	// Source is the APM plugin that should be used to perform the query and
	// obtain the metric that will be used to perform a calculation.
	Source string

	// Query is run against the Source in order to receive a metric response.
	Query string

	// QueryWindow is used to define how further back in time to query for
	// metrics.
	QueryWindow time.Duration

	// QueryWindowOffset defines an offset from the current time to apply to
	// the query window.
	QueryWindowOffset time.Duration

	// Strategy is the ScalingPolicyStrategy to use when performing the
	// ScalingPolicyCheck evaluation.
	Strategy *ScalingPolicyStrategy

	// OnError defines how errors are handled by the Autoscaler when running
	// this check. Possible values are "ignore" or "fail". If not set the
	// policy `on_check_error` value will be used.
	//
	// If "ignore" the check is not considered when calculating the final
	// scaling action result.
	// If "fail" the the entire policy evaluation will stop and no action will
	// be taken.
	OnError string
}

ScalingPolicyCheck is an individual check within a scaling policy.This check will be executed in isolation alongside other checks within the policy.

type ScalingPolicyStrategy 

type ScalingPolicyStrategy struct {

	// Name is the strategy that will be used to perform the desired state
	// calculation.
	Name string `hcl:"name,label"`

	// Config is the mapping of config values used by the strategy plugin. Each
	// plugin has a set of potentially uniquely supported keys.
	Config map[string]string `hcl:",remain"`
}

ScalingPolicyStrategy contains the plugin and configuration details for calculating the desired target state from the current state.

type ScalingPolicyTarget 

type ScalingPolicyTarget struct {

	// Name identifies the target plugin which can handle performing target
	// requests for this ScalingPolicy.
	Name string `hcl:"name,label"`

	// Config is the mapping of config values used by the target plugin. Each
	// plugin has a set of potentially uniquely supported keys.
	Config map[string]string `hcl:",remain"`
}

ScalingPolicyTarget identifies the target for which the ScalingPolicy as a whole is configured for.

func (*ScalingPolicyTarget) IsJobTaskGroupTarget 

func (t *ScalingPolicyTarget) IsJobTaskGroupTarget() bool

IsJobTaskGroupTarget identifies whether the ScalingPolicyTarget relates to a Nomad job group.

func (*ScalingPolicyTarget) IsNodePoolTarget 

func (t *ScalingPolicyTarget) IsNodePoolTarget() bool

IsNodePoolTarget identifies whether the ScalingPolicyTarget relates to Nomad client nodes and therefore horizontal cluster scaling.

type TargetScalingNoOpError added in v0.3.4 

type TargetScalingNoOpError struct {
	Err error
}

TargetScalingNoOpError is a special error type that can be used by target plugins to indicate that a scaling request didn't result in any action, but didn't fail either. This can be used to avoid post-scaling actions such as placing the policy in cooldown.

func NewTargetScalingNoOpError added in v0.3.4 

func NewTargetScalingNoOpError(msg string, args ...interface{}) *TargetScalingNoOpError

NewTargetScalingNoOpError returns a new target scaling no-op error with the provided formatted message.

func (*TargetScalingNoOpError) Error added in v0.3.4 

func (n *TargetScalingNoOpError) Error() string

Error implements the error interface.

type TargetStatus 

type TargetStatus struct {

	// Ready indicates whether the target is currently in a state where scaling
	// is permitted.
	Ready bool

	// Count is the current value of the target and thus performs the current
	// state basis when performing strategy calculations to identify the
	// desired state.
	Count int64

	// Meta is a mapping that provides additional information about the target
	// that can be used during the policy evaluation to ensure the correct
	// calculations and logic are applied to the target.
	Meta map[string]string
}

TargetStatus is the response object when performing the Status call of the target plugin interface. The response details key information about the current state of the target.

type TimeRange 

type TimeRange struct {
	From time.Time
	To   time.Time
}

TimeRange defines a range of time.

type TimestampedMetric 

type TimestampedMetric struct {
	Timestamp time.Time
	Value     float64
}

TimestampedMetric contains a single metric Value along with its associated Timestamp.

type TimestampedMetrics 

type TimestampedMetrics []TimestampedMetric

TimestampedMetrics is an array of timestamped metric values. This type is used so we can sort metrics based on the timestamp.

func (TimestampedMetrics) Len 

func (t TimestampedMetrics) Len() int

Len satisfies the Len function of the sort.Interface interface.

func (TimestampedMetrics) Less 

func (t TimestampedMetrics) Less(i, j int) bool

Less satisfies the Less function of the sort.Interface interface.

func (TimestampedMetrics) Swap 

func (t TimestampedMetrics) Swap(i, j int)

Swap satisfies the Swap function of the sort.Interface interface.

Source Files

View all Source files

Directories

Path Synopsis
helper
blocking
error
file
flag
modes
nomad
ptr
scaleutils
scaleutils/nodepool
scaleutils/nodeselector
uuid

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.