Class FirecrackerMicroVM

Represents a firecracker microVM instance.

Before calling any API methods, ensure that the firecracker process is spawned using spawnFirecrackerProcess().
After finishing with the instance, call stopFirecrackerProcess() to clean up the process.

Note

This makes API calls for each configuration change. Use FirecrackerLauncher for easier microVM setup.

Hierarchy (View Summary)

FirecrackerAPIClient
- FirecrackerMicroVM

Index

Constructors

constructor

new FirecrackerMicroVM(initParams?: FirecrackerInitParams): FirecrackerMicroVM
Initializes the configuration for Firecracker instance. It does not start the microVM (or firecracker process) yet.

To actually start the microVM, call spawnFirecrackerProcess().
Parameters
- OptionalinitParams: FirecrackerInitParams
  the initialization parameters for the Firecracker process
Returns FirecrackerMicroVM
Overrides FirecrackerAPIClient.constructor
- Defined in core/firecracker-microvm.ts:34

Properties

`Protected` `Optional`firecrackerProcess

firecrackerProcess?: ChildProcess

The spawned Firecracker process.

`Protected`initParams

initParams: FirecrackerInitParams = DefaultFirecrackerInitParams

Initialization parameters for the Firecracker process. Defaults are taken from DefaultFirecrackerInitParams.

`Protected`undiciClient

undiciClient: Client

The Undici HTTP client configured to connect over the provided Unix socket.

Methods

`Protected`buildFirecrackerArgs

buildFirecrackerArgs(): string[]
Builds the command line arguments array for the Firecracker binary based on initParams. This follows the same logic as the Rust ArgParser in the Firecracker source.

Returns string[]
See
https://github.com/firecracker-microvm/firecracker/blob/f0691f8253d4bde225b9f70ecabf39b7ad796935/src/firecracker/src/main.rs#L144
- Defined in core/firecracker-microvm.ts:53

createOrUpdateDrive

createOrUpdateDrive(drive: Drive): Promise<void>
Creates new drive with ID specified by drive_id or updates existing drive. This works pre-boot only. Will fail if update is not possible.
Parameters
- drive: Drive
  Guest drive properties
Returns Promise<void>
Inherited from FirecrackerAPIClient.createOrUpdateDrive
- Defined in api/api-client.ts:156

getInstanceInfo

getInstanceInfo(): Promise<InstanceInfo>
Returns general information about an instance

Returns Promise<InstanceInfo>
the instance information

Throws
with the fault_message from the API
Inherited from FirecrackerAPIClient.getInstanceInfo
- Defined in api/api-client.ts:97

getMachineConfiguration

getMachineConfiguration(): Promise<MachineConfiguration>
Gets the machine configuration of the VM. When called before the PUT operation, it will return the default values for the vCPU count (=1), memory size (=128 MiB). By default SMT is disabled and there is no CPU Template.

Returns Promise<MachineConfiguration>
the machine configuration

Throws
with the fault_message from the API
Inherited from FirecrackerAPIClient.getMachineConfiguration
- Defined in api/api-client.ts:193

`Protected`jsonRequest

jsonRequest<ResponseBodyType extends object>(
options: RequestOptions,
validStatusCodes: number[],
): Promise<ResponseBodyType>
- Attempts to parse response body as JSON.
- Calls request() internally
Type Parameters
- ResponseBodyType extends object
Parameters
- options: RequestOptions
- validStatusCodes: number[]
Returns Promise<ResponseBodyType>
Inherited from FirecrackerAPIClient.jsonRequest
- Defined in api/api-client.ts:72

`Protected`noContentRequest

noContentRequest(
options: RequestOptions,
validStatusCodes: number[],
): Promise<void>
- Does not attempt to parse response body.
- Calls request() internally
Parameters
- options: RequestOptions
- validStatusCodes: number[]
Returns Promise<void>
Inherited from FirecrackerAPIClient.noContentRequest
- Defined in api/api-client.ts:85

partiallyUpdateMachineConfiguration

partiallyUpdateMachineConfiguration(
machineConfig: Partial<MachineConfiguration>,
): Promise<void>
Partially updates the Machine Configuration of the VM. Pre-boot only.
- If any of the parameters has an incorrect value, the whole update fails.
- Same as setMachineConfig, expect that this accepts partial updates. Kept for covering the firecracker API.
Parameters
- machineConfig: Partial<MachineConfiguration>
  A subset of Machine Configuration Parameters
Returns Promise<void>
Throws
with the fault_message from the API
Inherited from FirecrackerAPIClient.partiallyUpdateMachineConfiguration
- Defined in api/api-client.ts:240

`Protected`request

request(
options: RequestOptions,
validStatusCodes: number[],
): Promise<ResponseData<null>>
Makes a request to the API.
- Assumes JSON request body.
- Checks that the response status code is in the validStatusCodes array.
- If not, throws an Error with the fault_message from the API error response.
Parameters
- options: RequestOptions
  the options for the request. Everything will work except the 'Content-Type' header, which is always set to 'application/json'.
- validStatusCodes: number[]
  array of valid status codes for the response
Returns Promise<ResponseData<null>>
the response from the API

Throws
with the fault_message from the API if the response status code is not valid
Inherited from FirecrackerAPIClient.request
- Defined in api/api-client.ts:46

setBootSource

setBootSource(bootSource: BootSource): Promise<void>
Creates new boot source if one does not already exist, otherwise updates it. This is works pre-boot only. Will fail if update is not possible.
Parameters
- bootSource: BootSource
  the bootsource
Returns Promise<void>
Inherited from FirecrackerAPIClient.setBootSource
- Defined in api/api-client.ts:138

setMachineConfiguration

setMachineConfiguration(machineConfig: MachineConfiguration): Promise<void>
Updates the Machine Configuration of the VM. Pre-boot only.
- Firecracker starts with default values for vCPU count (=1) and memory size (=128 MiB).
- The vCPU count is restricted to the [1, 32] range.
- With SMT enabled, the vCPU count is required to be either 1 or an even number in the range. otherwise there are no restrictions regarding the vCPU count.
- If 2M hugetlbfs pages are specified, then mem_size_mib must be a multiple of 2.
- If any of the parameters has an incorrect value, the whole update fails.
- All parameters that are optional and are not specified are set to their default values (smt = false, track_dirty_pages = false, cpu_template = None, huge_pages = None).
Parameters
- machineConfig: MachineConfiguration
  Machine Configuration Parameters
Returns Promise<void>
Throws
with the fault_message from the API
Inherited from FirecrackerAPIClient.setMachineConfiguration
- Defined in api/api-client.ts:218

spawnFirecrackerProcess

spawnFirecrackerProcess(removeExistingSocket: boolean): Promise<void>
Spawns a firecracker process
- Does nothing if the process is already spawned.
- Waits until the Firecracker API is ready to accept requests before returning.
- If the API does not become ready within 5 seconds, throws an error.
Parameters
- removeExistingSocket: boolean
  whether to remove an existing socket file before starting the process. This is useful to ensure that a stale socket does not prevent the Firecracker process from starting.
Returns Promise<void>
- Defined in core/firecracker-microvm.ts:195

startAction

startAction(action: InstanceAction): Promise<void>
Starts an action on the instance
Parameters
- action: InstanceAction
  The action to start
Returns Promise<void>
resolves when the action is successfully started

Throws
with the fault_message from the API
Inherited from FirecrackerAPIClient.startAction
- Defined in api/api-client.ts:116

stopFirecrackerProcess

stopFirecrackerProcess(): Promise<void>
Kills the Firecracker process and waits for it to exit.
- If the process is not running, does nothing.
Returns Promise<void>
- Defined in core/firecracker-microvm.ts:249

updateDriveProperties

updateDriveProperties(partialDrive: PartialDrive): Promise<void>
Updates the properties of a drive with the specified ID. This works post-boot only. Will fail if update is not possible.
Parameters
- partialDrive: PartialDrive
  Guest drive properties to update
Returns Promise<void>
Inherited from FirecrackerAPIClient.updateDriveProperties
- Defined in api/api-client.ts:174

Class FirecrackerMicroVM

Note

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns FirecrackerMicroVM

Properties

Protected OptionalfirecrackerProcess

ProtectedinitParams

ProtectedundiciClient

Methods

ProtectedbuildFirecrackerArgs

Returns string[]

See

createOrUpdateDrive

Parameters

Returns Promise<void>

getInstanceInfo

Returns Promise<InstanceInfo>

Throws

getMachineConfiguration

Returns Promise<MachineConfiguration>

Throws

ProtectedjsonRequest

Type Parameters

Parameters

Returns Promise<ResponseBodyType>

ProtectednoContentRequest

Parameters

Returns Promise<void>

partiallyUpdateMachineConfiguration

Parameters

Returns Promise<void>

Throws

Protectedrequest

Parameters

Returns Promise<ResponseData<null>>

Throws

setBootSource

Parameters

Returns Promise<void>

setMachineConfiguration

Parameters

Returns Promise<void>

Throws

spawnFirecrackerProcess

Parameters

Returns Promise<void>

startAction

Parameters

Returns Promise<void>

Throws

stopFirecrackerProcess

Returns Promise<void>

updateDriveProperties

Parameters

Returns Promise<void>

Settings

On This Page

`Protected` `Optional`firecrackerProcess

`Protected`initParams

`Protected`undiciClient

`Protected`buildFirecrackerArgs

`Protected`jsonRequest

`Protected`noContentRequest

`Protected`request