Documentation ¶
Index ¶
- Constants
- func HasAlwaysMigrateLabel(obj metav1.ObjectMetaAccessor) bool
- func HasAutoscalingEnabled(obj metav1.ObjectMetaAccessor) bool
- func SerializeMonitorMessage(content any, id uint64) ([]byte, error)
- type AgentRequest
- type Allocation
- type DownscaleRequest
- type DownscaleResult
- type HealthCheck
- type InternalError
- type InvalidMessage
- type Metrics
- type MigrateResponse
- type MonitorProtoVersion
- type MonitorProtocolResponse
- type MoreResources
- type PluginProtoVersion
- type PluginResponse
- type ResourceBounds
- type Resources
- func (r Resources) AbsDiff(cmp Resources) Resources
- func (r Resources) CheckValuesAreReasonablySized() error
- func (r Resources) ConvertToAllocation(memSlotSize *resource.Quantity) 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) ValidateNonZero() error
- type RunnerProtoVersion
- type ScalingBounds
- type ScalingConfig
- type UpscaleConfirmation
- type UpscaleNotification
- type UpscaleRequest
- type VCPUCgroup
- type VCPUChange
- type VersionRange
- type VmCpuInfo
- type VmInfo
- type VmMemInfo
Constants ¶
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" )
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
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"` // 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 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 ¶
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 ¶
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 PluginProtoV2_0 // PluginProtoV2_1 represents v2.1 of the agent<->scheduler plugin protocol. // // Changes from v2.0: // // * added AgentRequest.LastPermit // // Currently the latest version. PluginProtoV2_1 )
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) 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: 4 }, then all VMs are expected to // have allocated vCPUs that are a multiple of two, with twice as many memory slots. // // This value may be different across nodes, and the scheduler expects that all AgentRequests // will abide by the most recent ComputeUnit they've received. ComputeUnit Resources `json:"resourceUnit"` }
type ResourceBounds ¶ added in v0.7.0
type Resources ¶
type Resources struct { VCPU vmapi.MilliCPU `json:"vCPUs"` // Mem gives the number of slots of memory (typically 1G ea.) requested. The slot size is set by // the value of the VM's VirtualMachineSpec.Guest.MemorySlotSize. Mem uint16 `json:"mem"` }
Resources represents an amount of CPU and memory (via memory slots)
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
AbsDiff returns a new Resources with each field F as the absolute value of the difference between r.F and cmp.F
func (Resources) CheckValuesAreReasonablySized ¶ added in v0.7.0
func (Resources) ConvertToAllocation ¶ added in v0.18.0
func (r Resources) ConvertToAllocation(memSlotSize *resource.Quantity) Allocation
ConvertToRaw produces the Allocation equivalent to these Resources with the given slot size
func (Resources) HasFieldGreaterThan ¶
HasFieldGreaterThan returns true if and only if there is a field F where r.F > cmp.F
func (Resources) HasFieldLessThan ¶
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 ¶
Max returns a new Resources value with each field F as the maximum of r.F and cmp.F
func (Resources) Min ¶
Min returns a new Resources value with each field F as the minimum of r.F and cmp.F
func (Resources) ValidateNonZero ¶
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.
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
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
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 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 (VmInfo) EqualScalingBounds ¶ added in v0.6.0
func (VmInfo) Format ¶ added in v0.6.0
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 ¶
Max returns the Resources representing the maximum amount this VmInfo says the VM may reserve
func (VmInfo) Min ¶
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