A basic Go interface to the Firecracker API

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.23 or later 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.