api

package
v0.29.0 Latest Latest
Warning

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

 Go to latest Published: May 10, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	LabelEnableAutoMigration      = "autoscaling.neon.tech/auto-migration-enabled"
	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 HasAutoMigrationEnabled added in v0.28.0 

func HasAutoMigrationEnabled(obj metav1.ObjectMetaAccessor) bool

HasAutoMigrationEnabled returns true iff the object has the label that enables "automatic" scheduler-triggered migration, and it's set to "true"

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"`
	// 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 (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
	//
	// 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 (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) IncludesExtendedMetrics added in v0.28.0 

func (v PluginProtoVersion) IncludesExtendedMetrics() bool

IncludesExtendedMetrics returns whether this version of the protocol includes the AgentRequest's metrics loadAvg5M and memoryUsageBytes.

This is true for all versions below v5.0.

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

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

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 

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

func ExtractVmInfoFromPod added in v0.27.0 

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

func (VmInfo) EqualScalingBounds added in v0.6.0 

func (vm VmInfo) EqualScalingBounds(cmp VmInfo) bool

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

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

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.