firecracker

package module
v0.22.1-0...-61974fd Latest Latest
Warning

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

 Go to latest Published: May 25, 2021 License: Apache-2.0 Imports: 32 Imported by: 0

README

A basic Go interface to the Firecracker API

Build status GoDoc

This package is a Go library to interact with the Firecracker API. It is designed as an abstraction of the OpenAPI-generated client that allows for convenient manipulation of Firecracker VM from Go programs.

There are some Firecracker features that are not yet supported by the SDK. These are tracked as GitHub issues with the firecracker-feature label . Contributions to address missing features are welcomed.

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 firectl tool that provides a simple command-line interface to launching a firecracker VM. It also serves as an example client of this SDK.

Network configuration

Firecracker, by design, only supports Linux tap devices. The SDK provides facilities to:

  • Attach a pre-created tap device, optionally with static IP configuration, to the VM. This is referred to as a "static network interface".
  • Create a tap device via CNI plugins, which will then be attached to the VM automatically by the SDK. This is referred to as a "CNI-configured network interface"
CNI

If a VM is configured with a CNI-configured network interface, by default CNI configuration files will be sought from /etc/cni/conf.d and CNI plugins will be sought under /opt/cni/bin (both of these values can be overridden via API fields). CNI network lists must be specified in a configuration file at this time.

It's currently highly recommended to use CNI configuration that includes tc-redirect-tap as a chained plugin. This will allow you to adapt pre-existing CNI plugins/configuration to a tap device usable by a Firecracker VM.

Example

With the following file at /etc/cni/conf.d/fcnet.conflist:

{
  "name": "fcnet",
  "cniVersion": "0.3.1",
  "plugins": [
    {
      "type": "ptp",
      "ipMasq": true,
      "ipam": {
        "type": "host-local",
        "subnet": "192.168.127.0/24",
        "resolvConf": "/etc/resolv.conf"
      }
    },
    {
      "type": "firewall"
    },
    {
      "type": "tc-redirect-tap"
    }
  ]
}

and the ptp, host-local, firewall, and tc-redirect-tap CNI plugin binaries installed under /opt/cni/bin, you can specify, in the Go SDK API, a Machine with the following NetworkInterface:

{
  NetworkInterfaces: []firecracker.NetworkInterface{{
    CNIConfiguration: &firecracker.CNIConfiguration{
      NetworkName: "fcnet",
      IfName: "veth0",
    },
  }}
}

Note that NetworkName in the CNIConfiguration of the API matches the name field specified inside the /etc/cni/conf.d/fcnet.conflist file.

With the above configuration, when the Firecracker VM is started the SDK will invoke CNI and place the final VM inside the resultant network namespace. The end result being:

  • Outside the network namespace, a single veth endpoint created by the ptp plugin will exist with a static IP from the host-local plugin (i.e. 192.168.127.1)
    • Users can obtain the IP address and other static network configuration generated for their machine via CNI by inspecting the network interface's StaticConfiguration field, which will be automatically filled out after the machine has been started.
    • The IP address, for example, can be obtained at NetworkInterfaces[0].StaticConfiguration.IPConfiguration.IPAddr after a call to the machine object's Start method succeeds.
  • Inside the VM's network namespace:
    • The other side of the veth device will exist with name veth0, as specified by the IfName parameter above, and a different IP (i.e. 192.168.127.2)
    • The tap device created by tc-redirect-tap, which will not have an IP but will have all of its traffic mirrored with the veth0 device
  • Inside the actual Firecracker VM guest:
    • A network interface with the same IP as that of veth0 (i.e. 192.168.127.2)
    • Traffic sent on this device will be mirrored with the external veth0 device, so from a practical perspective the VM's internal network interface will externally appear the same as veth0
    • The internal name of the interface is determined by the Guest OS, not the Firecracker Go SDK.

Note that the ptp and host-local plugins are not required, they are just used in this example. The tc-redirect-tap plugin can be chained after any CNI plugin that creates a network interface. It will setup the tap device to be mirrored with the IfName device created by any previous plugin. Any IP configuration on that IfName device will be applied statically to the VM's internal network interface on boot.

Also note that use of CNI-configured network interfaces will require the SDK to be running with at least CAP_SYS_ADMIN and CAP_NET_ADMIN Linux capabilities (in order to have the ability to create and configure network namespaces).

Network Setup Limitations

These limitations are a result of the current implementation and may be lifted in the future:

  • For a given VM, if a CNI-configured network interface is specified or a static interface that includes IP configuration is specified, the VM can only have a single network interface, not multiple.
    • Users can specify multiple static interfaces as long as none of them include IP configuration.
  • DNS nameserver settings will only be effective if the VM's rootfs makes /etc/resolv.conf be a symlink to /proc/net/pnp.
  • Only up to 2 DNS nameservers can be configured within the VM internally.
    • If a static network interface specifies more than 2, an error will be returned.
    • If a CNI-configured network interface receives more than 2 nameservers from the CNI invocation result, the nameservers after the second will be ignored without error (in order to be compatible with pre-existing CNI plugins/configuration).

Questions?

Please use GitHub issues to report problems, discuss roadmap items, or make feature requests.

If you've discovered an issue that may have security implications to users or developers of this software, please do not report it using GitHub issues, but instead follow Firecracker's security reporting guidelines.

Other discussion: For general discussion, please join us in the #general channel on the Firecracker Slack.

License

This library is licensed under the Apache 2.0 License.

Documentation

Overview

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at 

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package firecracker provides a library to interact with the Firecracker API.

Firecracker is an open-source virtualization technology that is purpose-built for creating and managing secure, multi-tenant containers and functions-based services. See https://firecracker-microvm.github.io/ for more details.

This library requires Go 1.11 and can be used with Go modules.

BUG(aws): There are some Firecracker features that are not yet supported by the SDK. These are tracked as GitHub issues with the firecracker-feature label: https://github.com/firecracker-microvm/firecracker-go-sdk/issues?q=is%3Aissue+is%3Aopen+label%3Afirecracker-feature

This library is licensed under the Apache 2.0 License.

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at 

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at 

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at 

http://aws.amazon.com/apache2.0/

or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Examples

Constants

View Source 
const (
	StartVMMHandlerName                = "fcinit.StartVMM"
	BootstrapLoggingHandlerName        = "fcinit.BootstrapLogging"
	CreateLogFilesHandlerName          = "fcinit.CreateLogFilesHandler"
	CreateMachineHandlerName           = "fcinit.CreateMachine"
	CreateBootSourceHandlerName        = "fcinit.CreateBootSource"
	AttachDrivesHandlerName            = "fcinit.AttachDrives"
	CreateNetworkInterfacesHandlerName = "fcinit.CreateNetworkInterfaces"
	AddVsocksHandlerName               = "fcinit.AddVsocks"
	SetMetadataHandlerName             = "fcinit.SetMetadata"
	ConfigMmdsHandlerName              = "fcinit.ConfigMmds"
	LinkFilesToRootFSHandlerName       = "fcinit.LinkFilesToRootFS"
	SetupNetworkHandlerName            = "fcinit.SetupNetwork"
	SetupKernelArgsHandlerName         = "fcinit.SetupKernelArgs"
	CreateBalloonHandlerName           = "fcint.CreateBalloon"

	ValidateCfgHandlerName        = "validate.Cfg"
	ValidateJailerCfgHandlerName  = "validate.JailerCfg"
	ValidateNetworkCfgHandlerName = "validate.NetworkCfg"
)

Handler name constants

View Source 
const Version = "0.22.0"

Version represents the current version of the SDK.

Variables

View Source 
var AddVsocksHandler = Handler{
	Name: AddVsocksHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.addVsocks(ctx, m.Cfg.VsockDevices...)
	},
}

AddVsocksHandler is a named handler that adds vsocks to the firecracker process.

View Source 
var AttachDrivesHandler = Handler{
	Name: AttachDrivesHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.attachDrives(ctx, m.Cfg.Drives...)
	},
}

AttachDrivesHandler is a named handler that will attach all drives for the firecracker process.

View Source 
var BootstrapLoggingHandler = Handler{
	Name: BootstrapLoggingHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		if err := m.setupLogging(ctx); err != nil {
			return err
		}
		if err := m.setupMetrics(ctx); err != nil {
			return err
		}
		m.logger.Debugf("setup logging: success")
		return nil
	},
}

BootstrapLoggingHandler is a named handler that will set up fifo logging of firecracker process.

View Source 
var ConfigMmdsHandler = Handler{
	Name: ConfigMmdsHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.setMmdsConfig(ctx, m.Cfg.MmdsAddress)
	},
}

ConfigMmdsHandler is a named handler that puts the MMDS config into the firecracker process.

View Source 
var ConfigValidationHandler = Handler{
	Name: ValidateCfgHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {

		return m.Cfg.Validate()
	},
}

ConfigValidationHandler is used to validate that required fields are present. This validator is to be used when the jailer is turned off.

View Source 
var CreateBootSourceHandler = Handler{
	Name: CreateBootSourceHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.createBootSource(ctx, m.Cfg.KernelImagePath, m.Cfg.InitrdPath, m.Cfg.KernelArgs)
	},
}

CreateBootSourceHandler is a named handler that will set up the booting process of the firecracker process.

View Source 
var CreateLogFilesHandler = Handler{
	Name: CreateLogFilesHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		if err := createFifoOrFile(ctx, m, m.Cfg.MetricsFifo, m.Cfg.MetricsPath); err != nil {
			return err
		}

		if err := createFifoOrFile(ctx, m, m.Cfg.LogFifo, m.Cfg.LogPath); err != nil {
			return err
		}

		if m.Cfg.FifoLogWriter != nil {
			if err := m.captureFifoToFile(ctx, m.logger, m.Cfg.LogFifo, m.Cfg.FifoLogWriter); err != nil {
				m.logger.Warnf("captureFifoToFile() returned %s. Continuing anyway.", err)
			}
		}

		m.logger.Debug("Created metrics and logging fifos.")

		return nil
	},
}

CreateLogFilesHandler is a named handler that will create the fifo log files

View Source 
var CreateMachineHandler = Handler{
	Name: CreateMachineHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.createMachine(ctx)
	},
}

CreateMachineHandler is a named handler that will "create" the machine and upload any necessary configuration to the firecracker process.

View Source 
var CreateNetworkInterfacesHandler = Handler{
	Name: CreateNetworkInterfacesHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.createNetworkInterfaces(ctx, m.Cfg.NetworkInterfaces...)
	},
}

CreateNetworkInterfacesHandler is a named handler that registers network interfaces with the Firecracker VMM.

View Source 
var ErrAlreadyStarted = errors.New("firecracker: machine already started")

ErrAlreadyStarted signifies that the Machine has already started and cannot be started again.

View Source 
var (
	// ErrMissingJailerConfig will occur when entering jailer logic but the
	// jailer config had not been specified.
	ErrMissingJailerConfig = fmt.Errorf("jailer config was not set for use")
)
View Source 
var ErrRequiredHandlerMissing = fmt.Errorf("required handler is missing from FcInit's list")

ErrRequiredHandlerMissing occurs when a required handler is not present in the handler list.

View Source 
var JailerConfigValidationHandler = Handler{
	Name: ValidateJailerCfgHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		if m.Cfg.JailerCfg == nil {
			return nil
		}

		hasRoot := m.Cfg.InitrdPath != ""
		for _, drive := range m.Cfg.Drives {
			if BoolValue(drive.IsRootDevice) {
				hasRoot = true
				break
			}
		}

		if !hasRoot {
			return fmt.Errorf("A root drive must be present in the drive list")
		}

		if m.Cfg.JailerCfg.ChrootStrategy == nil {
			return fmt.Errorf("ChrootStrategy cannot be nil")
		}

		if len(m.Cfg.JailerCfg.ExecFile) == 0 {
			return fmt.Errorf("exec file must be specified when using jailer mode")
		}

		if len(m.Cfg.JailerCfg.ID) == 0 {
			return fmt.Errorf("id must be specified when using jailer mode")
		}

		if m.Cfg.JailerCfg.GID == nil {
			return fmt.Errorf("GID must be specified when using jailer mode")
		}

		if m.Cfg.JailerCfg.UID == nil {
			return fmt.Errorf("UID must be specified when using jailer mode")
		}

		if m.Cfg.JailerCfg.NumaNode == nil {
			return fmt.Errorf("ID must be specified when using jailer mode")
		}

		return nil
	},
}

JailerConfigValidationHandler is used to validate that required fields are present.

View Source 
var NetworkConfigValidationHandler = Handler{
	Name: ValidateNetworkCfgHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.Cfg.ValidateNetwork()
	},
}
View Source 
var SetupKernelArgsHandler = Handler{
	Name: SetupKernelArgsHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.setupKernelArgs(ctx)
	},
}

SetupKernelArgsHandler is a named handler that will update any kernel boot args being provided to the VM based on the other configuration provided, if needed.

View Source 
var SetupNetworkHandler = Handler{
	Name: SetupNetworkHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.setupNetwork(ctx)
	},
}

SetupNetworkHandler is a named handler that will setup the network namespace and network interface configuration prior to the Firecracker VMM starting.

View Source 
var StartVMMHandler = Handler{
	Name: StartVMMHandlerName,
	Fn: func(ctx context.Context, m *Machine) error {
		return m.startVMM(ctx)
	},
}

StartVMMHandler is a named handler that will handle starting of the VMM. This handler will also set the exit channel on completion.

Functions

func Bool 

func Bool(b bool) *bool

Bool will return a pointer value of the given parameter.

func BoolValue 

func BoolValue(b *bool) bool

BoolValue will return a boolean value. If the pointer is nil, then false will be returned.

func Int 

func Int(v int) *int

Int will return a pointer value of the given parameters.

func Int64 

func Int64(v int64) *int64

Int64 will return a pointer value of the given parameter.

func Int64Value 

func Int64Value(v *int64) int64

Int64Value will return an int64 value. If the pointer is nil, then zero will be returned.

func IntValue 

func IntValue(v *int) int

IntValue will return an int value. If the pointer is nil, zero will be returned.

func NewRateLimiter 

func NewRateLimiter(bandwidth, ops models.TokenBucket, opts ...RateLimiterOpt) *models.RateLimiter

NewRateLimiter will construct a new RateLimiter with given parameters.

func NewUnixSocketTransport 

func NewUnixSocketTransport(socketPath string, logger *logrus.Entry, debug bool) runtime.ClientTransport

NewUnixSocketTransport creates a new clientTransport configured at the specified Unix socketPath.

func String 

func String(str string) *string

String will return a pointer value of the given parameter.

func StringValue 

func StringValue(str *string) string

StringValue will return a string value. If the pointer is nil, then an empty string will be returned.

Types

type BalloonDevice 

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

BalloonDevice is a builder that will create a balloon used to set up the firecracker microVM.

func NewBalloonDevice 

func NewBalloonDevice(amountMib int64, deflateOnOom bool, opts ...BalloonOpt) BalloonDevice

NewBalloonDevice will return a new BalloonDevice.

func (BalloonDevice) Build 

func (b BalloonDevice) Build() models.Balloon

Build will return a new balloon

func (BalloonDevice) UpdateAmountMib 

func (b BalloonDevice) UpdateAmountMib(amountMib int64) BalloonDevice

UpdateAmountMiB sets the target size of the balloon

func (BalloonDevice) UpdateStatsPollingIntervals 

func (b BalloonDevice) UpdateStatsPollingIntervals(statsPollingIntervals int64) BalloonDevice

UpdateStatsPollingIntervals sets the time in seconds between refreshing statistics. A non-zero value will enable the statistics. Defaults to 0.

type BalloonOpt 

type BalloonOpt func(*models.Balloon)

func WithStatsPollingIntervals 

func WithStatsPollingIntervals(statsPollingIntervals int64) BalloonOpt

WithStatsPollingIntervals is a functional option which sets the time in seconds between refreshing statistics.

type CNIConfiguration 

type CNIConfiguration struct {
	// NetworkName (either NetworkName or NetworkConfig are required)
	// corresponds to the "name" parameter in the CNI spec's
	// Network Configuration List structure. It selects the name
	// of the network whose configuration will be used when invoking CNI.
	NetworkName string

	// NetworkConfig (either NetworkName or NetworkConfig are required)
	// replaces the NetworkName with parsed CNI network configuration
	// skipping the requirement to store network config file in CNI
	// configuration directory.
	NetworkConfig *libcni.NetworkConfigList

	// IfName (optional) corresponds to the CNI_IFNAME parameter as specified
	// in the CNI spec. It generally specifies the name of the interface to be
	// created by a CNI plugin being invoked.
	//
	// Note that this does NOT necessarily correspond to the name of the
	// tap device the Firecracker VM will use as the tap device may be
	// created by a chained plugin that adapts the tap to a pre-existing
	// network device (which will by the one with "IfName").
	IfName string

	// VMIfName (optional) sets the interface name in the VM. It is used
	// to correctly pass IP configuration obtained from the CNI to the VM kernel.
	// It can be left blank for VMs with single network interface.
	VMIfName string

	// Args (optional) corresponds to the CNI_ARGS parameter as specified in
	// the CNI spec. It allows custom args to be passed to CNI plugins during
	// invocation.
	Args [][2]string

	// BinPath (optional) is a list of directories in which CNI plugin binaries
	// will be sought. If not provided, defaults to just "/opt/bin/CNI"
	BinPath []string

	// ConfDir (optional) is the directory in which CNI configuration files
	// will be sought. If not provided, defaults to "/etc/cni/conf.d"
	ConfDir string

	// CacheDir (optional) is the director in which CNI queries/results will be
	// cached by the runtime. If not provided, defaults to "/var/lib/cni"
	CacheDir string

	// Force allows to overwrite default behavior of the pre existing network deletion
	// mostly created for different types of CNI plugins which are not expecting fail on that step.
	// In case if Force was set to `True` error will be still logged, but new new network will be created anyway.
	Force bool
	// contains filtered or unexported fields
}

CNIConfiguration specifies the CNI parameters that will be used to generate the network namespace and tap device used by a Firecracker interface.

Currently, CNIConfiguration can only be specified for VMs that have a single network interface.

type Client 

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

Client is a client for interacting with the Firecracker API

func NewClient 

func NewClient(socketPath string, logger *logrus.Entry, debug bool, opts ...ClientOpt) *Client

NewClient creates a Client

func (*Client) CreateSnapshot 

func (f *Client) CreateSnapshot(ctx context.Context, snapshotParams *models.SnapshotCreateParams, opts ...CreateSnapshotOpt) (*ops.CreateSnapshotNoContent, error)

CreateSnapshot is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) CreateSyncAction 

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

CreateSyncAction is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) DescribeBalloonConfig 

func (f *Client) DescribeBalloonConfig(ctx context.Context) (*ops.DescribeBalloonConfigOK, error)

DescribeBalloonConfig is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) DescribeBalloonStats 

func (f *Client) DescribeBalloonStats(ctx context.Context) (*ops.DescribeBalloonStatsOK, error)

DescribeBalloonStats is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) GetInstanceInfo 

func (f *Client) GetInstanceInfo(ctx context.Context, opts ...DescribeInstanceOpt) (*ops.DescribeInstanceOK, error)

GetInstanceInfo is a wrapper for the swagger generated client to make calling of the API easier

func (*Client) GetMachineConfiguration 

func (f *Client) GetMachineConfiguration(opts ...GetMachineConfigurationOpt) (*ops.GetMachineConfigurationOK, error)

GetMachineConfiguration is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) GetMmds 

func (f *Client) GetMmds(ctx context.Context, opts ...GetMmdsOpt) (*ops.GetMmdsOK, error)

GetMmds is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) LoadSnapshot 

func (f *Client) LoadSnapshot(ctx context.Context, snapshotParams *models.SnapshotLoadParams, opts ...LoadSnapshotOpt) (*ops.LoadSnapshotNoContent, error)

LoadSnapshot is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchBalloon 

func (f *Client) PatchBalloon(ctx context.Context, ballonUpdate *models.BalloonUpdate, opts ...PatchBalloonOpt) (*ops.PatchBalloonNoContent, error)

PatchBalloon is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchBalloonStatsInterval 

func (f *Client) PatchBalloonStatsInterval(ctx context.Context, balloonStatsUpdate *models.BalloonStatsUpdate, opts ...PatchBalloonStatsIntervalOpt) (*ops.PatchBalloonStatsIntervalNoContent, error)

PatchBalloonStatsInterval is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchGuestDriveByID 

func (f *Client) PatchGuestDriveByID(ctx context.Context, driveID, pathOnHost string, opts ...PatchGuestDriveByIDOpt) (*ops.PatchGuestDriveByIDNoContent, error)

PatchGuestDriveByID is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchGuestNetworkInterfaceByID 

func (f *Client) PatchGuestNetworkInterfaceByID(ctx context.Context, ifaceID string, ifaceCfg *models.PartialNetworkInterface, opts ...PatchGuestNetworkInterfaceByIDOpt) (*ops.PatchGuestNetworkInterfaceByIDNoContent, error)

PatchGuestNetworkInterfaceByID is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchMmds 

func (f *Client) PatchMmds(ctx context.Context, metadata interface{}, opts ...PatchMmdsOpt) (*ops.PatchMmdsNoContent, error)

PatchMmds is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PatchVM 

func (f *Client) PatchVM(ctx context.Context, vm *models.VM, opts ...PatchVMOpt) (*ops.PatchVMNoContent, error)

PatchVM is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutBalloon 

func (f *Client) PutBalloon(ctx context.Context, balloon *models.Balloon, opts ...PutBalloonOpt) (*ops.PutBalloonNoContent, error)

PutBalloonOpt is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutGuestBootSource 

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

PutGuestBootSource is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutGuestDriveByID 

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

PutGuestDriveByID is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutGuestNetworkInterfaceByID 

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

PutGuestNetworkInterfaceByID is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutGuestVsock 

func (f *Client) PutGuestVsock(ctx context.Context, vsock *models.Vsock, opts ...PutGuestVsockOpt) (*ops.PutGuestVsockNoContent, error)

PutGuestVsock is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutLogger 

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

PutLogger is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutMachineConfiguration 

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

PutMachineConfiguration is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutMetrics 

func (f *Client) PutMetrics(ctx context.Context, metrics *models.Metrics, opts ...PutMetricsOpt) (*ops.PutMetricsNoContent, error)

PutMetrics is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutMmds 

func (f *Client) PutMmds(ctx context.Context, metadata interface{}, opts ...PutMmdsOpt) (*ops.PutMmdsNoContent, error)

PutMmds is a wrapper for the swagger generated client to make calling of the API easier.

func (*Client) PutMmdsConfig 

func (f *Client) PutMmdsConfig(ctx context.Context, config *models.MmdsConfig) (*ops.PutMmdsConfigNoContent, error)

PutMmdsConfig is a wrapper for the swagger generated client to make calling of the API easier.

type ClientOpt 

type ClientOpt func(*Client)

ClientOpt is a functional option used to modify the client after construction.

func WithOpsClient 

func WithOpsClient(opsClient ops.ClientIface) ClientOpt

WithOpsClient will return a functional option and replace the operations client. This is useful for mock and stub testing.

type Config 

type Config struct {
	// SocketPath defines the file path where the Firecracker control socket
	// should be created.
	SocketPath string

	// LogPath defines the file path where the Firecracker log is located.
	LogPath string

	// LogFifo defines the file path where the Firecracker log named-pipe should
	// be located.
	LogFifo string

	// LogLevel defines the verbosity of Firecracker logging.  Valid values are
	// "Error", "Warning", "Info", and "Debug", and are case-sensitive.
	LogLevel string

	// MetricsPath defines the file path where the Firecracker metrics
	// is located.
	MetricsPath string

	// MetricsFifo defines the file path where the Firecracker metrics
	// named-pipe should be located.
	MetricsFifo string

	// KernelImagePath defines the file path where the kernel image is located.
	// The kernel image must be an uncompressed ELF image.
	KernelImagePath string

	// InitrdPath defines the file path where initrd image is located.
	//
	// This parameter is optional.
	InitrdPath string

	// KernelArgs defines the command-line arguments that should be passed to
	// the kernel.
	KernelArgs string

	// Drives specifies BlockDevices that should be made available to the
	// microVM.
	Drives []models.Drive

	// NetworkInterfaces specifies the tap devices that should be made available
	// to the microVM.
	NetworkInterfaces NetworkInterfaces

	// FifoLogWriter is an io.Writer that is used to redirect the contents of the
	// fifo log to the writer.
	FifoLogWriter io.Writer

	// VsockDevices specifies the vsock devices that should be made available to
	// the microVM.
	VsockDevices []VsockDevice

	// MachineCfg represents the firecracker microVM process configuration
	MachineCfg models.MachineConfiguration

	// DisableValidation allows for easier mock testing by disabling the
	// validation of configuration performed by the SDK.
	DisableValidation bool

	// JailerCfg is configuration specific for the jailer process.
	JailerCfg *JailerConfig

	// (Optional) VMID is a unique identifier for this VM. It's set to a
	// random uuid if not provided by the user. It's used to set Firecracker's instance ID.
	// If CNI configuration is provided as part of NetworkInterfaces,
	// the VMID is used to set CNI ContainerID and create a network namespace path.
	VMID string

	// NetNS represents the path to a network namespace handle. If present, the
	// application will use this to join the associated network namespace
	NetNS string

	// ForwardSignals is an optional list of signals to catch and forward to
	// firecracker. If not provided, the default signals will be used.
	ForwardSignals []os.Signal

	// SeccompLevel specifies whether seccomp filters should be installed and how
	// restrictive they should be. Possible values are:
	//
	//	0 : (default): disabled.
	//	1 : basic filtering. This prohibits syscalls not whitelisted by Firecracker.
	//	2 : advanced filtering. This adds further checks on some of the
	//			parameters of the allowed syscalls.
	SeccompLevel SeccompLevelValue

	// MmdsAddress is IPv4 address used by guest applications when issuing requests to MMDS.
	// It is possible to use a valid IPv4 link-local address (169.254.0.0/16).
	// If not provided, the default address (169.254.169.254) will be used.
	MmdsAddress net.IP
}

Config is a collection of user-configurable VMM settings

func (*Config) Validate 

func (cfg *Config) Validate() error

Validate will ensure that the required fields are set and that the fields are valid values.

func (*Config) ValidateNetwork 

func (cfg *Config) ValidateNetwork() error

type CreateSnapshotOpt 

type CreateSnapshotOpt func(*ops.CreateSnapshotParams)

CreateSnapshotOpt is a functional option to be used for the CreateSnapshot API in setting any additional optional fields.

type CreateSyncActionOpt 

type CreateSyncActionOpt func(*ops.CreateSyncActionParams)

CreateSyncActionOpt is a functional option to be used for the CreateSyncAction API in setting any additional optional fields.

type DescribeInstanceOpt 

type DescribeInstanceOpt func(*ops.DescribeInstanceParams)

DescribeInstanceOpt is a functional option to be used for the DescribeInstance API for any additional optional fields

type DriveOpt 

type DriveOpt func(*models.Drive)

DriveOpt represents an optional function used to allow for specific customization of the models.Drive structure.

func WithDriveID 

func WithDriveID(id string) DriveOpt

WithDriveID sets the ID of the drive

func WithPartuuid 

func WithPartuuid(uuid string) DriveOpt

WithPartuuid sets the unique ID of the boot partition

func WithRateLimiter 

func WithRateLimiter(limiter models.RateLimiter) DriveOpt

WithRateLimiter sets the rate limitter of the drive

func WithReadOnly 

func WithReadOnly(flag bool) DriveOpt

WithReadOnly sets the drive read-only

type DrivesBuilder 

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

DrivesBuilder is a builder that will build an array of drives used to set up the firecracker microVM. The DriveID will be an incrementing number starting at one

Example 
drivesParams := []struct {
	Path     string
	ReadOnly bool
}{
	{
		Path:     "/first/path/drive.img",
		ReadOnly: true,
	},
	{
		Path:     "/second/path/drive.img",
		ReadOnly: false,
	},
}

// construct a new builder with the given rootfs path
b := firecracker.NewDrivesBuilder("/path/to/rootfs")
for _, param := range drivesParams {
	// add our additional drives
	b = b.AddDrive(param.Path, param.ReadOnly)
}

const socketPath = "/tmp/firecracker.sock"
cfg := firecracker.Config{
	SocketPath:      socketPath,
	KernelImagePath: "/path/to/kernel",
	// build our drives into the machine's configuration
	Drives: b.Build(),
	MachineCfg: models.MachineConfiguration{
		VcpuCount: firecracker.Int64(1),
	},
}

ctx := context.Background()
m, err := firecracker.NewMachine(ctx, cfg)
if err != nil {
	panic(fmt.Errorf("failed to create new machine: %v", err))
}

if err := m.Start(ctx); err != nil {
	panic(fmt.Errorf("failed to initialize machine: %v", err))
}

// wait for VMM to execute
if err := m.Wait(ctx); err != nil {
	panic(err)
}

Output:
Example (DriveOpt) 
drives := firecracker.NewDrivesBuilder("/path/to/rootfs").
	AddDrive("/path/to/drive1.img", true).
	AddDrive("/path/to/drive2.img", false, func(drive *models.Drive) {
		// set our custom bandwidth rate limiter
		drive.RateLimiter = &models.RateLimiter{
			Bandwidth: &models.TokenBucket{
				OneTimeBurst: firecracker.Int64(1024 * 1024),
				RefillTime:   firecracker.Int64(500),
				Size:         firecracker.Int64(1024 * 1024),
			},
		}
	}).
	Build()

const socketPath = "/tmp/firecracker.sock"
cfg := firecracker.Config{
	SocketPath:      socketPath,
	KernelImagePath: "/path/to/kernel",
	// build our drives into the machine's configuration
	Drives: drives,
	MachineCfg: models.MachineConfiguration{
		VcpuCount: firecracker.Int64(1),
	},
}

ctx := context.Background()
m, err := firecracker.NewMachine(ctx, cfg)
if err != nil {
	panic(fmt.Errorf("failed to create new machine: %v", err))
}

if err := m.Start(ctx); err != nil {
	panic(fmt.Errorf("failed to initialize machine: %v", err))
}

// wait for VMM to execute
if err := m.Wait(ctx); err != nil {
	panic(err)
}

Output:

func NewDrivesBuilder 

func NewDrivesBuilder(rootDrivePath string) DrivesBuilder

NewDrivesBuilder will return a new DrivesBuilder with a given rootfs.

func (DrivesBuilder) AddDrive 

func (b DrivesBuilder) AddDrive(path string, readOnly bool, opts ...DriveOpt) DrivesBuilder

AddDrive will add a new drive to the given builder.

func (DrivesBuilder) Build 

func (b DrivesBuilder) Build() []models.Drive

Build will construct an array of drives with the root drive at the very end.

func (DrivesBuilder) WithRootDrive 

func (b DrivesBuilder) WithRootDrive(rootDrivePath string, opts ...DriveOpt) DrivesBuilder

WithRootDrive will set the given builder with the a new root path. The root drive will be set to read and write by default.

type GetMachineConfigurationOpt 

type GetMachineConfigurationOpt func(*ops.GetMachineConfigurationParams)

GetMachineConfigurationOpt is a functional option to be used for the GetMachineConfiguration API in setting any additional optional fields.

type GetMmdsOpt 

type GetMmdsOpt func(*ops.GetMmdsParams)

GetMmdsOpt is a functional option to be used for the GetMmds API in setting any additional optional fields.

type Handler 

type Handler struct {
	Name string
	Fn   func(context.Context, *Machine) error
}

Handler represents a named handler that contains a name and a function which is used to execute during the initialization process of a machine.

func LinkFilesHandler 

func LinkFilesHandler(kernelImageFileName string) Handler

LinkFilesHandler creates a new link files handler that will link files to the rootfs

func NewCreateBalloonHandler 

func NewCreateBalloonHandler(amountMib int64, deflateOnOom bool, StatsPollingIntervals int64) Handler

NewCreateBalloonHandler is a named handler that put a memory balloon into the firecracker process.

func NewSetMetadataHandler 

func NewSetMetadataHandler(metadata interface{}) Handler

NewSetMetadataHandler is a named handler that puts the metadata into the firecracker process.

type HandlerList 

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

HandlerList represents a list of named handler that can be used to execute a flow of instructions for a given machine.

func (HandlerList) Append 

func (l HandlerList) Append(handlers ...Handler) HandlerList

Append will append a new handler to the handler list.

func (HandlerList) AppendAfter 

func (l HandlerList) AppendAfter(name string, handler Handler) HandlerList

AppendAfter will append a given handler after the specified handler.

func (HandlerList) Clear 

func (l HandlerList) Clear() HandlerList

Clear clears all named handler in the list.

func (HandlerList) Has 

func (l HandlerList) Has(name string) bool

Has will iterate through the handler list and check to see if the the named handler exists.

func (HandlerList) Len 

func (l HandlerList) Len() int

Len return the length of the given handler list

func (HandlerList) Prepend 

func (l HandlerList) Prepend(handlers ...Handler) HandlerList

Prepend will prepend a new set of handlers to the handler list

func (HandlerList) Remove 

func (l HandlerList) Remove(name string) HandlerList

Remove will return an updated handler with all instances of the specific named handler being removed.

func (HandlerList) Run 

func (l HandlerList) Run(ctx context.Context, m *Machine) error

Run will execute each instruction in the handler list. If an error occurs in any of the handlers, then the list will halt execution and return the error.

func (HandlerList) Swap 

func (l HandlerList) Swap(handler Handler) HandlerList

Swap will replace all elements of the given name with the new handler.

func (HandlerList) Swappend 

func (l HandlerList) Swappend(handler Handler) HandlerList

Swappend will either append, if there isn't an element within the handler list, otherwise it will replace all elements with the given name.

type Handlers 

type Handlers struct {
	Validation HandlerList
	FcInit     HandlerList
}

Handlers is a container that houses categories of handler lists.

func (Handlers) Run 

func (h Handlers) Run(ctx context.Context, m *Machine) error

Run will execute all handlers in the Handlers object by flattening the lists into a single list and running.

type HandlersAdapter 

type HandlersAdapter interface {
	AdaptHandlers(*Handlers) error
}

HandlersAdapter is an interface used to modify a given set of handlers.

type IPConfiguration 

type IPConfiguration struct {
	IPAddr      net.IPNet
	Gateway     net.IP
	Nameservers []string
	IfName      string
}

IPConfiguration specifies an IP, a gateway and DNS Nameservers that should be configured automatically within the VM upon boot. It currently only supports IPv4 addresses.

IPConfiguration can specify interface name, in that case config will be applied to the specified interface, if IfName is left blank, config applies to VM with a single network interface. The IPAddr and Gateway will be used to assign an IP a a default route for the VM's internal interface.

The first 2 nameservers will be configured in the /proc/net/pnp file in a format compatible with /etc/resolv.conf (any further nameservers are currently ignored). VMs that wish to use the nameserver settings here will thus typically need to make /etc/resolv.conf a symlink to /proc/net/pnp

type JailerCommandBuilder 

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

JailerCommandBuilder will build a jailer command. This can be used to specify that a jailed firecracker executable wants to be run on the Machine.

func NewJailerCommandBuilder 

func NewJailerCommandBuilder() JailerCommandBuilder

NewJailerCommandBuilder will return a new jailer command builder with the proper default value initialized.

func (JailerCommandBuilder) Args 

func (b JailerCommandBuilder) Args() []string

Args returns the specified set of args to be used in command construction.

func (JailerCommandBuilder) Bin 

func (b JailerCommandBuilder) Bin() string

Bin returns the jailer bin path. If bin path is empty, then the default path will be returned.

func (JailerCommandBuilder) Build 

func (b JailerCommandBuilder) Build(ctx context.Context) *exec.Cmd

Build will build a jailer command.

func (JailerCommandBuilder) Stderr 

func (b JailerCommandBuilder) Stderr() io.Writer

Stderr will return the stderr that will be used when creating the firecracker exec.Command

func (JailerCommandBuilder) Stdin 

func (b JailerCommandBuilder) Stdin() io.Reader

Stdin will return the stdin that will be used when creating the firecracker exec.Command

func (JailerCommandBuilder) Stdout 

func (b JailerCommandBuilder) Stdout() io.Writer

Stdout will return the stdout that will be used when creating the firecracker exec.Command

func (JailerCommandBuilder) WithBin 

func (b JailerCommandBuilder) WithBin(bin string) JailerCommandBuilder

WithBin will set the specific bin path to the builder.

func (JailerCommandBuilder) WithChrootBaseDir 

func (b JailerCommandBuilder) WithChrootBaseDir(path string) JailerCommandBuilder

WithChrootBaseDir will set the given path as the chroot base directory. This specifies where chroot jails are built and defaults to /srv/jailer.

func (JailerCommandBuilder) WithDaemonize 

func (b JailerCommandBuilder) WithDaemonize(daemonize bool) JailerCommandBuilder

WithDaemonize will specify whether to set stdio to /dev/null

func (JailerCommandBuilder) WithExecFile 

func (b JailerCommandBuilder) WithExecFile(path string) JailerCommandBuilder

WithExecFile will set the specified path to the builder. This represents a firecracker binary used when calling the jailer.

func (JailerCommandBuilder) WithFirecrackerArgs 

func (b JailerCommandBuilder) WithFirecrackerArgs(args ...string) JailerCommandBuilder

WithFirecrackerArgs will adds these arguments to the end of the argument chain which the jailer will intepret to belonging to Firecracke

func (JailerCommandBuilder) WithGID 

func (b JailerCommandBuilder) WithGID(gid int) JailerCommandBuilder

WithGID will set the specified gid to the builder.

func (JailerCommandBuilder) WithID 

func (b JailerCommandBuilder) WithID(id string) JailerCommandBuilder

WithID will set the specified id to the builder.

func (JailerCommandBuilder) WithNetNS 

func (b JailerCommandBuilder) WithNetNS(path string) JailerCommandBuilder

WithNetNS will set the given path to the net namespace of the builder. This represents the path to a network namespace handle and will be used to join the associated network namepsace.

func (JailerCommandBuilder) WithNumaNode 

func (b JailerCommandBuilder) WithNumaNode(node int) JailerCommandBuilder

WithNumaNode uses the specfied node for the jailer. This represents the numa node that the process will get assigned to.

func (JailerCommandBuilder) WithStderr 

func (b JailerCommandBuilder) WithStderr(stderr io.Writer) JailerCommandBuilder

WithStderr specifies which io.Writer to use in place of the os.Stderr in the firecracker exec.Command.

func (JailerCommandBuilder) WithStdin 

func (b JailerCommandBuilder) WithStdin(stdin io.Reader) JailerCommandBuilder

WithStdin specifies which io.Reader to use in place of the os.Stdin in the firecracker exec.Command.

func (JailerCommandBuilder) WithStdout 

func (b JailerCommandBuilder) WithStdout(stdout io.Writer) JailerCommandBuilder

WithStdout specifies which io.Writer to use in place of the os.Stdout in the firecracker exec.Command.

func (JailerCommandBuilder) WithUID 

func (b JailerCommandBuilder) WithUID(uid int) JailerCommandBuilder

WithUID will set the specified uid to the builder.

type JailerConfig 

type JailerConfig struct {
	// GID the jailer switches to as it execs the target binary.
	GID *int

	// UID the jailer switches to as it execs the target binary.
	UID *int

	// ID is the unique VM identification string, which may contain alphanumeric
	// characters and hyphens. The maximum id length is currently 64 characters
	ID string

	// NumaNode represents the NUMA node the process gets assigned to.
	NumaNode *int

	// ExecFile is the path to the Firecracker binary that will be exec-ed by
	// the jailer. The user can provide a path to any binary, but the interaction
	// with the jailer is mostly Firecracker specific.
	ExecFile string

	// JailerBinary specifies the jailer binary to be used for setting up the
	// Firecracker VM jail. If the value contains no path separators, it will
	// use the PATH environment variable to get the absolute path of the binary.
	// If the value contains path separators, the value will be used directly
	// to exec the jailer. This follows the same conventions as Golang's
	// os/exec.Command.
	//
	// If not specified it defaults to "jailer".
	JailerBinary string

	// ChrootBaseDir represents the base folder where chroot jails are built. The
	// default is /srv/jailer
	ChrootBaseDir string

	//  Daemonize is set to true, call setsid() and redirect STDIN, STDOUT, and
	//  STDERR to /dev/null
	Daemonize bool

	// ChrootStrategy will dictate how files are transfered to the root drive.
	ChrootStrategy HandlersAdapter

	// Stdout specifies the IO writer for STDOUT to use when spawning the jailer.
	Stdout io.Writer
	// Stderr specifies the IO writer for STDERR to use when spawning the jailer.
	Stderr io.Writer
	// Stdin specifies the IO reader for STDIN to use when spawning the jailer.
	Stdin io.Reader
}

JailerConfig is jailer specific configuration needed to execute the jailer.

Example (EnablingJailer) 
ctx := context.Background()
vmmCtx, vmmCancel := context.WithCancel(ctx)
defer vmmCancel()

const id = "my-jailer-test"
const path = "/path/to/jailer-workspace"
const kernelImagePath = "/path/to/kernel-image"

uid := 123
gid := 100

fcCfg := firecracker.Config{
	SocketPath:      "api.socket",
	KernelImagePath: kernelImagePath,
	KernelArgs:      "console=ttyS0 reboot=k panic=1 pci=off",
	Drives:          firecracker.NewDrivesBuilder("/path/to/rootfs").Build(),
	LogLevel:        "Debug",
	MachineCfg: models.MachineConfiguration{
		VcpuCount:  firecracker.Int64(1),
		HtEnabled:  firecracker.Bool(false),
		MemSizeMib: firecracker.Int64(256),
	},
	JailerCfg: &firecracker.JailerConfig{
		UID:            &uid,
		GID:            &gid,
		ID:             id,
		NumaNode:       firecracker.Int(0),
		ChrootBaseDir:  path,
		ChrootStrategy: firecracker.NewNaiveChrootStrategy(kernelImagePath),
		ExecFile:       "/path/to/firecracker-binary",
	},
}

// Check if kernel image is readable
f, err := os.Open(fcCfg.KernelImagePath)
if err != nil {
	panic(fmt.Errorf("Failed to open kernel image: %v", err))
}
f.Close()

// Check each drive is readable and writable
for _, drive := range fcCfg.Drives {
	drivePath := firecracker.StringValue(drive.PathOnHost)
	f, err := os.OpenFile(drivePath, os.O_RDWR, 0666)
	if err != nil {
		panic(fmt.Errorf("Failed to open drive with read/write permissions: %v", err))
	}
	f.Close()
}

logger := log.New()
m, err := firecracker.NewMachine(vmmCtx, fcCfg, firecracker.WithLogger(log.NewEntry(logger)))
if err != nil {
	panic(err)
}

if err := m.Start(vmmCtx); err != nil {
	panic(err)
}
defer m.StopVMM()

// wait for the VMM to exit
if err := m.Wait(vmmCtx); err != nil {
	panic(err)
}

Output:

type LoadSnapshotOpt 

type LoadSnapshotOpt func(*ops.LoadSnapshotParams)

LoadSnapshotOpt is a functional option to be used for the LoadSnapshot API in setting any additional optional fields.

type Machine 

type Machine struct {
	// Handlers holds the set of handlers that are run for validation and start
	Handlers Handlers

	Cfg Config
	// contains filtered or unexported fields
}

Machine is the main object for manipulating Firecracker microVMs

func NewMachine 

func NewMachine(ctx context.Context, cfg Config, opts ...Opt) (*Machine, error)

NewMachine initializes a new Machine instance and performs validation of the provided Config.

func (*Machine) CreateBalloon 

func (m *Machine) CreateBalloon(ctx context.Context, amountMib int64, deflateOnOom bool, statsPollingIntervals int64, opts ...PutBalloonOpt) error

CreateBalloon creates a balloon device if one does not exist

func (*Machine) CreateSnapshot 

func (m *Machine) CreateSnapshot(ctx context.Context, memFilePath, snapshotPath string, opts ...CreateSnapshotOpt) error

CreateSnapshot creates a snapshot of the VM

func (*Machine) DescribeInstanceInfo 

func (m *Machine) DescribeInstanceInfo(ctx context.Context) (models.InstanceInfo, error)

func (*Machine) GetBalloonConfig 

func (m *Machine) GetBalloonConfig(ctx context.Context) (models.Balloon, error)

GetBalloonConfig gets the current balloon device configuration.

func (*Machine) GetBalloonStats 

func (m *Machine) GetBalloonStats(ctx context.Context) (models.BalloonStats, error)

GetBalloonStats gets the latest balloon device statistics, only if enabled pre-boot.

func (*Machine) GetMetadata 

func (m *Machine) GetMetadata(ctx context.Context, v interface{}) error

GetMetadata gets the machine's metadata from MDDS and unmarshals it into v

func (*Machine) LoadSnapshot 

func (m *Machine) LoadSnapshot(ctx context.Context, memFilePath, snapshotPath string, opts ...LoadSnapshotOpt) error

LoadSnapshot load a snapshot

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.Entry

Logger returns a logrus logger appropriate for logging hypervisor messages

func (*Machine) PID 

func (m *Machine) PID() (int, error)

PID returns the machine's running process PID or an error if not running

func (*Machine) PauseVM 

func (m *Machine) PauseVM(ctx context.Context, opts ...PatchVMOpt) error

PauseVM pauses the VM

func (*Machine) ResumeVM 

func (m *Machine) ResumeVM(ctx context.Context, opts ...PatchVMOpt) error

ResumeVM resumes the VM

func (*Machine) SetMetadata 

func (m *Machine) SetMetadata(ctx context.Context, metadata interface{}) error

SetMetadata sets the machine's metadata for MDDS

func (*Machine) Shutdown 

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

Shutdown requests a clean shutdown of the VM by sending CtrlAltDelete on the virtual keyboard

func (*Machine) Start 

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

Start actually start a Firecracker microVM. The context must not be cancelled while the microVM is running.

It will iterate through the handler list and call each handler. If an error occurred during handler execution, that error will be returned. If the handlers succeed, then this will start the VMM instance. Start may only be called once per Machine. Subsequent calls will return ErrAlreadyStarted.

func (*Machine) StopVMM 

func (m *Machine) StopVMM() error

StopVMM stops the current VMM.

func (*Machine) UpdateBalloon 

func (m *Machine) UpdateBalloon(ctx context.Context, amountMib int64, opts ...PatchBalloonOpt) error

UpdateBalloon will update an existing balloon device, before or after machine startup

func (*Machine) UpdateBalloonStats 

func (m *Machine) UpdateBalloonStats(ctx context.Context, statsPollingIntervals int64, opts ...PatchBalloonStatsIntervalOpt) error

UpdateBalloon will update a balloon device statistics polling interval. Statistics cannot be turned on/off after boot.

func (*Machine) UpdateGuestDrive 

func (m *Machine) UpdateGuestDrive(ctx context.Context, driveID, pathOnHost string, opts ...PatchGuestDriveByIDOpt) error

UpdateGuestDrive will modify the current guest drive of ID index with the new parameters of the partialDrive.

func (*Machine) UpdateGuestNetworkInterfaceRateLimit 

func (m *Machine) UpdateGuestNetworkInterfaceRateLimit(ctx context.Context, ifaceID string, rateLimiters RateLimiterSet, opts ...PatchGuestNetworkInterfaceByIDOpt) error

UpdateGuestNetworkInterfaceRateLimit modifies the specified network interface's rate limits

func (*Machine) UpdateMetadata 

func (m *Machine) UpdateMetadata(ctx context.Context, metadata interface{}) error

UpdateMetadata patches the machine's metadata for MDDS

func (*Machine) Wait 

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

Wait will wait until the firecracker process has finished. Wait is safe to call concurrently, and will deliver the same error to all callers, subject to each caller's context cancellation.

func (*Machine) WaitForSocket 

func (m *Machine) WaitForSocket(timeout time.Duration, exitchan chan error) error

WaitForSocket waits for the given file to exist

type MachineIface 

type MachineIface interface {
	Start(context.Context) error
	StopVMM() error
	Shutdown(context.Context) error
	Wait(context.Context) error
	SetMetadata(context.Context, interface{}) error
	UpdateGuestDrive(context.Context, string, string, ...PatchGuestDriveByIDOpt) error
	UpdateGuestNetworkInterfaceRateLimit(context.Context, string, RateLimiterSet, ...PatchGuestNetworkInterfaceByIDOpt) error
}

MachineIface can be used for mocking and testing of the Machine. The Machine is subject to change, meaning this interface would change.

type NaiveChrootStrategy 

type NaiveChrootStrategy struct {
	Rootfs          string
	KernelImagePath string
}

NaiveChrootStrategy will simply hard link all files, drives and kernel image, to the root drive.

func NewNaiveChrootStrategy 

func NewNaiveChrootStrategy(kernelImagePath string) NaiveChrootStrategy

NewNaiveChrootStrategy returns a new NaivceChrootStrategy

func (NaiveChrootStrategy) AdaptHandlers 

func (s NaiveChrootStrategy) AdaptHandlers(handlers *Handlers) error

AdaptHandlers will inject the LinkFilesHandler into the handler list.

type NetworkInterface 

type NetworkInterface struct {
	// StaticConfiguration parameters that will be used to configure the VM's
	// tap device and internal network for this network interface.
	StaticConfiguration *StaticNetworkConfiguration

	// CNIConfiguration that will be used to generate the VM's network namespace,
	// tap device and internal network for this network interface.
	CNIConfiguration *CNIConfiguration

	// AllowMMDS makes the Firecracker MMDS available on this network interface.
	AllowMMDS bool

	// InRateLimiter limits the incoming bytes.
	InRateLimiter *models.RateLimiter

	// OutRateLimiter limits the outgoing bytes.
	OutRateLimiter *models.RateLimiter
}

NetworkInterface represents a Firecracker microVM's network interface. It can be configured either with static parameters set via StaticConfiguration or via CNI as set via CNIConfiguration. It is currently an error to specify both static and CNI configuration.

Example (RateLimiting) 
// construct the limitations of the bandwidth for firecracker
bandwidthBuilder := firecracker.TokenBucketBuilder{}.
	WithInitialSize(1024 * 1024).        // Initial token amount
	WithBucketSize(1024 * 1024).         // Max number of tokens
	WithRefillDuration(30 * time.Second) // Refill rate

// construct the limitations of the number of operations per duration for firecracker
opsBuilder := firecracker.TokenBucketBuilder{}.
	WithInitialSize(5).
	WithBucketSize(5).
	WithRefillDuration(5 * time.Second)

// create the inbound rate limiter
inbound := firecracker.NewRateLimiter(bandwidthBuilder.Build(), opsBuilder.Build())

bandwidthBuilder = bandwidthBuilder.WithBucketSize(1024 * 1024 * 10)
opsBuilder = opsBuilder.
	WithBucketSize(100).
	WithInitialSize(100)
// create the outbound rate limiter
outbound := firecracker.NewRateLimiter(bandwidthBuilder.Build(), opsBuilder.Build())

networkIfaces := []firecracker.NetworkInterface{{
	StaticConfiguration: &firecracker.StaticNetworkConfiguration{
		MacAddress:  "01-23-45-67-89-AB-CD-EF",
		HostDevName: "tap-name",
	},
	InRateLimiter:  inbound,
	OutRateLimiter: outbound,
}}

cfg := firecracker.Config{
	SocketPath:      "/path/to/socket",
	KernelImagePath: "/path/to/kernel",
	Drives:          firecracker.NewDrivesBuilder("/path/to/rootfs").Build(),
	MachineCfg: models.MachineConfiguration{
		VcpuCount: firecracker.Int64(1),
	},
	NetworkInterfaces: networkIfaces,
}

ctx := context.Background()
m, err := firecracker.NewMachine(ctx, cfg)
if err != nil {
	panic(fmt.Errorf("failed to create new machine: %v", err))
}

defer os.Remove(cfg.SocketPath)

if err := m.Start(ctx); err != nil {
	panic(fmt.Errorf("failed to initialize machine: %v", err))
}

// wait for VMM to execute
if err := m.Wait(ctx); err != nil {
	panic(err)
}

Output:

type NetworkInterfaces 

type NetworkInterfaces []NetworkInterface

NetworkInterfaces is a slice of NetworkInterface objects that a VM will be configured to use.

type Opt 

type Opt func(*Machine)

Opt represents a functional option to help modify functionality of a Machine.

func WithClient 

func WithClient(client *Client) Opt

WithClient will use the client in place rather than the client constructed during bootstrapping of the machine. This option is useful for mocking out tests.

func WithLogger 

func WithLogger(logger *logrus.Entry) Opt

WithLogger will allow for the Machine to use the provided logger.

func WithProcessRunner 

func WithProcessRunner(cmd *exec.Cmd) Opt

WithProcessRunner will allow for a specific command to be run instead of the default firecracker command. For example, this could be used to instead call the jailer instead of firecracker directly.

Example (Logging) 
const socketPath = "/tmp/firecracker.sock"

cfg := firecracker.Config{
	SocketPath:      socketPath,
	KernelImagePath: "/path/to/kernel",
	Drives:          firecracker.NewDrivesBuilder("/path/to/rootfs").Build(),
	MachineCfg: models.MachineConfiguration{
		VcpuCount: firecracker.Int64(1),
	},
}

// stdout will be directed to this file
stdoutPath := "/tmp/stdout.log"
stdout, err := os.OpenFile(stdoutPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
if err != nil {
	panic(fmt.Errorf("failed to create stdout file: %v", err))
}

// stderr will be directed to this file
stderrPath := "/tmp/stderr.log"
stderr, err := os.OpenFile(stderrPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
if err != nil {
	panic(fmt.Errorf("failed to create stderr file: %v", err))
}

ctx := context.Background()
// build our custom command that contains our two files to
// write to during process execution
cmd := firecracker.VMCommandBuilder{}.
	WithBin("firecracker").
	WithSocketPath(socketPath).
	WithStdout(stdout).
	WithStderr(stderr).
	Build(ctx)

m, err := firecracker.NewMachine(ctx, cfg, firecracker.WithProcessRunner(cmd))
if err != nil {
	panic(fmt.Errorf("failed to create new machine: %v", err))
}

defer os.Remove(cfg.SocketPath)

if err := m.Start(ctx); err != nil {
	panic(fmt.Errorf("failed to initialize machine: %v", err))
}

// wait for VMM to execute
if err := m.Wait(ctx); err != nil {
	panic(err)
}

Output:

type PatchBalloonOpt 

type PatchBalloonOpt func(*ops.PatchBalloonParams)

PatchBalloonOpt is a functional option to be used for the PatchBalloon API in setting any additional optional fields.

type PatchBalloonStatsIntervalOpt 

type PatchBalloonStatsIntervalOpt func(*ops.PatchBalloonStatsIntervalParams)

PatchBalloonStatsIntervalOpt is a functional option to be used for the PatchBalloonStatsInterval API in setting any additional optional fields.

type PatchGuestDriveByIDOpt 

type PatchGuestDriveByIDOpt func(*ops.PatchGuestDriveByIDParams)

PatchGuestDriveByIDOpt is a functional option to be used for the PutMmds API in setting any additional optional fields.

type PatchGuestNetworkInterfaceByIDOpt 

type PatchGuestNetworkInterfaceByIDOpt func(*ops.PatchGuestNetworkInterfaceByIDParams)

PatchGuestNetworkInterfaceByIDOpt is a functional option to be used for the PatchGuestNetworkInterfaceByID API in setting any additional optional fields.

type PatchMmdsOpt 

type PatchMmdsOpt func(*ops.PatchMmdsParams)

PatchMmdsOpt is a functional option to be used for the GetMmds API in setting any additional optional fields.

type PatchVMOpt 

type PatchVMOpt func(*ops.PatchVMParams)

PatchVMOpt is a functional option to be used for the PatchVM API in setting any additional optional fields.

type PutBalloonOpt 

type PutBalloonOpt func(*ops.PutBalloonParams)

PutBalloonOpt is a functional option to be used for the PutBalloon API in setting any additional optional fields.

type PutGuestBootSourceOpt 

type PutGuestBootSourceOpt func(*ops.PutGuestBootSourceParams)

PutGuestBootSourceOpt is a functional option to be used for the PutGuestBootSource API in setting any additional optional fields.

type PutGuestDriveByIDOpt 

type PutGuestDriveByIDOpt func(*ops.PutGuestDriveByIDParams)

PutGuestDriveByIDOpt is a functional option to be used for the PutGuestDriveByID API in setting any additional optional fields.

type PutGuestNetworkInterfaceByIDOpt 

type PutGuestNetworkInterfaceByIDOpt func(*ops.PutGuestNetworkInterfaceByIDParams)

PutGuestNetworkInterfaceByIDOpt is a functional option to be used for the PutGuestNetworkInterfaceByID API in setting any additional optional fields.

type PutGuestVsockOpt 

type PutGuestVsockOpt func(params *ops.PutGuestVsockParams)

PutGuestVsockOpt is a functional option to be used for the PutGuestVsock API in setting any additional optional fields.

type PutLoggerOpt 

type PutLoggerOpt func(*ops.PutLoggerParams)

PutLoggerOpt is a functional option to be used for the PutLogger API in setting any additional optional fields.

type PutMachineConfigurationOpt 

type PutMachineConfigurationOpt func(*ops.PutMachineConfigurationParams)

PutMachineConfigurationOpt is a functional option to be used for the PutMachineConfiguration API in setting any additional optional fields.

type PutMetricsOpt 

type PutMetricsOpt func(*ops.PutMetricsParams)

PutMetricsOpt is a functional option to be used for the PutMetrics API in setting any additional optional fields.

type PutMmdsOpt 

type PutMmdsOpt func(*ops.PutMmdsParams)

PutMmdsOpt is a functional option to be used for the PutMmds API in setting any additional optional fields.

type RateLimiterOpt 

type RateLimiterOpt func(*models.RateLimiter)

RateLimiterOpt represents a functional option for rate limiting construction

type RateLimiterSet 

type RateLimiterSet struct {
	// InRateLimiter limits the incoming bytes.
	InRateLimiter *models.RateLimiter
	// OutRateLimiter limits the outgoing bytes.
	OutRateLimiter *models.RateLimiter
}

RateLimiterSet represents a pair of RateLimiters (inbound and outbound)

type SeccompLevelValue 

type SeccompLevelValue int

SeccompLevelValue represents a secure computing level type. 

const (
	// SeccompLevelDisable is the default value.
	SeccompLevelDisable SeccompLevelValue = iota
	// SeccompLevelBasic prohibits syscalls not whitelisted by Firecracker.
	SeccompLevelBasic
	// SeccompLevelAdvanced adds further checks on some of the parameters of the
	// allowed syscalls.
	SeccompLevelAdvanced
)

secure computing levels

func (SeccompLevelValue) String 

func (level SeccompLevelValue) String() string

type StaticNetworkConfiguration 

type StaticNetworkConfiguration struct {
	// MacAddress defines the MAC address that should be assigned to the network
	// interface inside the microVM.
	MacAddress string

	// HostDevName is the name of the tap device the VM will use
	HostDevName string

	// IPConfiguration (optional) allows a static IP, gateway and up to 2 DNS nameservers
	// to be automatically configured within the VM upon startup.
	IPConfiguration *IPConfiguration
}

StaticNetworkConfiguration allows a network interface to be defined via static parameters (as contrasted with parameters autogenerated from CNI).

type TokenBucketBuilder 

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

TokenBucketBuilder is a builder that allows of building components of the models.RateLimiter structure.

func (TokenBucketBuilder) Build 

func (b TokenBucketBuilder) Build() models.TokenBucket

Build will return a new token bucket

func (TokenBucketBuilder) WithBucketSize 

func (b TokenBucketBuilder) WithBucketSize(size int64) TokenBucketBuilder

WithBucketSize will set the bucket size for the given token bucket

func (TokenBucketBuilder) WithInitialSize 

func (b TokenBucketBuilder) WithInitialSize(size int64) TokenBucketBuilder

WithInitialSize will set the initial token bucket size

func (TokenBucketBuilder) WithRefillDuration 

func (b TokenBucketBuilder) WithRefillDuration(dur time.Duration) TokenBucketBuilder

WithRefillDuration will set the given refill duration of the bucket fill rate.

type VMCommandBuilder 

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

VMCommandBuilder is a utility for building an exec.Cmd that represents how to start the Firecracker VMM.

func (VMCommandBuilder) AddArgs 

func (b VMCommandBuilder) AddArgs(args ...string) VMCommandBuilder

AddArgs will append the provided args to the given command

func (VMCommandBuilder) Args 

func (b VMCommandBuilder) Args() []string

Args returns all args that will be passed to exec.Command

func (VMCommandBuilder) Bin 

func (b VMCommandBuilder) Bin() string

Bin returns the bin that was set. If bin had not been set, then the default will be returned.

func (VMCommandBuilder) Build 

func (b VMCommandBuilder) Build(ctx context.Context) *exec.Cmd

Build will build a firecracker command using the specific arguments specified in the builder.

func (VMCommandBuilder) SocketPath 

func (b VMCommandBuilder) SocketPath() []string

SocketPath returns the specified socket path

func (VMCommandBuilder) Stderr 

func (b VMCommandBuilder) Stderr() io.Writer

Stderr will return the stderr that will be used when creating the firecracker exec.Command

func (VMCommandBuilder) Stdin 

func (b VMCommandBuilder) Stdin() io.Reader

Stdin will return the stdin that will be used when creating the firecracker exec.Command

func (VMCommandBuilder) Stdout 

func (b VMCommandBuilder) Stdout() io.Writer

Stdout will return the stdout that will be used when creating the firecracker exec.Command

func (VMCommandBuilder) WithArgs 

func (b VMCommandBuilder) WithArgs(args []string) VMCommandBuilder

WithArgs specifies which arguments to pass through to the firecracker exec.Command

func (VMCommandBuilder) WithBin 

func (b VMCommandBuilder) WithBin(bin string) VMCommandBuilder

WithBin specifies which binary for firecracker to use

func (VMCommandBuilder) WithSocketPath 

func (b VMCommandBuilder) WithSocketPath(path string) VMCommandBuilder

WithSocketPath specifies the socket path to be used when creating the firecracker exec.Command

func (VMCommandBuilder) WithStderr 

func (b VMCommandBuilder) WithStderr(stderr io.Writer) VMCommandBuilder

WithStderr specifies which io.Writer to use in place of the os.Stderr in the firecracker exec.Command.

func (VMCommandBuilder) WithStdin 

func (b VMCommandBuilder) WithStdin(stdin io.Reader) VMCommandBuilder

WithStdin specifies which io.Reader to use in place of the os.Stdin in the firecracker exec.Command.

func (VMCommandBuilder) WithStdout 

func (b VMCommandBuilder) WithStdout(stdout io.Writer) VMCommandBuilder

WithStdout specifies which io.Writer to use in place of the os.Stdout in the firecracker exec.Command.

type VsockDevice 

type VsockDevice struct {
	// ID defines the vsock's device ID for firecracker.
	ID string
	// Path defines the filesystem path of the vsock device on the host.
	Path string
	// CID defines the 32-bit Context Identifier for the vsock device.  See
	// the vsock(7) manual page for more information.
	CID uint32
}

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

Source Files

View all Source files

Directories

Path Synopsis
models
operations
cni
internal
vmconf
Package vmconf defines an interface for converting particular CNI invocation results to networking configuration usable by a VM.
 Package vmconf defines an interface for converting particular CNI invocation results to networking configuration usable by a VM.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.