informant

Documentation

Index

• Constants
• type Agent
  • func (a *Agent) CheckID(timeout time.Duration) error
  • func (a *Agent) EnsureUnregistered() (wasCurrent bool)
  • func (a *Agent) Resume(timeout time.Duration) error
  • func (a *Agent) SpawnRequestUpscale(timeout time.Duration, handleError func(error))
  • func (a *Agent) Suspend(timeout time.Duration, handleError func(error))
• type AgentSet
  • func NewAgentSet() *AgentSet
  • func (s *AgentSet) Get(id uuid.UUID) (_ *Agent, ok bool)
  • func (s *AgentSet) ReceivedUpscale()
  • func (s *AgentSet) RegisterNewAgent(info *api.AgentDesc) (api.InformantProtoVersion, int, error)
  • func (s *AgentSet) RequestUpscale()
• type CgroupConfig
• type CgroupManager
  • func NewCgroupManager(groupName string) (*CgroupManager, error)
  • func (c *CgroupManager) CurrentMemoryUsage() (uint64, error)
  • func (c *CgroupManager) FetchState() (cgroup2.State, error)
  • func (c *CgroupManager) Freeze() error
  • func (c *CgroupManager) SetHighMem(bytes uint64) error
  • func (c *CgroupManager) Thaw() error
• type CgroupState
  • func (s *CgroupState) ReceivedUpscale()
• type NewStateOpts
  • func WithCgroup(cgm *CgroupManager, config CgroupConfig) NewStateOpts
• type State
  • func NewState(agents *AgentSet, opts ...NewStateOpts) (*State, error)
  • func (s *State) NotifyUpscale(newResources *api.RawResources) (*struct{}, int, error)
  • func (s *State) RegisterAgent(info *api.AgentDesc) (*api.InformantDesc, int, error)
  • func (s *State) TryDownscale(target *api.RawResources) (*api.DownscaleResult, int, error)
  • func (s *State) UnregisterAgent(info *api.AgentDesc) (*api.UnregisterAgent, int, error)

Constants

const (
	PrometheusPort uint16 = 9100

	CheckDeadlockDelay   time.Duration = 1 * time.Second
	CheckDeadlockTimeout time.Duration = 250 * time.Millisecond

	AgentBackgroundCheckDelay   time.Duration = 10 * time.Second
	AgentBackgroundCheckTimeout time.Duration = 250 * time.Millisecond

	AgentResumeTimeout  time.Duration = 100 * time.Millisecond
	AgentSuspendTimeout time.Duration = 200 * time.Millisecond
	AgentUpscaleTimeout time.Duration = 400 * time.Millisecond // does not include waiting for /upscale response
)

const ProtocolVersion api.InformantProtoVersion = api.InformantProtoV1_1

ProtocolVersion is the current version of the agent<->informant protocol in use by this informant

Currently, each VM informant supports only one version at a time. In the future, this may change.

Types

type Agent

type Agent struct {
	// contains filtered or unexported fields
}

func (*Agent) CheckID

func (a *Agent) CheckID(timeout time.Duration) error

CheckID checks that the Agent's ID matches what's expected

If the agent has already been registered, then a failure in this method will unregister the agent.

If the Agent is unregistered before the call to CheckID() completes, the request will be cancelled and this method will return context.Canceled.

func (*Agent) EnsureUnregistered

func (a *Agent) EnsureUnregistered() (wasCurrent bool)

EnsureUnregistered unregisters the Agent if it is currently registered, signalling the AgentSet to use a new Agent if it isn't already

Returns whether the agent was the current Agent in use.

func (*Agent) Resume

func (a *Agent) Resume(timeout time.Duration) error

Resume attempts to restore the Agent as the current one in use, sending a request to its /resume endpoint

If the Agent is unregistered before the call to Resume() completes, the request will be cancelled and this method will return context.Canceled.

If the request fails, the Agent will be unregistered.

func (*Agent) SpawnRequestUpscale

func (a *Agent) SpawnRequestUpscale(timeout time.Duration, handleError func(error))

SpawnRequestUpscale requests that the Agent increase the resource allocation to this VM

This method blocks until the request is picked up by the message queue, and returns without waiting for the request to complete (it'll do that on its own).

The timeout applies only once the request is in-flight.

This method MUST NOT be called while holding a.parent.lock; if that happens, it may deadlock.

func (*Agent) Suspend

func (a *Agent) Suspend(timeout time.Duration, handleError func(error))

Suspend signals to the Agent that it is not *currently* in use, sending a request to its /suspend endpoint

If the Agent is unregistered before the call to Suspend() completes, the request will be cancelled and this method will return context.Canceled.

If the request fails, the Agent will be unregistered.

type AgentSet

type AgentSet struct {
	// contains filtered or unexported fields
}

AgentSet is the global state handling various autoscaler-agents that we could connect to

func NewAgentSet

func NewAgentSet() *AgentSet

NewAgentSet creates a new AgentSet and starts the necessary background tasks

On completion, the background tasks should be ended with the Stop method.

func (*AgentSet) Get

func (s *AgentSet) Get(id uuid.UUID) (_ *Agent, ok bool)

Get returns the requested Agent, if it exists

func (*AgentSet) ReceivedUpscale

func (s *AgentSet) ReceivedUpscale()

ReceivedUpscale marks any desired upscaling from a prior s.RequestUpscale() as resolved

Typically, (*CgroupState).ReceivedUpscale() is also called alongside this method.

func (*AgentSet) RegisterNewAgent

func (s *AgentSet) RegisterNewAgent(info *api.AgentDesc) (api.InformantProtoVersion, int, error)

RegisterNewAgent instantiates our local information about the autsocaler-agent

Returns: protocol version, status code, error (if unsuccessful)

func (*AgentSet) RequestUpscale

func (s *AgentSet) RequestUpscale()

RequestUpscale requests an immediate upscale for more memory, if there's an agent currently enabled

If there's no current agent, then RequestUpscale marks the upscale as desired, and will request upscaling from the next agent we connect to.

type CgroupConfig

type CgroupConfig struct {
	// OOMBufferBytes gives the amount of memory, in bytes, below system memory that the cgroup's
	// memory.high should be set to.
	//
	// In other words, memory.high + OOMBufferBytes will equal total system memory.
	OOMBufferBytes uint64

	// SysBufferBytes gives the estimated amount of memory, in bytes, that the kernel uses before
	// handing out the rest to userspace. This value is the estimated difference between the
	// *actual* physical memory and the amount reported by `grep MemTotal /proc/meminfo`.
	//
	// For more information, refer to `man 5 proc`, which defines MemTotal as "Total usable RAM
	// (i.e., physical RAM minus a few reserved bits and the kernel binary code)".
	//
	// We only use SysBufferBytes when calculating the system memory from the *external* memory
	// size, rather than the self-reported memory size, according to the kernel.
	//
	// TODO: this field is only necessary while we still have to trust the autoscaler-agent's
	// upscale resource amounts (because we might not *actually* have been upscaled yet). This field
	// should be removed once we have a better solution there.
	SysBufferBytes uint64

	// MemoryHighBufferBytes gives the amount of memory, in bytes, below a proposed new value for
	// memory.high that the cgroup's memory usage must be for us to downscale
	//
	// In other words, we can downscale only when:
	//
	//   memory.current + MemoryHighBufferBytes < (proposed) memory.high
	//
	// TODO: there's some minor issues with this approach -- in particular, that we might have
	// memory in use by the kernel's page cache that we're actually ok with getting rid of.
	MemoryHighBufferBytes uint64

	// MaxUpscaleWaitMillis gives the maximum duration, in milliseconds, that we're allowed to pause
	// the cgroup for while waiting for the autoscaler-agent to upscale us
	MaxUpscaleWaitMillis uint
}

CgroupConfig provides some configuration options for State cgroup handling

var (
	// DefaultCgroupConfig is the default CgroupConfig used for cgroup interaction logic
	DefaultCgroupConfig CgroupConfig = CgroupConfig{
		OOMBufferBytes:        200 * (1 << 20),
		SysBufferBytes:        100 * (1 << 20),
		MemoryHighBufferBytes: 100 * (1 << 20),
		MaxUpscaleWaitMillis:  20,
	}
)

type CgroupManager

type CgroupManager struct {
	MemoryHighEvent util.CondChannelReceiver
	ErrCh           <-chan error
	// contains filtered or unexported fields
}

func NewCgroupManager

func NewCgroupManager(groupName string) (*CgroupManager, error)

func (*CgroupManager) CurrentMemoryUsage

func (c *CgroupManager) CurrentMemoryUsage() (uint64, error)

CurrentMemoryUsage returns the value at memory.current -- the cgroup's current memory usage.

func (*CgroupManager) FetchState

func (c *CgroupManager) FetchState() (cgroup2.State, error)

FetchState returns a cgroup2.State indicating whether the cgroup is currently frozen

func (*CgroupManager) Freeze

func (c *CgroupManager) Freeze() error

func (*CgroupManager) SetHighMem

func (c *CgroupManager) SetHighMem(bytes uint64) error

SetMemLimit sets the memory.high limit of the cgroup, clearing

func (*CgroupManager) Thaw

func (c *CgroupManager) Thaw() error

type CgroupState

type CgroupState struct {
	// contains filtered or unexported fields
}

CgroupState provides the high-level cgroup handling logic, building upon the low-level plumbing provided by CgroupManager.

func (*CgroupState) ReceivedUpscale

func (s *CgroupState) ReceivedUpscale()

ReceivedUpscale notifies s.upscaleEventsRecvr

Typically, (*AgentSet).ReceivedUpscale() is also called alongside this method.

type NewStateOpts

type NewStateOpts struct {
	// contains filtered or unexported fields
}

NewStateOpts are individual options provided to NewState

func WithCgroup

func WithCgroup(cgm *CgroupManager, config CgroupConfig) NewStateOpts

WithCgroup creates a NewStateOpts that sets its CgroupHandler

This function will panic if the provided CgroupConfig is invalid.

type State

type State struct {
	// contains filtered or unexported fields
}

State is the global state of the informant

func NewState

func NewState(agents *AgentSet, opts ...NewStateOpts) (*State, error)

NewState instantiates a new State object, starting whatever background processes might be required

Optional configuration may be provided by NewStateOpts.

When WithCgroup is provided, the State object will handle "memory high" events for the cgroup, and

func (*State) NotifyUpscale

func (s *State) NotifyUpscale(newResources *api.RawResources) (*struct{}, int, error)

NotifyUpscale signals that the VM's resource usage has been increased to the new amount

Returns: body (if successful), status code and error (if unsuccessful)

func (*State) RegisterAgent

func (s *State) RegisterAgent(info *api.AgentDesc) (*api.InformantDesc, int, error)

RegisterAgent registers a new or updated autoscaler-agent

Returns: body (if successful), status code, error (if unsuccessful)

func (*State) TryDownscale

func (s *State) TryDownscale(target *api.RawResources) (*api.DownscaleResult, int, error)

TryDownscale tries to downscale the VM's current resource usage, returning whether the proposed amount is ok

Returns: body (if successful), status code and error (if unsuccessful)

func (*State) UnregisterAgent

func (s *State) UnregisterAgent(info *api.AgentDesc) (*api.UnregisterAgent, int, error)

UnregisterAgent unregisters the autoscaler-agent given by info, if it is currently registered

If a different autoscaler-agent is currently registered, this method will do nothing.

Returns: body (if successful), status code and error (if unsuccessful)