docs/dev-machine-setup.md
Firecracker uses KVM for the actual resource virtualization, hence setting up a development environment requires either a bare-metal machine (with hardware virtualization), or a virtual machine that supports nested virtualization. The different options are outlined below. Once the environment is set up, one can continue with the specific steps of setting up Firecracker (e.g., as outlined in the Getting Started instructions).
[TODO]
Note that Firecracker development on macOS has no hard dependency on VMware Fusion or Ubuntu. All that is required is a Linux VM that supports nested virtualization. This is but one example of that setup:
.vmwarevm file if
prompted.sudo apt install curl -y to install cURL.Firecracker development environment on AWS can be setup using bare metal instances. Follow these steps to create a bare metal instance.
If you don't already have an AWS account, create one using the AWS Portal.
Login to AWS console. You must
select a region that offers bare metal EC2 instances. To check which regions
support bare-metal, visit
Amazon EC2 On-Demand Pricing
and look for *.metal instance types.
Click on Launch a virtual machine in Build Solution section.
Firecracker requires a relatively new kernel, so you should use a recent
Linux distribution - such as
Ubuntu Server 22.04 LTS (HVM), SSD Volume Type.
In Step 2, scroll to the bottom and select c5.metal instance type. Click
on Next: Configure Instance Details.
In Step 3, click on Next: Add Storage.
In Step 4, click on Next: Add Tags.
In Step 5, click on Next: Configure Security Group.
In Step 6, take the default security group. This opens up port 22 and is
needed so that you can ssh into the machine later. Click on
Review and Launch.
Verify the details and click on Launch. If you do not have an existing key
pair, then you can select Create a new key pair to create a key pair. This
is needed so that you can use it later to ssh into the machine.
Click on the instance id in the green box. Copy Public DNS from the
Description tab of the selected instance.
Login to the newly created instance:
ssh -i <ssh-key> ubuntu@<public-ip>
Now you can continue with the Firecracker Getting Started instructions to use Firecracker to create a microVM.
One of the options to set up Firecracker for development purposes is to use a VM on Google Compute Engine (GCE), which supports nested virtualization and allows to run KVM. If you don't have a Google Cloud Platform (GCP) account, you can find brief instructions in the Addendum below.
Here is a brief summary of steps to create such a setup (full instructions to set up a Ubuntu-based VM on GCE with nested KVM enablement can be found in GCE documentation).
Select a GCP project and zone
$ FC_PROJECT=your_name-firecracker
$ FC_REGION=us-east1
$ FC_ZONE=us-east1-b
For convenience, give the project a unique name (e.g., your_name-firecracker), so that GCP does not need to create a project id different than project name (by appending randomized numbers to the name you provide).
$ gcloud projects create ${FC_PROJECT} --enable-cloud-apis --set-as-default
$ gcloud config set project ${FC_PROJECT}
$ gcloud config set compute/region ${FC_REGION}
$ gcloud config set compute/zone ${FC_ZONE}
The next step is to create a VM image able to run nested KVM (as outlined here).
Now we create the VM:
Keep in mind that you will need an instance type that supports nested
virtualization. E2 and N2D instances will not work. If you want to use a
N1 instance (default in some regions), make sure it uses at least a
processor of the Haswell architecture by specifying
--min-cpu-platform="Intel Haswell" when you create the instance.
Alternatively, use N2 instances (such as with
--machine-type="n2-standard-2").
$ FC_VM=firecracker-vm
$ gcloud compute instances create ${FC_VM} --enable-nested-virtualization \
--zone=${FC_ZONE} --min-cpu-platform="Intel Haswell" \
--machine-type=n1-standard-2
Connect to the VM via SSH.
$ gcloud compute ssh ${FC_VM}
When doing it for the first time, a key-pair will be created for you (you will be propmpted for a passphrase - can just keep it empty) and uploaded to GCE. Done! You should see the prompt of the new VM:
[YOUR_USER_NAME]@firecracker-vm:~$
Verify that VMX is enabled, enable KVM
$ grep -cw vmx /proc/cpuinfo
1
$ apt-get update
$ apt-get install acl
$ sudo setfacl -m u:${USER}:rw /dev/kvm
$ [ -r /dev/kvm ] && [ -w /dev/kvm ] && echo "OK" || echo "FAIL"
OK
Depending on your machine you will get a different number, but anything except 0
means KVM is enabled.
Now you can continue with the Firecracker Getting Started instructions to install and configure Firecracker in the new VM.
In a nutshell, setting up a GCP account involves the following steps:
Log in to GCP console with your Google credentials. If you don't have account, you will be prompted to join the trial.
Install GCP CLI & SDK (full instructions can be found here).
$ export CLOUD_SDK_REPO="cloud-sdk-$(lsb_release -c -s)"
$ echo "deb http://packages.cloud.google.com/apt $CLOUD_SDK_REPO main" \
| sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
$ curl https://packages.cloud.google.com/apt/doc/apt-key.gpg \
| sudo apt-key add -
$ sudo apt-get update && sudo apt-get install -y google-cloud-sdk
Configure the gcloud CLI by running:
$ gcloud init --console-only
Follow the prompts to authenticate (open the provided link, authenticate, copy the token back to console) and select the default project.
[TODO]