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
- Variables
- func EnsureImage(ctx context.Context, cli *client.Client) (string, string, error)
- func LogSink() sim.LogSink
- type Agent
- func (a *Agent) AddressOn(network string) (netip.Addr, bool)
- func (a *Agent) Architecture() string
- func (a *Agent) Client() *Client
- func (a *Agent) ContainerID() string
- func (a *Agent) Join(ctx context.Context, network string, address netip.Addr) (netip.Addr, error)
- func (a *Agent) Leave(ctx context.Context, network string) error
- func (a *Agent) Stop()
- type Client
- func (c *Client) AttachDisk(ctx context.Context, id string, slot, sizeMiB int) error
- func (c *Client) Create(ctx context.Context, spec GuestSpec) (GuestState, error)
- func (c *Client) CreateMember(ctx context.Context, id string, spec MemberSpec) (MemberState, error)
- func (c *Client) Delete(ctx context.Context, id string) error
- func (c *Client) Exec(ctx context.Context, id string, command []string) (ExecResponse, error)
- func (c *Client) ExecIn(ctx context.Context, id, process string, command []string) (ExecResponse, error)
- func (c *Client) ExportRootFS(ctx context.Context, id string) (io.ReadCloser, error)
- func (c *Client) Get(ctx context.Context, id string) (GuestState, error)
- func (c *Client) LeaveNetwork(ctx context.Context, address netip.Addr) error
- func (c *Client) List(ctx context.Context) ([]GuestState, error)
- func (c *Client) Logs(ctx context.Context, id string, opts LogOptions, fn func(LogLine)) error
- func (c *Client) Ping(ctx context.Context) error
- func (c *Client) SetIngress(ctx context.Context, id string, stages [][]PacketRule) error
- func (c *Client) SetRoute(ctx context.Context, id, defaultRoute string) error
- func (c *Client) Start(ctx context.Context, id string) (GuestState, error)
- func (c *Client) StartMember(ctx context.Context, id, name string) (MemberState, error)
- func (c *Client) Stop(ctx context.Context, id string) error
- func (c *Client) StopMember(ctx context.Context, id, name string) error
- func (c *Client) UploadMemberRootFS(ctx context.Context, id, name string, archive io.Reader) error
- func (c *Client) UploadRootFS(ctx context.Context, id string, archive io.Reader) error
- func (c *Client) Wait(ctx context.Context, id string) (GuestState, error)
- func (c *Client) WaitMember(ctx context.Context, id, name string) (MemberState, error)
- func (c *Client) WaitReady(ctx context.Context) error
- func (c *Client) WaitStopped(ctx context.Context, id string) (GuestState, error)
- type ExecRequest
- type ExecResponse
- type GuestConfig
- type GuestNetwork
- type GuestRoute
- type GuestSpec
- type GuestState
- type GuestStatus
- type LogLine
- type LogOptions
- type MemberSpec
- type MemberState
- type Mount
- type Options
- type PacketRule
- type SeedFile
Constants ¶
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.
const GuestConfigPath = "/etc/sockerless/guest.json"
GuestConfigPath is where guestinit reads its configuration.
const GuestInitPath = "/sbin/sockerless-init"
GuestInitPath is where the agent places guestinit in the root filesystem.
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.
const NoDefaultRoute = "none"
NoDefaultRoute is the DefaultRoute of a guest with no route out of its network.
Variables ¶
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 ¶
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.
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 ¶
Start builds the agent image if the engine lacks it, starts the agent and returns once its API answers.
func (*Agent) Architecture ¶
Architecture is the OCI architecture the agent's guests run on.
func (*Agent) ContainerID ¶
func (*Agent) Join ¶
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 ¶
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.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client talks to one agent.
func NewClient ¶
NewClient reaches the agent at base ("http://host:port") with its token.
func (*Client) AttachDisk ¶
AttachDisk gives one of the guest's disk slots a block device of the size.
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) 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 ¶
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) LeaveNetwork ¶
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) SetIngress ¶
SetIngress replaces the rules at the guest's tap.
func (*Client) SetRoute ¶
SetRoute replaces where the guest's default route goes, in the terms of GuestNetwork.DefaultRoute.
func (*Client) StartMember ¶
StartMember mounts the member's root filesystem in the guest and starts its process.
func (*Client) Stop ¶
Stop ends the guest's first process within its grace; the machine powers off once its members have ended too.
func (*Client) StopMember ¶
StopMember ends the member's process within its grace.
func (*Client) UploadMemberRootFS ¶
UploadMemberRootFS streams the member's root filesystem as a tar archive.
func (*Client) UploadRootFS ¶
UploadRootFS streams the guest's root filesystem as a tar archive — an OCI image's filesystem as the engine exports it.
func (*Client) Wait ¶
Wait blocks until the guest's first process has ended; the machine runs on while members do.
func (*Client) WaitMember ¶
WaitMember blocks until the member's process has ended.
func (*Client) WaitStopped ¶
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 ¶
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.
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. |