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 ¶
- Variables
- func Ping(ctx context.Context, host string, count int) (types.PingStats, error)
- type Agent
- func (a *Agent) Desired() *types.NodeState
- func (a *Agent) Handler(token string) http.Handler
- func (a *Agent) Kick()
- func (a *Agent) Reconcile(ctx context.Context)
- func (a *Agent) Run(ctx context.Context)
- func (a *Agent) Serve(ctx context.Context, addr, token string)
- func (a *Agent) Status() *types.NodeStatus
- type Config
- type ControlPlane
- type Mesh
- type Proxy
- type Remote
- type Resolver
- type Runtime
- type Updater
Constants ¶
This section is empty.
Variables ¶
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.
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.
var ErrRemoved = errors.New("this node was removed from the cluster")
ErrRemoved means the control node no longer knows this node.
Functions ¶
Types ¶
type Agent ¶
type Agent struct {
Config
// contains filtered or unexported fields
}
func (*Agent) 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) Serve ¶
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.
type Resolver ¶
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.