agent

package
v0.8.22 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package agent runs on every node, the control node included. It makes the node match the desired state the control node computes for it: it boots the instances it should hold, health-checks them, restarts crashes per the app's restart policy, stops and removes what it should no longer hold, keeps the WireGuard mesh and the proxy's routes current, and reports what it observes.

The desired state is cached on disk, so a node keeps running (and serving traffic for) its last known state while the control node is unreachable. Every pass compares the desired state with the VMs actually running and fixes the difference, so crashes, restarts and reboots converge the same way.

Index

Constants

This section is empty.

Variables

View Source
var (
	FenceAfter      = 2 * time.Minute
	FenceCheckEvery = 5 * time.Second
)

The timings are variables so tests can shorten them. FenceAfter must stay well under cluster.FailoverAfter, and well over cluster.PollTimeout: an idle node only hears from the control node when a long poll returns.

View Source
var DNSWait = 30 * time.Second

DNSWait is how long instances wait for this node's DNS service before starting without it. At boot it answers a moment after the agent sets up the bridge it listens on. A variable so tests can shorten it.

View Source
var ErrRemoved = errors.New("this node was removed from the cluster")

ErrRemoved means the control node no longer knows this node.

Functions

func Ping added in v0.8.19

func Ping(ctx context.Context, host string, count int) (types.PingStats, error)

Ping sends count ICMP echoes to host, pingEvery apart, and waits up to a second for the last answers. It uses an unprivileged ICMP socket where the system allows one, and a raw one (root) where it doesn't.

Types

type Agent

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

func New

func New(c Config) *Agent

func (*Agent) Desired

func (a *Agent) Desired() *types.NodeState

Desired is the state the agent is applying, or nil before the first one.

func (*Agent) Handler

func (a *Agent) Handler(token string) http.Handler

Handler is the agent's API. It serves the control node, which presents token: this node's app logs, sessions with its VMs (jokku enter, volume copies), volume backups and network tests. It also serves volume disks to the node taking one over, which presents that move's token, and takes in other nodes' network test traffic. With no token, only the latter two.

func (*Agent) Kick

func (a *Agent) Kick()

Kick asks for a reconcile pass soon.

func (*Agent) Reconcile

func (a *Agent) Reconcile(ctx context.Context)

Reconcile runs one pass.

func (*Agent) Run

func (a *Agent) Run(ctx context.Context)

Run starts the agent and blocks until ctx is done.

func (*Agent) Serve

func (a *Agent) Serve(ctx context.Context, addr, token string)

Serve runs the agent's API on addr (this node's mesh address) until ctx is done. The firewall keeps VMs away from the port as well.

func (*Agent) Status

func (a *Agent) Status() *types.NodeStatus

Status is the report sent to the control node.

type Config

type Config struct {
	Control  ControlPlane
	Runtime  Runtime
	Mesh     Mesh     // nil: no mesh
	Proxy    Proxy    // nil: no proxy
	Resolver Resolver // nil: VMs use the host's resolvers
	DataDir  string
	DNS      []string // resolvers handed to guests
	Version  string
	Log      *slog.Logger
	// GCArtifacts deletes root filesystems no instance here uses. Off on
	// the control node, which keeps recent releases for rollbacks.
	GCArtifacts bool
	// Updater updates jokku here when the control node says to; nil on the
	// control node, which "jokku update" updates.
	Updater Updater
	// Latency is how long the requests this node's proxy handled took, for
	// the control node (GET /v1/latency); nil serves none.
	Latency *latency.Recorder
	// Seed is the state to start from before the control node has been
	// heard, when none is cached: an edge reaches the control node only over
	// the mesh, so it needs its first peer before its first poll.
	Seed *types.NodeState
	// Local is set on the control node, whose Control runs in the same
	// process: it can't be cut off from it, so it never fences.
	Local bool
	// Metrics measures the host; nil reads /proc.
	Metrics func() types.NodeMetrics
	// Ping measures round trips to a host for network tests; nil sends
	// ICMP echoes (Ping).
	Ping func(ctx context.Context, host string, count int) (types.PingStats, error)
	// ReconcileEvery and ReportEvery default to 2s and 5s.
	ReconcileEvery, ReportEvery time.Duration
	// UpFor is how long an instance checked by staying up (no port) must
	// run to count as healthy; default 5s.
	UpFor time.Duration
}

type ControlPlane

type ControlPlane interface {
	// State long-polls for this node's desired state, returning once it
	// differs from etag (or after a timeout).
	State(ctx context.Context, etag string) (*types.NodeState, error)
	Report(ctx context.Context, st *types.NodeStatus) error
	// Artifact downloads a root filesystem image.
	Artifact(ctx context.Context, name string, w io.Writer) error
}

ControlPlane is how an agent reaches the control node: in-process on the control node, HTTPS everywhere else.

type Mesh

type Mesh interface {
	Sync(ctx context.Context, self types.NodeIdentity, peers []types.Peer, access *types.EdgeAccess) error
}

Mesh keeps the WireGuard mesh matching the peer list, with what edges may reach on this node.

type Proxy

type Proxy interface {
	Apply(ctx context.Context, ps *types.ProxyState) error
}

Proxy loads routes into this node's proxy.

type Remote

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

Remote is the control plane as seen from a worker: the control node's API over HTTPS, with its TLS key pinned and this node's token.

func NewRemote

func NewRemote(base, token string, tlsConfig *tls.Config) *Remote

func (*Remote) Artifact

func (r *Remote) Artifact(ctx context.Context, name string, w io.Writer) error

func (*Remote) Report

func (r *Remote) Report(ctx context.Context, st *types.NodeStatus) error

func (*Remote) State

func (r *Remote) State(ctx context.Context, etag string) (*types.NodeState, error)

type Resolver

type Resolver interface {
	Apply(ctx context.Context, z dns.Zone) error
	Ready(addr string) bool
}

Resolver hands the cluster's internal names to this node's DNS service, and says whether it answers at addr, the node's bridge address.

type Runtime

type Runtime interface {
	Available() error
	EnsureNetwork(ctx context.Context) error
	Start(ctx context.Context, s vm.Spec) error
	Stop(ctx context.Context, id string, grace time.Duration) error
	Remove(ctx context.Context, id string) error
	Units(ctx context.Context) (map[string]string, error)
	Usage(ctx context.Context, ids []string) (map[string]vm.Usage, error)
	CheckTCP(addr string) bool

	// Volume disks: create an empty one, grow one that no VM has attached,
	// and list those attached to running VMs.
	CreateVolume(ctx context.Context, path string, sizeMB int) error
	GrowVolume(ctx context.Context, path string, sizeMB int) error
	Attached(ctx context.Context) (map[string]bool, error)

	// Session connects to a running VM's guest agent, returning the token
	// it expects.
	Session(ctx context.Context, id string) (io.ReadWriteCloser, string, error)
}

Runtime runs microVMs: vm.Host in production, a fake in tests.

type Updater

type Updater interface {
	// Start begins the update in the background.
	Start(ctx context.Context, version string) error
	// Running reports whether an update is under way.
	Running(ctx context.Context) bool
}

Updater updates jokku on this node to another release.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL