nodeagent

package
v0.0.0-...-1614f50 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

Package nodeagent is the client side of the node agent: the container that boots Firecracker microVMs for the services configured onto it, holding the KVM device and the network capability the simulator process never holds. The agent's program is cmd/nodeagent, the guest's first process is cmd/guestinit, and the types here are their wire contract.

Index

Constants

View Source
const (
	ControlPort = 5000
	ExitPort    = 5001
)

The vsock ports the guest and the agent talk on: the guest serves its control API on ControlPort; it reports its first process's exit to the agent, which listens on ExitPort.

View Source
const GuestConfigPath = "/etc/sockerless/guest.json"

GuestConfigPath is where guestinit reads its configuration.

View Source
const GuestInitPath = "/sbin/sockerless-init"

GuestInitPath is where the agent places guestinit in the root filesystem.

View Source
const InitProcess = "init"

InitProcess selects the guest's first process where a member name selects a member: in a log read and in an exec. No member may take the name.

View Source
const NoDefaultRoute = "none"

NoDefaultRoute is the DefaultRoute of a guest with no route out of its network.

Variables

View Source
var ErrNotFound = errors.New("the agent knows no such guest")

The client wraps ErrNotFound when the agent knows no guest of the id.

Functions

func EnsureImage

func EnsureImage(ctx context.Context, cli *client.Client) (string, string, error)

EnsureImage builds the agent image for the engine's architecture unless the engine holds it, and returns its name: the sources' digest names it, so a change to the agent rebuilds it and an unchanged one reuses it.

func LogSink

func LogSink() sim.LogSink

LogSink writes the agent's own log into the simulator's output, where a guest's lifecycle reads beside the requests that drove it.

Types

type Agent

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

Agent is a node agent the simulator started as a container: the one container holding /dev/kvm, /dev/net/tun and the network capability inside its own namespace.

func Adopt

func Adopt(ctx context.Context, network string, labels map[string]string, sink sim.LogSink) (*Agent, bool, error)

Adopt takes over a node agent a previous process of this persistent simulator left running, found by its labels, with its API reached on network, and reports false when none runs. It reads the agent's token from the container's environment, where the process that started it put it.

func Start

func Start(ctx context.Context, opts Options, sink sim.LogSink) (*Agent, error)

Start builds the agent image if the engine lacks it, starts the agent and returns once its API answers.

func (*Agent) AddressOn

func (a *Agent) AddressOn(network string) (netip.Addr, bool)

AddressOn is the agent's address on a network it joined.

func (*Agent) Architecture

func (a *Agent) Architecture() string

Architecture is the OCI architecture the agent's guests run on.

func (*Agent) Client

func (a *Agent) Client() *Client

func (*Agent) ContainerID

func (a *Agent) ContainerID() string

func (*Agent) Join

func (a *Agent) Join(ctx context.Context, network string, address netip.Addr) (netip.Addr, error)

Join connects the agent to an engine network at the address the cloud leased for it, so guests can bridge onto that network, and returns the address; a network already joined returns the address it has there.

func (*Agent) Leave

func (a *Agent) Leave(ctx context.Context, network string) error

Leave takes the agent off an engine network it joined, once the cloud has no workload left on it: the agent dissolves the bridge its guests on that network used, and the container leaves the network, so the engine can remove it. The agent never leaves the network it started on, where the simulator reaches it.

func (*Agent) Stop

func (a *Agent) Stop()

Stop ends every guest and the agent.

type Client

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

Client talks to one agent.

func NewClient

func NewClient(base, token string) *Client

NewClient reaches the agent at base ("http://host:port") with its token.

func (*Client) AttachDisk

func (c *Client) AttachDisk(ctx context.Context, id string, slot, sizeMiB int) error

AttachDisk gives one of the guest's disk slots a block device of the size.

func (*Client) Create

func (c *Client) Create(ctx context.Context, spec GuestSpec) (GuestState, error)

Create registers a guest; its root filesystem follows with UploadRootFS.

func (*Client) CreateMember

func (c *Client) CreateMember(ctx context.Context, id string, spec MemberSpec) (MemberState, error)

CreateMember declares a member of a running guest; its root filesystem follows with UploadMemberRootFS and it runs from StartMember.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, id string) error

Delete stops the guest if it runs and removes everything it held.

func (*Client) Exec

func (c *Client) Exec(ctx context.Context, id string, command []string) (ExecResponse, error)

Exec runs a command in the guest, in its first process's root.

func (*Client) ExecIn

func (c *Client) ExecIn(ctx context.Context, id, process string, command []string) (ExecResponse, error)

ExecIn runs a command in the root of the process named: InitProcess or empty for the first process, else a member.

func (*Client) ExportRootFS

func (c *Client) ExportRootFS(ctx context.Context, id string) (io.ReadCloser, error)

ExportRootFS streams the guest's root filesystem as a tar archive, which the caller closes. A running guest's filesystem is frozen while the agent reads it, so the archive is consistent.

func (*Client) Get

func (c *Client) Get(ctx context.Context, id string) (GuestState, error)

func (*Client) LeaveNetwork

func (c *Client) LeaveNetwork(ctx context.Context, address netip.Addr) error

LeaveNetwork has the agent dissolve the bridge it built for the network it holds address on, ahead of its container leaving that network.

func (*Client) List

func (c *Client) List(ctx context.Context) ([]GuestState, error)

List reads every guest the agent holds.

func (*Client) Logs

func (c *Client) Logs(ctx context.Context, id string, opts LogOptions, fn func(LogLine)) error

Logs hands fn each line the guest's processes wrote.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

func (*Client) SetIngress

func (c *Client) SetIngress(ctx context.Context, id string, stages [][]PacketRule) error

SetIngress replaces the rules at the guest's tap.

func (*Client) SetRoute

func (c *Client) SetRoute(ctx context.Context, id, defaultRoute string) error

SetRoute replaces where the guest's default route goes, in the terms of GuestNetwork.DefaultRoute.

func (*Client) Start

func (c *Client) Start(ctx context.Context, id string) (GuestState, error)

Start boots the guest and returns once its first process answers.

func (*Client) StartMember

func (c *Client) StartMember(ctx context.Context, id, name string) (MemberState, error)

StartMember mounts the member's root filesystem in the guest and starts its process.

func (*Client) Stop

func (c *Client) Stop(ctx context.Context, id string) error

Stop ends the guest's first process within its grace; the machine powers off once its members have ended too.

func (*Client) StopMember

func (c *Client) StopMember(ctx context.Context, id, name string) error

StopMember ends the member's process within its grace.

func (*Client) UploadMemberRootFS

func (c *Client) UploadMemberRootFS(ctx context.Context, id, name string, archive io.Reader) error

UploadMemberRootFS streams the member's root filesystem as a tar archive.

func (*Client) UploadRootFS

func (c *Client) UploadRootFS(ctx context.Context, id string, archive io.Reader) error

UploadRootFS streams the guest's root filesystem as a tar archive — an OCI image's filesystem as the engine exports it.

func (*Client) Wait

func (c *Client) Wait(ctx context.Context, id string) (GuestState, error)

Wait blocks until the guest's first process has ended; the machine runs on while members do.

func (*Client) WaitMember

func (c *Client) WaitMember(ctx context.Context, id, name string) (MemberState, error)

WaitMember blocks until the member's process has ended.

func (*Client) WaitReady

func (c *Client) WaitReady(ctx context.Context) error

WaitReady polls Ping until the agent answers or ctx ends.

func (*Client) WaitStopped

func (c *Client) WaitStopped(ctx context.Context, id string) (GuestState, error)

WaitStopped blocks until the machine has stopped: its first process and every member have ended.

type ExecRequest

type ExecRequest struct {
	Command []string `json:"command"`
	Process string   `json:"process,omitempty"`
}

ExecRequest runs a command in a guest: in its first process's root, or in the root of the member Process names.

type ExecResponse

type ExecResponse struct {
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	ExitCode int    `json:"exitCode"`
}

ExecResponse is what the command produced.

type GuestConfig

type GuestConfig struct {
	Hostname   string            `json:"hostname"`
	Address    string            `json:"address"`
	Hosts      []string          `json:"hosts"`
	Command    []string          `json:"command"`
	Args       []string          `json:"args"`
	Env        map[string]string `json:"env"`
	WorkingDir string            `json:"workingDir"`
	User       string            `json:"user"`
	DNS        []string          `json:"dns"`
	StopGrace  time.Duration     `json:"stopGrace"`
}

GuestConfig is what the agent writes into the guest's root filesystem for guestinit: everything the first process needs that the kernel command line does not carry.

type GuestNetwork

type GuestNetwork struct {
	// AgentAddress is the agent's own address on the network, which names the
	// interface the guest bridges onto.
	AgentAddress string `json:"agentAddress"`
	// Address is the guest's address in CIDR notation.
	Address string `json:"address"`
	// Gateway is the network's own gateway, where the guest reaches the
	// engine's host and the shares it serves.
	Gateway string `json:"gateway"`
	// DefaultRoute is where the guest's default route goes: empty for
	// Gateway, an address on the network for another next hop, or
	// NoDefaultRoute for none.
	DefaultRoute string `json:"defaultRoute,omitempty"`
	MAC          string `json:"mac"`
	// DNS are the resolvers the guest asks.
	DNS []string `json:"dns,omitempty"`
	// Routes are the guest's further routes, which it takes before its first
	// process starts: the cloud's fixed link-local addresses through the
	// network's sidecar.
	Routes []GuestRoute `json:"routes,omitempty"`
}

GuestNetwork is the guest's place on an engine network the agent joined.

type GuestRoute

type GuestRoute struct {
	Destination string `json:"destination"`
	Via         string `json:"via"`
}

GuestRoute sends what the guest addresses to Destination (a CIDR) through Via.

type GuestSpec

type GuestSpec struct {
	ID       string `json:"id"`
	Hostname string `json:"hostname,omitempty"`
	// Hosts are name:address entries for the guest's hosts file; the address
	// host-gateway stands for the network's gateway, as the engine reads it.
	Hosts []string `json:"hosts,omitempty"`
	// Labels mark the guest for the simulator that placed it, as a
	// container's labels do, so a restarted simulator finds it again.
	Labels  map[string]string `json:"labels,omitempty"`
	Command []string          `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	// WorkingDir is where the first process starts; empty is /.
	WorkingDir string `json:"workingDir,omitempty"`
	// User runs the first process as uid[:gid]; empty is root.
	User string `json:"user,omitempty"`
	// Network places the guest on the agent's network at a fixed address.
	Network GuestNetwork `json:"network"`
	// ExtraNetworks are further networks the guest has an interface on,
	// eth1 onwards, each at its address, with no route out through it: a
	// container's further engine networks.
	ExtraNetworks []GuestNetwork `json:"extraNetworks,omitempty"`
	VCPUs         int            `json:"vcpus,omitempty"`
	// MemoryMiB is the guest's memory; zero takes 512.
	MemoryMiB int `json:"memoryMiB,omitempty"`
	// The agent writes Seed files into the root filesystem before it boots.
	Seed []SeedFile `json:"seed,omitempty"`
	// StopGrace is how long the first process gets between SIGTERM and the
	// guest's power-off.
	StopGrace time.Duration `json:"stopGrace,omitempty"`
	// Ingress is what the guest may receive: stages a packet passes in
	// turn, each a rule list whose first match decides, where an accept
	// hands the packet to the next stage and a stage nothing matches drops
	// it. No stages admit everything, as a cloud with no rules attached
	// does; an empty stage admits nothing.
	Ingress [][]PacketRule `json:"ingress,omitempty"`
	// DiskSlots is how many block devices beyond the root the guest can take
	// while it runs, members' root filesystems among them; zero takes four.
	DiskSlots int `json:"diskSlots,omitempty"`
	// Mounts are the file shares guestinit mounts before the first process
	// starts: what a bind mount gives a container.
	Mounts []Mount `json:"mounts,omitempty"`
}

type GuestState

type GuestState struct {
	ID      string            `json:"id"`
	Status  GuestStatus       `json:"status"`
	Labels  map[string]string `json:"labels,omitempty"`
	Address string            `json:"address"`
	// Gateway is the guest's network's gateway, where the guest reaches a
	// share the simulator serves, and AgentAddress the agent's own address on
	// that network, where it reaches a share served from the agent's namespace.
	Gateway      string        `json:"gateway,omitempty"`
	AgentAddress string        `json:"agentAddress,omitempty"`
	ExitCode     int           `json:"exitCode"`
	Error        string        `json:"error,omitempty"`
	StartedAt    time.Time     `json:"startedAt"`
	ExitedAt     time.Time     `json:"exitedAt,omitempty"`
	StoppedAt    time.Time     `json:"stoppedAt"`
	Members      []MemberState `json:"members,omitempty"`
}

GuestState is a guest as the agent sees it. Status is the machine's; ExitedAt is when the first process ended, zero while it runs, and the machine runs on past it while members do.

type GuestStatus

type GuestStatus string

GuestStatus is what the agent reports about a guest.

const (
	// GuestCreating is a guest whose root filesystem is being prepared.
	GuestCreating GuestStatus = "creating"
	// GuestRunning is a guest whose first process runs.
	GuestRunning GuestStatus = "running"
	// GuestExited is a guest whose first process has ended and whose machine
	// has powered off.
	GuestExited GuestStatus = "exited"
)

type LogLine

type LogLine struct {
	Time   time.Time `json:"time"`
	Stream string    `json:"stream"`
	Text   string    `json:"text"`
	Member string    `json:"member,omitempty"`
}

LogLine is one line a guest's process wrote: the first process when Member is empty, else the member named.

type LogOptions

type LogOptions struct {
	// Follow keeps reading new lines until the boot in progress has ended,
	// or, with Process set, until that process has ended and every line it
	// wrote is out.
	Follow bool
	// CurrentBoot reads the boot in progress alone; otherwise every boot's
	// lines come, the whole console of the machine.
	CurrentBoot bool
	// Process reads one process's lines: InitProcess for the first process,
	// a member's name for the member; empty reads every process's.
	Process string
}

LogOptions select what Logs reads.

type MemberSpec

type MemberSpec struct {
	Name    string            `json:"name"`
	Labels  map[string]string `json:"labels,omitempty"`
	Command []string          `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	// WorkingDir is where the member's process starts, inside its root.
	WorkingDir string `json:"workingDir,omitempty"`
	// User runs the process as uid[:gid], resolved in the member's root.
	User string `json:"user,omitempty"`
	// The agent writes Seed files into the member's root filesystem before it
	// mounts.
	Seed []SeedFile `json:"seed,omitempty"`
	// StopGrace is how long the process gets between SIGTERM and SIGKILL.
	StopGrace time.Duration `json:"stopGrace,omitempty"`
	// Mounts are the file shares guestinit mounts into the member's root before
	// its process starts.
	Mounts []Mount `json:"mounts,omitempty"`
}

MemberSpec is a process tree the guest runs beside its first process from a root filesystem of its own, sharing the guest's network, hostname and kernel: a sidecar container's shape. The member starts once the guest runs, and the guest powers off when its first process and every member have ended.

type MemberState

type MemberState struct {
	Name      string            `json:"name"`
	Status    GuestStatus       `json:"status"`
	Labels    map[string]string `json:"labels,omitempty"`
	ExitCode  int               `json:"exitCode"`
	Error     string            `json:"error,omitempty"`
	StartedAt time.Time         `json:"startedAt"`
	StoppedAt time.Time         `json:"stoppedAt"`
}

MemberState is a member as the agent sees it.

type Mount

type Mount struct {
	// Server is host:/export, the address the guest reaches the share at.
	Server   string `json:"server"`
	Port     int    `json:"port"`
	Path     string `json:"path"`
	ReadOnly bool   `json:"readOnly,omitempty"`
	// File names the share's one entry, which guestinit places at Path as a
	// file: a bind of a single file.
	File string `json:"file,omitempty"`
}

Mount is a file share the guest mounts over its network at Path: an NFSv4 export the simulator serves at Server's port, read-only when the bind was.

type Options

type Options struct {
	// Name is the container's name.
	Name string
	// Network is the engine network the agent starts on, at Address; the
	// simulator reaches the agent's API there. Every other network comes
	// through Join.
	Network string
	Address netip.Addr
	Labels  map[string]string
}

Options place the agent.

type PacketRule

type PacketRule struct {
	Protocol   string `json:"protocol"`
	SourceCIDR string `json:"sourceCIDR"`
	FromPort   int    `json:"fromPort"`
	ToPort     int    `json:"toPort"`
	Action     string `json:"action"`
}

PacketRule is one rule at the guest's tap, as netrules.PacketRule spells it.

type SeedFile

type SeedFile struct {
	Path string `json:"path"`
	Mode int64  `json:"mode,omitempty"`
	Data []byte `json:"data"`
}

SeedFile is one file written into the guest's root filesystem.

Directories

Path Synopsis
cmd
guestinit command
Command guestinit is the first process of a Firecracker guest the node agent boots.
Command guestinit is the first process of a Firecracker guest the node agent boots.
nodeagent command
Command nodeagent boots Firecracker microVMs for the simulator that started it.
Command nodeagent boots Firecracker microVMs for the simulator that started it.
nodeagent-image command
Command nodeagent-image builds the node agent's image on the engine, or finds it held, and prints its name.
Command nodeagent-image builds the node agent's image on the engine, or finds it held, and prints its name.

Jump to

Keyboard shortcuts

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