api

package
v0.23.1 Latest Latest
Warning

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

 Go to latest Published: Jan 25, 2024 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	LabelTestingOnlyAlwaysMigrate = "autoscaling.neon.tech/testing-only-always-migrate"
	LabelEnableAutoscaling        = "autoscaling.neon.tech/enabled"
	AnnotationAutoscalingBounds   = "autoscaling.neon.tech/bounds"
	AnnotationAutoscalingConfig   = "autoscaling.neon.tech/config"
	AnnotationBillingEndpointID   = "autoscaling.neon.tech/billing-endpoint-id"
)
View Source 
const (
	// MonitorProtoV1_0 represents v1.0 of the agent<->monitor protocol - the initial version.
	//
	// Currently the latest version.
	MonitorProtoV1_0 = iota + 1
)

Variables

This section is empty.

Functions

func HasAlwaysMigrateLabel added in v0.6.0 

func HasAlwaysMigrateLabel(obj metav1.ObjectMetaAccessor) bool

func HasAutoscalingEnabled added in v0.6.0 

func HasAutoscalingEnabled(obj metav1.ObjectMetaAccessor) bool

HasAutoscalingEnabled returns true iff the object has the label that enables autoscaling

func SerializeMonitorMessage added in v0.18.0 

func SerializeMonitorMessage(content any, id uint64) ([]byte, error)

This function is used to prepare a message for serialization. Any data passed to the monitor should be serialized with this function. As of protocol v1.0, the following types maybe be sent to the monitor, and thus passed in: - DownscaleRequest - UpscaleNotification - InvalidMessage - InternalError - HealthCheck

Types

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 (AgentRequest) ProtocolRange added in v0.1.8 

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

ProtocolRange returns a VersionRange exactly equal to r.ProtoVersion

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 added in v0.23.0 

func BytesFromResourceQuantity(r resource.Quantity) Bytes

BytesFromResourceQuantity converts resource.Quantity into Bytes

func (Bytes) AsFloat64 added in v0.23.0 

func (b Bytes) AsFloat64() float64

AsFloat64 converts a Bytes into float64 of the same amount

func (Bytes) Format added in v0.23.0 

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

func (Bytes) MarshalJSON added in v0.23.0 

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

func (Bytes) ToResourceQuantity added in v0.23.0 

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

ToResourceQuantity converts a Bytes to resource.Quantity - typically used for formatting and/or serialization

func (*Bytes) UnmarshalJSON added in v0.23.0 

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"`
	LoadAverage5Min  float32 `json:"loadAvg5M"`
	MemoryUsageBytes float32 `json:"memoryUsageBytes"`
}

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

func ReadMetrics 

func ReadMetrics(nodeExporterOutput []byte, loadPrefix string) (m Metrics, err error)

ReadMetrics generates Metrics from node_exporter output, or returns error on failure

This function could be more efficient, but realistically it doesn't matter. The size of the output from node_exporter/vector is so small anyways.

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 (MonitorProtoVersion) String added in v0.15.0 

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 (MoreResources) And added in v0.1.4 

func (m MoreResources) And(cmp MoreResources) MoreResources

And returns the field-wise logical "and" of m and cmp

func (MoreResources) Not added in v0.1.4 

func (m MoreResources) Not() MoreResources

Not returns the field-wise logical "not" of m

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
	//
	// Currently the latest version.
	PluginProtoV4_0
)

func (PluginProtoVersion) AgentSendsComputeUnit added in v0.23.0 

func (v PluginProtoVersion) AgentSendsComputeUnit() bool

AgentSendsComputeUnit returns whether this version of the protocol expects the autoscaler-agent to send the value of its configured Compute Unit in its AgentRequest.

This is true for version v4.0 and greater.

func (PluginProtoVersion) AllowsNilMetrics added in v0.1.9 

func (v PluginProtoVersion) AllowsNilMetrics() bool

AllowsNilMetrics returns whether this version of the protocol allows the autoscaler-agent to send a nil metrics field.

This is true for version v1.1 and greater.

func (PluginProtoVersion) IsValid added in v0.1.8 

func (v PluginProtoVersion) IsValid() bool

IsValid returns whether the protocol version is valid. The zero value is not valid.

func (PluginProtoVersion) PluginSendsComputeUnit added in v0.22.0 

func (v PluginProtoVersion) PluginSendsComputeUnit() bool

PluginSendsComputeUnit returns whether this version of the protocol expects the scheduler plugin to send the value of the Compute Unit in its PluginResponse.

This is true for all versions below v3.0.

func (PluginProtoVersion) RepresentsMemoryAsBytes added in v0.23.0 

func (v PluginProtoVersion) RepresentsMemoryAsBytes() bool

RepresentsMemoryAsBytes returns whether this version of the protocol uses byte quantities to refer to memory amounts, rather than a number of memory slots.

This is true for version v4.0 and greater.

func (PluginProtoVersion) String added in v0.1.8 

func (v PluginProtoVersion) String() string

func (PluginProtoVersion) SupportsFractionalCPU added in v0.7.0 

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"`

	// ComputeUnit is the minimum unit of resources that the scheduler is expecting to work with
	//
	// For example, if ComputeUnit is Resources{ VCPU: 2, Mem: 4Gi }, then all VMs are expected to
	// have allocated vCPUs that are a multiple of two, with 2 GiB of memory per vCPU.
	//
	// This value may be different across nodes, and the scheduler expects that all AgentRequests
	// will abide by the most recent ComputeUnit they've received.
	//
	// THIS FIELD IS DEPRECATED: See https://github.com/neondatabase/autoscaling/issues/706
	ComputeUnit *Resources `json:"resourceUnit,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 (Resources) AbsDiff added in v0.12.0 

func (r Resources) AbsDiff(cmp Resources) Resources

AbsDiff returns a new Resources with each field F as the absolute value of the difference between r.F and cmp.F

func (Resources) Add added in v0.22.0 

func (r Resources) Add(other Resources) Resources

Add returns the result of adding the two Resources

func (Resources) CheckValuesAreReasonablySized added in v0.7.0 

func (r Resources) CheckValuesAreReasonablySized() error

func (Resources) ConvertToAllocation added in v0.18.0 

func (r Resources) ConvertToAllocation() Allocation

ConvertToRaw produces the Allocation equivalent to these Resources

func (Resources) HasFieldGreaterThan 

func (r Resources) HasFieldGreaterThan(cmp Resources) bool

HasFieldGreaterThan returns true if and only if there is a field F where r.F > cmp.F

func (Resources) HasFieldLessThan 

func (r Resources) HasFieldLessThan(cmp Resources) bool

HasFieldGreaterThan returns true if and only if there is a field F where r.F < cmp.F

func (Resources) IncreaseFrom added in v0.1.4 

func (r Resources) IncreaseFrom(old Resources) MoreResources

Increase returns a MoreResources with each field F true when r.F > old.F.

func (Resources) MarshalLogObject added in v0.10.0 

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

MarshalLogObject implements zapcore.ObjectMarshaler, so that Resources can be used with zap.Object

func (Resources) Max 

func (r Resources) Max(cmp Resources) Resources

Max returns a new Resources value with each field F as the maximum of r.F and cmp.F

func (Resources) Min 

func (r Resources) Min(cmp Resources) Resources

Min returns a new Resources value with each field F as the minimum of r.F and cmp.F

func (Resources) Mul 

func (r Resources) Mul(factor uint16) Resources

Mul returns the result of multiplying each resource by factor

func (Resources) SaturatingSub added in v0.22.0 

func (r Resources) SaturatingSub(other Resources) Resources

SaturatingSub returns the result of subtracting r - other, with values that *would* underflow instead set to zero.

func (Resources) ValidateNonZero 

func (r Resources) ValidateNonZero() error

ValidateNonZero checks that neither of the Resources fields are equal to zero, returning an error if either is.

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 (RunnerProtoVersion) SupportsCgroupFractionalCPU added in v0.7.0 

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 (ScalingBounds) Validate added in v0.7.0 

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

Validate checks that the ScalingBounds are all reasonable values - all fields initialized and non-zero.

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 (*ScalingConfig) Validate added in v0.7.0 

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 (VersionRange[V]) LatestSharedVersion added in v0.1.4 

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

LatestSharedVersion returns the latest version covered by both VersionRanges, if there is one.

If either range is invalid, or no such version exists (i.e. the ranges are disjoint), then the returned values will be (0, false).

func (VersionRange[V]) String added in v0.1.4 

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

type VmCpuInfo 

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

func (VmCpuInfo) Format added in v0.6.0 

func (cpu VmCpuInfo) Format(state fmt.State, verb rune)

type VmInfo 

type VmInfo struct {
	Name           string         `json:"name"`
	Namespace      string         `json:"namespace"`
	Cpu            VmCpuInfo      `json:"cpu"`
	Mem            VmMemInfo      `json:"mem"`
	ScalingConfig  *ScalingConfig `json:"scalingConfig,omitempty"`
	AlwaysMigrate  bool           `json:"alwaysMigrate"`
	ScalingEnabled bool           `json:"scalingEnabled"`
}

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 

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

func (VmInfo) EqualScalingBounds added in v0.6.0 

func (vm VmInfo) EqualScalingBounds(cmp VmInfo) bool

func (VmInfo) Format added in v0.6.0 

func (vm VmInfo) Format(state fmt.State, verb rune)

the reason we have custom formatting for VmInfo is because without it, the formatting of memory slot size (which is a resource.Quantity) has all the fields, meaning (a) it's hard to read, and (b) there's a lot of unnecessary information. But in order to enable "proper" formatting given a VmInfo, we have to implement Format from the top down, so we do.

func (VmInfo) Max 

func (vm VmInfo) Max() Resources

Max returns the Resources representing the maximum amount this VmInfo says the VM may reserve

func (VmInfo) Min 

func (vm VmInfo) Min() Resources

Min returns the Resources representing the minimum amount this VmInfo says the VM must reserve

func (VmInfo) NamespacedName added in v0.6.0 

func (vm VmInfo) NamespacedName() util.NamespacedName

func (*VmInfo) SetUsing 

func (vm *VmInfo) SetUsing(r Resources)

SetUsing sets the values of vm.{Cpu,Mem}.Use to those provided by r

func (VmInfo) Using 

func (vm VmInfo) Using() Resources

Using returns the Resources that this VmInfo says the VM is using

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 (VmMemInfo) Format added in v0.6.0 

func (mem VmMemInfo) Format(state fmt.State, verb rune)

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.