firecracker-node
    Preparing search index...

    Class FirecrackerAPIClient

    API Client for interacting with the Firecracker API over a Unix socket.

    Index

    Constructors

    constructor

    Properties

    undiciClient

    Methods

    cleanup createOrUpdateDrive getInstanceInfo getMachineConfiguration jsonRequest noContentRequest partiallyUpdateMachineConfiguration request setBootSource setMachineConfiguration startAction updateDriveProperties waitForAPIToBeReady

    Constructors

    • Initializes the API client with the specified socket path.

      Parameters

      • socketPath: string

        The path to the Unix socket (e.g., '/tmp/firecracker.socket')

      • OptionalbaseUrl: string

        The base URL for the API (default is 'http://localhost'). Don't include trailing slash.

      Returns FirecrackerAPIClient

    Properties

    undiciClient: Client

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

    Methods

    • Cleans up the API client by closing the underlying HTTP connection.

      Returns Promise<void>

      Make sure to not call API methods after calling this!

      add more intuitive cleanup pipeline

    • 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>

    • 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

      with the fault_message from the API

      • Attempts to parse response body as JSON.
      • Calls request() internally

      Type Parameters

      • ResponseBodyType extends object

      Parameters

      • options: RequestOptions
      • validStatusCodes: number[]

      Returns Promise<ResponseBodyType>

      • Does not attempt to parse response body.
      • Calls request() internally

      Parameters

      • options: RequestOptions
      • validStatusCodes: number[]

      Returns 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

      Returns Promise<void>

      with the fault_message from the API

    • 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

      with the fault_message from the API if the response status code is not valid

    • 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

      Returns 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

      Returns Promise<void>

      with the fault_message from the API

    • Starts an action on the instance

      Parameters

      Returns Promise<void>

      resolves when the action is successfully started

      with the fault_message from the API

    • Updates the properties of a drive with the specified ID. This works post-boot only. Will fail if update is not possible.

      Parameters

      Returns Promise<void>

    • Waits for firecracker API to be ready.

      This is method is useful when the firecracker process is just started and we need to wait until the API is ready before making any requests.

      Parameters

      • timeoutMs: number = 5000

        the maximum time to wait for the API to be ready, in milliseconds. Default is 5000ms.

      Returns Promise<void>

      if the API is not ready within the specified timeout

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods