api

package
v0.1.6 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2023 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const LabelTestingOnlyAlwaysMigrate = "autoscaler/testing-only-always-migrate"

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentDesc 

type AgentDesc struct {
	// AgentID is a unique UUID for the current instance of the autoscaler-agent
	//
	// This is helpful so that we can distinguish between (incorrect) duplicate calls to /register
	// and (correct) re-registering of an agent.
	AgentID uuid.UUID `json:"agentID"`

	// ServeAddr gives the unique (per instance)
	ServerAddr string `json:"agentServeAddr"`

	// MinProtoVersion is the minimum version of the agent<->informant protocol that the
	// autoscaler-agent supports
	//
	// Protocol versions are always non-zero.
	//
	// AgentDesc must always have MinProtoVersion <= MaxProtoVersion.
	MinProtoVersion InformantProtoVersion `json:"minProtoVersion"`
	// MaxProtoVersion is the maximum version of the agent<->informant protocol that the
	// autoscaler-agent supports, inclusive.
	//
	// Protocol versions are always non-zero.
	//
	// AgentDesc must always have MinProtoVersion <= MaxProtoVersion.
	MaxProtoVersion InformantProtoVersion `json:"maxProtoVersion"`
}

AgentDesc is the first message sent from an autoscaler-agent to a VM informant, describing some information about the autoscaler-agent

Each time an autoscaler-agent (re)connects to a VM informant, it sends an AgentDesc to the "/register" endpoint.

For more information on the agent<->informant protocol, refer to the top-level ARCHITECTURE.md

func (AgentDesc) ProtocolRange added in v0.1.4 

func (d AgentDesc) ProtocolRange() VersionRange[InformantProtoVersion]

ProtocolRange returns a VersionRange from d.MinProtoVersion to d.MaxProtoVersion.

type AgentIdentification 

type AgentIdentification struct {
	// AgentID is the same AgentID as given in the AgentDesc initially provided to the VM informant
	AgentID uuid.UUID `json:"agentID"`
}

AgentIdentification affirms the AgentID of the autoscaler-agent in its initial response to a VM informant, on the /id endpoint. This response is always wrapped in an AgentMessage. A type alias for this is provided as AgentIdentificationMessage, for convenience.

type AgentIdentificationMessage 

type AgentIdentificationMessage = AgentMessage[AgentIdentification]

type AgentMessage 

type AgentMessage[T any] struct {
	// Data is the content of the request or response
	Data T `json:"data"`

	// SequenceNumber is a unique-per-instance monotonically increasing number passed in each
	// non-initial message from the autoscaler-agent to the VM informant, both requests and
	// responses.
	SequenceNumber uint64 `json:"sequenceNumber"`
}

AgentMessage is used for (almost) every message sent from the autoscaler-agent to the VM informant, and serves to wrap the type T with a SequenceNumber

The SequenceNumber provides a total ordering of states, even if the ordering of HTTP requests and responses are out of order. Fundamentally this is required because we have bidirectional communication between the autoscaler-agent and VM informant — without it, we run the risk of racy behavior, which could *actually* result in data corruption.

type AgentRequest 

type AgentRequest struct {
	// Pod is the namespaced name of the pod making the request
	Pod PodName `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"`
	// Metrics provides information about the VM's current load, so that the scheduler may
	// prioritize which pods to migrate
	Metrics Metrics `json:"metrics"`
}

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

All AgentRequests expect a PluginResponse.

type DownscaleResult 

type DownscaleResult struct {
	Ok     bool
	Status string
}

DownscaleResult is used by the VM informant to return whether it downscaled successfully, and some indication of its status when doing so

type InformantDesc 

type InformantDesc struct {
	// ProtoVersion is the version of the agent<->informant protocol that the VM informant has
	// selected
	//
	// If an autoscaler-agent is successfully registered, a well-behaved VM informant MUST respond
	// with a ProtoVersion within the bounds of the agent's declared minimum and maximum protocol
	// versions. If the VM informant does not use a protocol version within those bounds, then it
	// MUST respond with an error status code.
	ProtoVersion InformantProtoVersion `json:"protoVersion"`

	// MetricsMethod tells the autoscaler-agent how to fetch metrics from the VM
	MetricsMethod InformantMetricsMethod `json:"metricsMethod"`
}

InformantDesc describes the capabilities of a VM informant, in response to an autoscaler-agent's request on the /register endpoint

For more information on the agent<->informant protocol, refer to the top-level ARCHITECTURE.md

type InformantMetricsMethod 

type InformantMetricsMethod struct {
	// Prometheus describes prometheus-format metrics, typically not through the informant itself
	Prometheus *MetricsMethodPrometheus `json:"prometheus,omitempty"`
}

InformantMetricsMethod collects the options for ways the VM informant can report metrics

At least one method *must* be provided in an InformantDesc, and more than one method gives the autoscaler-agent freedom to choose.

We use this type so it's easier to ensure backwards compatibility with previous versions of the VM informant — at least during the rollout of new autoscaler-agent or VM informant versions.

type InformantProtoVersion added in v0.1.4 

type InformantProtoVersion uint32

InformantProtoVersion represents a single version of the agent<->informant protocol

Each version of the agent<->informant 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 VM informant may only support versions above v1.1.

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

const (
	// InformantProtoV1_0 represents v1.0 of the agent<->informant protocol - the initial version.
	//
	// Last used in release version 0.1.2.
	InformantProtoV1_0 InformantProtoVersion = iota + 1 // +1 so we start from 1

	// InformantProtoV1_1 represents v1.1 of the agent<->informant protocol.
	//
	// Changes from v1.0:
	//
	// * Adds /try-upscale endpoint to the autoscaler-agent.
	//
	// Currently the latest version.
	InformantProtoV1_1
)

func (InformantProtoVersion) HasTryUpscale added in v0.1.4 

func (v InformantProtoVersion) HasTryUpscale() bool

HasTryUpscale returns whether this version of the protocol has the /try-upscale endpoint

This is true for version v1.1 and greater.

func (InformantProtoVersion) IsValid added in v0.1.4 

func (v InformantProtoVersion) IsValid() bool

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

func (InformantProtoVersion) String added in v0.1.4 

func (v InformantProtoVersion) String() string

type Metrics 

type Metrics struct {
	LoadAverage1Min float32 `json:"loadAvg1M"`
	LoadAverage5Min float32 `json:"loadAvg5M"`
}

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 MetricsMethodPrometheus 

type MetricsMethodPrometheus struct {
	Port uint16 `json:"port"`
}

MetricsMethodPrometheus describes VM informant's metrics in the prometheus format, made available on a particular port

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 MoreResources 

type MoreResources struct {
	// Cpu is true if the VM informant is requesting more CPU
	Cpu bool `json:"cpu"`
	// Memory is true if the VM informant 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 MoreResourcesRequest added in v0.1.4 

type MoreResourcesRequest struct {
	MoreResources

	// ExpectedID is the expected AgentID of the autoscaler-agent
	ExpectedID uuid.UUID `json:"expectedID"`
}

MoreResourcesRequest is the request type wrapping MoreResources that's sent by the VM informant to the autoscaler-agent's /try-upscale endpoint when the VM is urgently in need of more resources.

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 PodName 

type PodName struct {
	Name      string `json:"name"`
	Namespace string `json:"namespace"`
}

PodName represents the namespaced name of a pod

Some analogous types already exist elsewhere (e.g., in the kubernetes API packages), but they don't provide satisfactory JSON marshal/unmarshalling.

func (PodName) String 

func (n PodName) String() string

type RawResources 

type RawResources struct {
	Cpu    *resource.Quantity `json:"cpu"`
	Memory *resource.Quantity `json:"memory"`
}

RawResources signals raw resource amounts, and is primarily used in communications with the VM informant because it doesn't know about things like memory slots

type Resources 

type Resources struct {
	VCPU uint16 `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) ConvertToRaw 

func (r Resources) ConvertToRaw(memSlotSize *resource.Quantity) RawResources

ConvertToRaw produces the RawResources equivalent to these Resources with the given slot size

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) 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) 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 ResumeAgent 

type ResumeAgent struct {
	ExpectedID uuid.UUID `json:"expectedID"`
}

ResumeAgent is sent from the VM informant to the autoscaler-agent to resume contact when it was previously suspended.

type SuspendAgent 

type SuspendAgent struct {
	ExpectedID uuid.UUID `json:"expectedID"`
}

SuspendAgent is sent from the VM informant to the autoscaler-agent when it has been contacted by a new autoscaler-agent and wishes to switch to that instead

Instead of just cutting off any connection(s) to the agent, the informant keeps it around in case the new one fails and it needs to fall back to the old one.

type UnregisterAgent 

type UnregisterAgent struct {
	// WasActive indicates whether the unregistered autoscaler-agent was the one in-use by the VM
	// informant
	WasActive bool `json:"wasActive"`
}

UnregisterAgent is the result of a successful request to a VM informant's /unregister endpoint

type VersionRange added in v0.1.4 

type VersionRange[V constraints.Ordered] struct {
	Min V
	Max V
}

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

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

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 uint16 `json:"min"`
	Max uint16 `json:"max"`
	Use uint16 `json:"use"`
}

type VmInfo 

type VmInfo struct {
	Name          string    `json:"name"`
	Namespace     string    `json:"namespace"`
	Cpu           VmCpuInfo `json:"cpu"`
	Mem           VmMemInfo `json:"mem"`
	AlwaysMigrate bool      `json:"alwaysMigrate"`
}

VmInfo is the subset of vmapi.VirtualMachineSpec that the scheduler plugin and autoscaler agent care about

func ExtractVmInfo 

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

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) 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 uint16 `json:"min"`
	Max uint16 `json:"max"`
	Use uint16 `json:"use"`

	SlotSize resource.Quantity `json:"slotSize"`
}

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.