api

type AgentRequest ¶

type AgentRequest struct {
	// ProtoVersion is the version of the protocol that the autoscaler-agent is expecting to use
	//
	// If the scheduler does not support this version, then it will respond with a 400 status.
	ProtoVersion PluginProtoVersion `json:"protoVersion"`
	// Pod is the namespaced name of the pod making the request
	Pod util.NamespacedName `json:"pod"`
	// ComputeUnit gives the value of the agent's configured compute unit to use for the VM.
	//
	// If the requested resources are not a multiple of ComputeUnit, the scheduler plugin will make
	// a best-effort attempt to return a value satisfying the request. Any approved increases will
	// be a multiple of ComputeUnit, but otherwise the plugin does not check.
	ComputeUnit Resources `json:"computeUnit"`
	// Resources gives a requested or notified change in resources allocated to the VM.
	//
	// The requested amount MAY be equal to the current amount, in which case it serves as a
	// notification that the VM should no longer be contributing to resource pressure.
	//
	// TODO: allow passing nil here if nothing's changed (i.e., the request would be the same as the
	// previous request)
	Resources Resources `json:"resources"`
	// LastPermit indicates the last permit that the agent has received from the scheduler plugin.
	// In case of a failure, the new running scheduler uses LastPermit to recover the previous state.
	// LastPermit may be nil.
	LastPermit *Resources `json:"lastPermit"`
	// Metrics provides information about the VM's current load, so that the scheduler may
	// prioritize which pods to migrate
	//
	// In some protocol versions, this field may be nil.
	Metrics *Metrics `json:"metrics"`
}

AgentRequest is the type of message sent from an autoscaler-agent to the scheduler plugin

All AgentRequests expect a PluginResponse.

func (r AgentRequest) ProtocolRange() VersionRange[PluginProtoVersion]

type Allocation ¶ added in v0.15.0

type Allocation struct {
	// Number of vCPUs
	Cpu float64 `json:"cpu"`

	// Number of bytes
	Mem uint64 `json:"mem"`
}

Represents the resources that a VM has been granted

type Bytes ¶ added in v0.23.0

type Bytes uint64

Bytes represents a number of bytes, with custom marshaling / unmarshaling that goes through resource.Quantity in order to have simplified values over wire

func BytesFromResourceQuantity(r resource.Quantity) Bytes

func (b Bytes) AsFloat64() float64

func (b Bytes) Format(state fmt.State, verb rune)

func (b Bytes) MarshalJSON() ([]byte, error)

func (b Bytes) ToResourceQuantity() *resource.Quantity

func (b *Bytes) UnmarshalJSON(data []byte) error

type DownscaleRequest ¶ added in v0.15.0

type DownscaleRequest struct {
	Target Allocation `json:"target"`
}

This type is sent to the monitor as a request to downscale its resource usage. Once the monitor has downscaled or failed to do so, it should respond with a DownscaleResult.

type DownscaleResult ¶

type DownscaleResult struct {
	Ok     bool
	Status string
}

This type is sent to the agent to indicate if downscaling was successful. The agent does not need to respond.

type HealthCheck ¶ added in v0.15.0

type HealthCheck struct{}

This type is sent as part of a bidirectional heartbeat between the monitor and agent. The check is initiated by the agent.

type InternalError ¶ added in v0.15.0

type InternalError struct {
	Error string `json:"error"`
}

This type can be sent by either party to signal that an error occurred carrying out the other party's request, for example, the monitor erroring while trying to downscale. The receiving party can they log the error or propagate it as they see fit.

type InvalidMessage ¶ added in v0.15.0

type InvalidMessage struct {
	Error string `json:"error"`
}

This type can be sent by either party whenever they receive a message they cannot deserialize properly.

type Metrics ¶

type Metrics struct {
	LoadAverage1Min float32 `json:"loadAvg1M"`
	// DEPRECATED. Will be removed in an upcoming release.
	LoadAverage5Min *float32 `json:"loadAvg5M,omitempty"`
	// DEPRECATED. Will be removed in an upcoming release.
	MemoryUsageBytes *float32 `json:"memoryUsageBytes,omitempty"`
}

Metrics gives the information pulled from vector.dev that the scheduler may use to prioritize which pods it should migrate.

type MigrateResponse ¶

type MigrateResponse struct{}

MigrateResponse, when provided, is a notification to the autsocaler-agent that it will migrate

After receiving a MigrateResponse, the autoscaler-agent MUST NOT change its resource allocation.

TODO: fill this with more information as required

type MonitorProtoVersion ¶ added in v0.15.0

type MonitorProtoVersion uint32

MonitorProtoVersion represents a single version of the agent<->monitor protocol

Each version of the agent<->monitor protocol is named independently from releases of the repository containing this code. Names follow semver, although this does not necessarily guarantee support - for example, the monitor may only support versions above v1.1.

Version compatibility is documented in the neighboring file VERSIONING.md.

func (v MonitorProtoVersion) String() string

type MonitorProtocolResponse ¶ added in v0.15.0

type MonitorProtocolResponse struct {
	// If `Error` is nil, contains the value of the settled on protocol version.
	// Otherwise, will be set to 0 (MonitorProtocolVersion's zero value).
	Version MonitorProtoVersion `json:"version,omitempty"`

	// Will be nil if no error occurred.
	Error *string `json:"error,omitempty"`
}

Sent back by the monitor after figuring out what protocol version we should use

type MoreResources ¶

type MoreResources struct {
	// Cpu is true if the vm-monitor is requesting more CPU
	Cpu bool `json:"cpu"`
	// Memory is true if the vm-monitor is requesting more memory
	Memory bool `json:"memory"`
}

MoreResources holds the data associated with a MoreResourcesRequest

func (m MoreResources) And(cmp MoreResources) MoreResources

func (m MoreResources) Not() MoreResources

type PluginProtoVersion ¶ added in v0.1.8

type PluginProtoVersion uint32

PluginProtoVersion represents a single version of the agent<->scheduler plugin protocol

Each version of the agent<->scheduler plugin protocol is named independently from releases of the repository containing this code. Names follow semver, although this does not necessarily guarantee support - for example, the plugin may only support a single version, even though others may appear to be semver-compatible.

Version compatibility is documented in the neighboring file VERSIONING.md.

const (
	// PluginProtoV1_0 represents v1.0 of the agent<->scheduler plugin protocol - the initial
	// version.
	//
	// Last used in release version v0.1.8.
	PluginProtoV1_0 PluginProtoVersion = iota + 1 // start from zero, for backwards compatibility with pre-versioned messages

	// PluginProtoV1_1 represents v1.1 of the agent<->scheduler plugin protocol.
	//
	// Changes from v1.0:
	//
	// * Allows a nil value of the AgentRequest.Metrics field.
	//
	// Last used in release version v0.6.0.
	PluginProtoV1_1

	// PluginProtoV2_0 represents v2.0 of the agent<->scheduler plugin protocol.
	//
	// Changes from v1.1:
	//
	// * Supports fractional CPU
	//
	// Last used in release version v0.19.x.
	PluginProtoV2_0

	// PluginProtoV2_1 represents v2.1 of the agent<->scheduler plugin protocol.
	//
	// Changes from v2.0:
	//
	// * added AgentRequest.LastPermit
	//
	// Last used in release version v0.21.0.
	PluginProtoV2_1

	// PluginProtoV3_0 represents v3.0 of the agent<->scheduler plugin protocol.
	//
	// Changes from v2.1:
	//
	// * Removes PluginResponse.ComputeUnit (agent is now responsible for source of truth)
	//
	// Last used in release version v0.22.0.
	PluginProtoV3_0

	// PluginProtoV4_0 represents v4.0 of the agent<->scheduler plugin protocol.
	//
	// Changes from v3.0:
	//
	// * Memory quantities now use "number of bytes" instead of "number of memory slots"
	// * Adds AgentRequest.ComputeUnit
	//
	// Last used in release version v0.27.0.
	PluginProtoV4_0

	// PluginProtoV5_0 represents v5.0 of the agent<->scheduler plugin protocol.
	//
	// Changes from v4.0:
	//
	// * Removed AgentRequest.metrics fields loadAvg5M and memoryUsageBytes
	//
	// Currently the latest version.
	PluginProtoV5_0
)

func (v PluginProtoVersion) AgentSendsComputeUnit() bool

func (v PluginProtoVersion) AllowsNilMetrics() bool

func (v PluginProtoVersion) IncludesExtendedMetrics() bool

func (v PluginProtoVersion) IsValid() bool

func (v PluginProtoVersion) PluginSendsComputeUnit() bool

func (v PluginProtoVersion) RepresentsMemoryAsBytes() bool

func (v PluginProtoVersion) String() string

func (v PluginProtoVersion) SupportsFractionalCPU() bool

type PluginResponse ¶

type PluginResponse struct {
	// Permit provides an upper bound on the resources that the VM is now allowed to consume
	//
	// If the request's Resources were less than or equal its current resources, then the Permit
	// will exactly equal those resources. Otherwise, it may contain resource allocations anywhere
	// between the current and requested resources, inclusive.
	Permit Resources `json:"permit"`

	// Migrate, if present, notifies the autoscaler-agent that its VM will be migrated away,
	// alongside whatever other information may be useful.
	Migrate *MigrateResponse `json:"migrate,omitempty"`
}

type ResourceBounds ¶ added in v0.7.0

type ResourceBounds struct {
	CPU resource.Quantity `json:"cpu"`
	Mem resource.Quantity `json:"mem"`
}

type Resources ¶

type Resources struct {
	VCPU vmapi.MilliCPU `json:"vCPUs"`
	// Mem gives the number of bytes of memory requested
	Mem Bytes `json:"mem"`
}

Resources represents an amount of CPU and memory

When used in an AgentRequest, it represents the desired total amount of resources. When a resource is increasing, the autoscaler-agent "requests" the change to confirm that the resources are available. When decreasing, the autoscaler-agent is expected to use Resources to "notify" the scheduler -- i.e., the resource amount should have already been decreased. When a resource stays at the same amount, the associated AgentRequest serves to indicate that the autoscaler-agent is "satisfied" with its current resources, and should no longer contribute to any existing resource pressure.

When used a PluginResponse (as a Permit), then the Resources serves to inform the autoscaler-agent of the amount it has been permitted to use, subject to node resource limits.

In all cases, each resource type is considered separately from the others.

func (r Resources) AbsDiff(cmp Resources) Resources

func (r Resources) Add(other Resources) Resources

func (r Resources) CheckValuesAreReasonablySized() error

func (r Resources) ConvertToAllocation() Allocation

func (r Resources) HasFieldGreaterThan(cmp Resources) bool

func (r Resources) HasFieldLessThan(cmp Resources) bool

func (r Resources) IncreaseFrom(old Resources) MoreResources

func (r Resources) MarshalLogObject(enc zapcore.ObjectEncoder) error

func (r Resources) Max(cmp Resources) Resources

func (r Resources) Min(cmp Resources) Resources

func (r Resources) Mul(factor uint16) Resources

func (r Resources) SaturatingSub(other Resources) Resources

func (r Resources) ValidateNonZero() error

type RunnerProtoVersion ¶ added in v0.7.0

type RunnerProtoVersion uint32

this a similar version type for controller <-> runner communications see PluginProtoVersion comment for details

const (
	RunnerProtoV1 RunnerProtoVersion = iota + 1
)

func (v RunnerProtoVersion) SupportsCgroupFractionalCPU() bool

type ScalingBounds ¶ added in v0.7.0

type ScalingBounds struct {
	Min ResourceBounds `json:"min"`
	Max ResourceBounds `json:"max"`
}

ScalingBounds is the type that we deserialize from the "autoscaling.neon.tech/bounds" annotation

All fields (and sub-fields) are pointers so that our handling can distinguish between "field not set" and "field equal to zero". Please note that all field are still required to be set and non-zero, though.

func (b ScalingBounds) Validate(memSlotSize *resource.Quantity) error

type ScalingConfig ¶ added in v0.7.0

type ScalingConfig struct {
	// LoadAverageFractionTarget sets the desired fraction of current CPU that the load average
	// should be. For example, with a value of 0.7, we'd want load average to sit at 0.7 ×
	// CPU,
	// scaling CPU to make this happen.
	LoadAverageFractionTarget float64 `json:"loadAverageFractionTarget"`

	// MemoryUsageFractionTarget sets the desired fraction of current memory that
	// we would like to be using. For example, with a value of 0.7, on a 4GB VM
	// we'd like to be using 2.8GB of memory.
	MemoryUsageFractionTarget float64 `json:"memoryUsageFractionTarget"`
}

ScalingConfig provides bits of configuration for how the autoscaler-agent makes scaling decisions

func (c *ScalingConfig) Validate() error

type UpscaleConfirmation ¶ added in v0.15.0

type UpscaleConfirmation struct{}

This type is sent to the agent to confirm it successfully upscaled, meaning it increased its filecache and/or cgroup memory limits. The agent does not need to respond.

type UpscaleNotification ¶ added in v0.15.0

type UpscaleNotification struct {
	Granted Allocation `json:"granted"`
}

This type is sent to the monitor to inform it that it has been granted a geater allocation. Once the monitor is done applying this new allocation (i.e, increasing file cache size, cgroup memory limits) it should reply with an UpscaleConfirmation.

type UpscaleRequest ¶ added in v0.15.0

type UpscaleRequest struct{}

This type is sent to the agent as a way to request immediate upscale. Since the agent cannot control if the agent will choose to upscale the VM, it does not return anything. If an upscale is granted, the agent will notify the monitor via an UpscaleConfirmation

type VCPUCgroup ¶ added in v0.7.0

type VCPUCgroup struct {
	VCPUs vmapi.MilliCPU
}

VCPUCgroup is used in runner to reply to controller it represents the vCPU usage as controlled by cgroup

type VCPUChange ¶ added in v0.7.0

type VCPUChange struct {
	VCPUs vmapi.MilliCPU
}

VCPUChange is used to notify runner that it had some changes in its CPUs runner uses this info to adjust qemu cgroup

type VersionRange ¶ added in v0.1.4

type VersionRange[V constraints.Ordered] struct {
	Min V `json:"min"`
	Max V `json:"max"`
}

VersionRange is a helper type to represent a range of versions.

The bounds are inclusive, representing all versions v with Min <= v <= Max.

This type is sent directly to the monitor during the creation of a new Dispatcher as part of figuring out which protocol to use.

func (r VersionRange[V]) LatestSharedVersion(cmp VersionRange[V]) (_ V, ok bool)

func (r VersionRange[V]) String() string

type VmConfig ¶ added in v0.28.0

type VmConfig struct {
	// AutoMigrationEnabled indicates to the scheduler plugin that it's allowed to trigger migration
	// for this VM. This defaults to false because otherwise we might disrupt VMs that don't have
	// adequate networking support to preserve connections across live migration.
	AutoMigrationEnabled bool `json:"autoMigrationEnabled"`
	// AlwaysMigrate is a test-only debugging flag that, if present in the VM's labels, will always
	// prompt it to migrate, regardless of whether the VM actually *needs* to.
	AlwaysMigrate  bool           `json:"alwaysMigrate"`
	ScalingEnabled bool           `json:"scalingEnabled"`
	ScalingConfig  *ScalingConfig `json:"scalingConfig,omitempty"`
}

VmConfig stores the autoscaling-specific "extra" configuration derived from labels and annotations on the VM object.

This is separate from the bounds information stored in VmInfo (even though that's also derived from annotations), because VmConfig is meant to store values that either qualitatively change the handling for a VM (e.g., AutoMigrationEnabled) or are expected to largely be the same for most VMs (e.g., ScalingConfig).

type VmCpuInfo ¶

type VmCpuInfo struct {
	Min vmapi.MilliCPU `json:"min"`
	Max vmapi.MilliCPU `json:"max"`
	Use vmapi.MilliCPU `json:"use"`
}

func NewVmCpuInfo(cpus vmapi.CPUs) (*VmCpuInfo, error)

type VmInfo ¶

type VmInfo struct {
	Name      string    `json:"name"`
	Namespace string    `json:"namespace"`
	Cpu       VmCpuInfo `json:"cpu"`
	Mem       VmMemInfo `json:"mem"`
	Config    VmConfig  `json:"config"`
}

VmInfo is the subset of vmapi.VirtualMachineSpec that the scheduler plugin and autoscaler agent care about. It takes various labels and annotations into account, so certain fields might be different from what's strictly in the VirtualMachine object.

func ExtractVmInfo(logger *zap.Logger, vm *vmapi.VirtualMachine) (*VmInfo, error)

func ExtractVmInfoFromPod(logger *zap.Logger, pod *corev1.Pod) (*VmInfo, error)

func (vm VmInfo) EqualScalingBounds(cmp VmInfo) bool

func (vm VmInfo) Max() Resources

func (vm VmInfo) Min() Resources

func (vm VmInfo) NamespacedName() util.NamespacedName

func (vm *VmInfo) SetUsing(r Resources)

func (vm VmInfo) Using() Resources

type VmMemInfo ¶

type VmMemInfo struct {
	// Min is the minimum number of memory slots available
	Min uint16 `json:"min"`
	// Max is the maximum number of memory slots available
	Max uint16 `json:"max"`
	// Use is the number of memory slots currently plugged in the VM
	Use uint16 `json:"use"`

	SlotSize Bytes `json:"slotSize"`
}

func NewVmMemInfo(memSlots vmapi.MemorySlots, memSlotSize resource.Quantity) (*VmMemInfo, error)