firecracker

README

A basic Go interface to the Firecracker API

This package is a Go library to interact with the Firecracker API. There is also a command-line application that can be used to control Firecracker microVMs called firectl.

The library and command-line application are not yet complete. See the TODO file for an incomplete list of missing features.

Developing

Please see HACKING

Building

This library requires Go 1.11 and Go modules to build. A Makefile is provided for convenience, but is not required. When using the Makefile, you can pass additional flags to the Go compiler via the EXTRAGOARGS make variable.

Tools

There's a basic command-line tool, built as cmd/firectl/firectl that lets you run arbitrary Firecracker MicroVMs via the command line. This lets you run a fully functional Firecracker MicroVM, including console access, read/write access to filesystems, and network connectivity.

Usage of ./cmd/firectl/firectl:
    --firecracker-binary=  Path to firecracker binary
    --firecracker-console= Console type (stdio|xterm|none) (default: stdio)
    --kernel=              Path to the kernel image (default: ./vmlinux)
    --kernel-opts=         Kernel commandline (default: ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules)
    --root-drive=          Path to root disk image
    --add-drive=           Path to additional drive, suffixed with :ro or :rw, can be specified multiple times
    --tap-device=          NIC info, specified as DEVICE:MAC
    --vmm-log-fifo=        FIFO for firecracker logs
    --log-level=           vmm log level (default: Debug)
    --metrics-fifo=        FIFO for firecracker metrics
-d, --debug                Enable debug output
-h, --help                 Show usage

$ ./cmd/firectl/firectl --firecracker-binary=./firecracker-0.10.1 --firecracker-console=stdio --root-drive=openwrt-x86-64-rootfs-squashfs.img --tap-device=vmtap33/9a:e4:f6:b0:2d:f3 --add-drive drive-2.img:ro -d --vmm-log-fifo=/tmp/fc-logs.fifo --metrics-fifo=/tmp/fc-metrics

Network configuration

TODO

License

This library is licensed under the Apache 2.0 License.

Documentation

Index

• Constants
• type BlockDevice
• type CPUTemplate
• type Config
• type Firecracker
• type FirecrackerClient
  • func NewFirecrackerClient(socketPath string) *FirecrackerClient
  • func (f *FirecrackerClient) CreateSyncAction(ctx context.Context, info *models.InstanceActionInfo) (*ops.CreateSyncActionNoContent, error)
  • func (f *FirecrackerClient) GetMachineConfig() (*ops.GetMachineConfigOK, error)
  • func (f *FirecrackerClient) PutGuestBootSource(ctx context.Context, source *models.BootSource) (*ops.PutGuestBootSourceNoContent, error)
  • func (f *FirecrackerClient) PutGuestDriveByID(ctx context.Context, driveID string, drive *models.Drive) (*ops.PutGuestDriveByIDNoContent, error)
  • func (f *FirecrackerClient) PutGuestNetworkInterfaceByID(ctx context.Context, ifaceID string, ifaceCfg *models.NetworkInterface) (*ops.PutGuestNetworkInterfaceByIDNoContent, error)
  • func (f *FirecrackerClient) PutGuestVsockByID(ctx context.Context, vsockID string, vsock *models.Vsock) (*ops.PutGuestVsockByIDCreated, *ops.PutGuestVsockByIDNoContent, error)
  • func (f *FirecrackerClient) PutLogger(ctx context.Context, logger *models.Logger) (*ops.PutLoggerNoContent, error)
  • func (f *FirecrackerClient) PutMachineConfiguration(ctx context.Context, cfg *models.MachineConfiguration) (*ops.PutMachineConfigurationNoContent, error)
• type Machine
  • func NewMachine(cfg Config, firecracker Firecracker, l *log.Logger) *Machine
  • func (m *Machine) Init(ctx context.Context) (chan error, error)
  • func (m Machine) LogFile() string
  • func (m Machine) LogLevel() string
  • func (m *Machine) Logger() *log.Logger
  • func (m *Machine) StartInstance(ctx context.Context) error
  • func (m *Machine) StopVMM() error
• type NetworkInterface
• type VsockDevice

Constants

const (

	// ConsoleXterm indicates that the machine's console should be presented in an xterm
	ConsoleXterm = "xterm"
	// ConsoleStdio indicates that the machine's console should re-use the parent's stdio streams
	ConsoleStdio = "stdio"
	// ConsoleNone indicates that the machine's console IO should be discarded
	ConsoleNone = "none"
)

const (
	CPUTemplateT2 = models.CPUTemplateT2
	CPUTemplateC3 = models.CPUTemplateC3
)

CPUTemplates known by Firecracker. These are passed through directly from the model.

Types

type BlockDevice

type BlockDevice struct {
	HostPath string
	Mode     string
}

BlockDevice represents a host block device mapped to the firecracker VM. mode is either "ro" or "rw"

type CPUTemplate

type CPUTemplate models.CPUTemplate

CPUTemplate defines a set of CPU features that are exposed by Firecracker

type Config

type Config struct {
	BinPath           string
	SocketPath        string
	LogFifo           string
	LogLevel          string
	MetricsFifo       string
	KernelImagePath   string
	KernelArgs        string
	CPUCount          int64
	HtEnabled         bool
	CPUTemplate       CPUTemplate
	MemInMiB          int64
	RootDrive         BlockDevice
	RootPartitionUUID string
	AdditionalDrives  []BlockDevice
	NetworkInterfaces []NetworkInterface
	VsockDevices      []VsockDevice
	Console           string
	// contains filtered or unexported fields
}

Config is a collection of user-configurable VMM settings

type Firecracker

type Firecracker interface {
	PutLogger(ctx context.Context, logger *models.Logger) (*ops.PutLoggerNoContent, error)
	PutMachineConfiguration(ctx context.Context, cfg *models.MachineConfiguration) (*ops.PutMachineConfigurationNoContent, error)
	PutGuestBootSource(ctx context.Context, source *models.BootSource) (*ops.PutGuestBootSourceNoContent, error)
	PutGuestNetworkInterfaceByID(ctx context.Context, ifaceID string, ifaceCfg *models.NetworkInterface) (*ops.PutGuestNetworkInterfaceByIDNoContent, error)
	PutGuestDriveByID(ctx context.Context, driveID string, drive *models.Drive) (*ops.PutGuestDriveByIDNoContent, error)
	PutGuestVsockByID(ctx context.Context, vsockID string, vsock *models.Vsock) (*ops.PutGuestVsockByIDCreated, *ops.PutGuestVsockByIDNoContent, error)
	CreateSyncAction(ctx context.Context, info *models.InstanceActionInfo) (*ops.CreateSyncActionNoContent, error)
	GetMachineConfig() (*ops.GetMachineConfigOK, error)
}

type FirecrackerClient

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

func NewFirecrackerClient

func NewFirecrackerClient(socketPath string) *FirecrackerClient

func (*FirecrackerClient) CreateSyncAction

func (f *FirecrackerClient) CreateSyncAction(ctx context.Context, info *models.InstanceActionInfo) (*ops.CreateSyncActionNoContent, error)

func (*FirecrackerClient) GetMachineConfig

func (f *FirecrackerClient) GetMachineConfig() (*ops.GetMachineConfigOK, error)

func (*FirecrackerClient) PutGuestBootSource

func (f *FirecrackerClient) PutGuestBootSource(ctx context.Context, source *models.BootSource) (*ops.PutGuestBootSourceNoContent, error)

func (*FirecrackerClient) PutGuestDriveByID

func (f *FirecrackerClient) PutGuestDriveByID(ctx context.Context, driveID string, drive *models.Drive) (*ops.PutGuestDriveByIDNoContent, error)

func (*FirecrackerClient) PutGuestNetworkInterfaceByID

func (f *FirecrackerClient) PutGuestNetworkInterfaceByID(ctx context.Context, ifaceID string, ifaceCfg *models.NetworkInterface) (*ops.PutGuestNetworkInterfaceByIDNoContent, error)

func (*FirecrackerClient) PutGuestVsockByID

func (f *FirecrackerClient) PutGuestVsockByID(ctx context.Context, vsockID string, vsock *models.Vsock) (*ops.PutGuestVsockByIDCreated, *ops.PutGuestVsockByIDNoContent, error)

func (*FirecrackerClient) PutLogger

func (f *FirecrackerClient) PutLogger(ctx context.Context, logger *models.Logger) (*ops.PutLoggerNoContent, error)

func (*FirecrackerClient) PutMachineConfiguration

func (f *FirecrackerClient) PutMachineConfiguration(ctx context.Context, cfg *models.MachineConfiguration) (*ops.PutMachineConfigurationNoContent, error)

type Machine

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

Machine is the main object for manipulating firecracker VMs

func NewMachine

func NewMachine(cfg Config, firecracker Firecracker, l *log.Logger) *Machine

NewMachine initializes a new Machine instance

func (*Machine) Init

func (m *Machine) Init(ctx context.Context) (chan error, error)

Init starts the VMM and attaches drives and network interfaces.

func (Machine) LogFile

func (m Machine) LogFile() string

LogFile returns the filesystem path of the VMM log

func (Machine) LogLevel

func (m Machine) LogLevel() string

LogLevel returns the VMM log level.

func (*Machine) Logger

func (m *Machine) Logger() *log.Logger

Logger returns a logrus logger appropriate for logging hypervisor messages

func (*Machine) StartInstance

func (m *Machine) StartInstance(ctx context.Context) error

StartInstance starts the firecracker VM

func (*Machine) StopVMM

func (m *Machine) StopVMM() error

StopVMM stops the current VMM.

type NetworkInterface

type NetworkInterface struct {
	MacAddress  string
	HostDevName string
}

NetworkInterface represents a Firecracker VMs network interface.

type VsockDevice

type VsockDevice struct {
	Path string
	CID  uint32
}

VsockDevice represents a vsock connection between the host and the guest VM.