Firecracker Vm API

swagger: '2.0'
info:
  title: Firecracker Actions Vm API
  description: RESTful public-facing API. The API is accessible through HTTP calls on specific URLs carrying JSON modeled data. The transport medium is a Unix Domain Socket.
  version: 1.16.0-dev
  termsOfService: ''
  contact:
    email: firecracker-maintainers@amazon.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: localhost
basePath: /
schemes:
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: Vm
paths:
  /vm:
    patch:
      summary: Updates the microVM state.
      description: Sets the desired state (Paused or Resumed) for the microVM.
      operationId: patchVm
      parameters:
      - name: body
        in: body
        description: The microVM state
        required: true
        schema:
          $ref: '#/definitions/Vm'
      responses:
        204:
          description: Vm state updated
        400:
          description: Vm state cannot be updated due to bad input
          schema:
            $ref: '#/definitions/Error'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Vm
  /vm/config:
    get:
      summary: Gets the full VM configuration.
      description: Gets configuration for all VM resources. If the VM is restored from a snapshot, the boot-source, machine-config.smt and machine-config.cpu_template will be empty.
      operationId: getExportVmConfig
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/FullVmConfiguration'
        default:
          description: Internal server error
          schema:
            $ref: '#/definitions/Error'
      tags:
      - Vm
definitions:
  Vsock:
    type: object
    description: Defines a vsock device, backed by a set of Unix Domain Sockets, on the host side. For host-initiated connections, Firecracker will be listening on the Unix socket identified by the path `uds_path`. Firecracker will create this socket, bind and listen on it. Host-initiated connections will be performed by connection to this socket and issuing a connection forwarding request to the desired guest-side vsock port (i.e. `CONNECT 52\n`, to connect to port 52). For guest-initiated connections, Firecracker will expect host software to be bound and listening on Unix sockets at `uds_path_<PORT>`. E.g. "/path/to/host_vsock.sock_52" for port number 52.
    required:
    - guest_cid
    - uds_path
    properties:
      guest_cid:
        type: integer
        minimum: 3
        description: Guest Vsock CID
      uds_path:
        type: string
        description: Path to UNIX domain socket, used to proxy vsock connections.
      vsock_id:
        type: string
        description: This parameter has been deprecated and it will be removed in future Firecracker release.
  CpuTemplate:
    type: string
    description: The CPU Template defines a set of flags to be disabled from the microvm so that the features exposed to the guest are the same as in the selected instance type. This parameter has been deprecated and it will be removed in future Firecracker release.
    enum:
    - C3
    - T2
    - T2S
    - T2CL
    - T2A
    - V1N1
    - None
    default: None
  Pmem:
    type: object
    required:
    - id
    - path_on_host
    properties:
      id:
        type: string
        description: Identificator for this device.
      path_on_host:
        type: string
        description: Host level path for the virtio-pmem device to use as a backing file.
      root_device:
        type: boolean
        description: Flag to make this device be the root device for VM boot. Setting this flag will fail if there is another device configured to be a root device already.
      read_only:
        type: boolean
        description: Flag to map backing file in read-only mode.
      rate_limiter:
        $ref: '#/definitions/RateLimiter'
  EntropyDevice:
    type: object
    description: Defines an entropy device.
    properties:
      rate_limiter:
        $ref: '#/definitions/RateLimiter'
  NetworkInterface:
    type: object
    description: Defines a network interface.
    required:
    - host_dev_name
    - iface_id
    properties:
      guest_mac:
        type: string
      host_dev_name:
        type: string
        description: Host level path for the guest network interface
      iface_id:
        type: string
      rx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
      tx_rate_limiter:
        $ref: '#/definitions/RateLimiter'
  RateLimiter:
    type: object
    description: Defines an IO rate limiter with independent bytes/s and ops/s limits. Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets. This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
    properties:
      bandwidth:
        $ref: '#/definitions/TokenBucket'
        description: Token bucket with bytes as tokens
      ops:
        $ref: '#/definitions/TokenBucket'
        description: Token bucket with operations as tokens
  FullVmConfiguration:
    type: object
    properties:
      balloon:
        $ref: '#/definitions/Balloon'
      drives:
        type: array
        description: Configurations for all block devices.
        items:
          $ref: '#/definitions/Drive'
      boot-source:
        $ref: '#/definitions/BootSource'
      cpu-config:
        $ref: '#/definitions/CpuConfig'
      logger:
        $ref: '#/definitions/Logger'
      machine-config:
        $ref: '#/definitions/MachineConfiguration'
      metrics:
        $ref: '#/definitions/Metrics'
      memory-hotplug:
        $ref: '#/definitions/MemoryHotplugConfig'
      mmds-config:
        $ref: '#/definitions/MmdsConfig'
      network-interfaces:
        type: array
        description: Configurations for all net devices.
        items:
          $ref: '#/definitions/NetworkInterface'
      pmem:
        type: array
        description: Configurations for all pmem devices.
        items:
          $ref: '#/definitions/Pmem'
      vsock:
        $ref: '#/definitions/Vsock'
      entropy:
        $ref: '#/definitions/EntropyDevice'
  MemoryHotplugConfig:
    type: object
    description: The configuration of the hotpluggable memory device (virtio-mem)
    properties:
      total_size_mib:
        type: integer
        description: Total size of the hotpluggable memory in MiB.
      slot_size_mib:
        type: integer
        default: 128
        minimum: 128
        description: Slot size for the hotpluggable memory in MiB. This will determine the granularity of hot-plug memory from the host. Refer to the device documentation on how to tune this value.
      block_size_mib:
        type: integer
        default: 2
        minimum: 2
        description: (Logical) Block size for the hotpluggable memory in MiB. This will determine the logical granularity of hot-plug memory for the guest. Refer to the device documentation on how to tune this value.
  CpuidRegisterModifier:
    type: object
    description: Modifier for a specific CPUID register within a leaf (x86_64)
    required:
    - register
    - bitmap
    properties:
      register:
        type: string
        description: Target CPUID register name
        enum:
        - eax
        - ebx
        - ecx
        - edx
      bitmap:
        type: string
        description: 32-bit bitmap string defining which bits to modify. Format is "0b" followed by 32 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Example "0b00000000000000000000000000000001" or "0bxxxxxxxxxxxxxxxxxxxxxxxxxxxx0001"
  Vm:
    type: object
    description: Defines the microVM running state. It is especially useful in the snapshotting context.
    required:
    - state
    properties:
      state:
        type: string
        enum:
        - Paused
        - Resumed
  MmdsConfig:
    type: object
    description: Defines the MMDS configuration.
    required:
    - network_interfaces
    properties:
      version:
        description: Enumeration indicating the MMDS version to be configured.
        type: string
        enum:
        - V1
        - V2
        default: V1
      network_interfaces:
        description: List of the network interface IDs capable of forwarding packets to the MMDS. Network interface IDs mentioned must be valid at the time of this request. The net device model will reply to HTTP GET requests sent to the MMDS address via the interfaces mentioned. In this case, both ARP requests and TCP segments heading to `ipv4_address` are intercepted by the device model, and do not reach the associated TAP device.
        type: array
        items:
          type: string
      ipv4_address:
        type: string
        format: 169.254.([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-4]).([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])
        default: 169.254.169.254
        description: A valid IPv4 link-local address.
      imds_compat:
        type: boolean
        description: MMDS operates compatibly with EC2 IMDS (i.e. responds "text/plain" content regardless of Accept header in requests).
        default: false
  Metrics:
    type: object
    description: Describes the configuration option for the metrics capability.
    required:
    - metrics_path
    properties:
      metrics_path:
        type: string
        description: Path to the named pipe or file where the JSON-formatted metrics are flushed.
  Balloon:
    type: object
    required:
    - amount_mib
    - deflate_on_oom
    description: Balloon device descriptor.
    properties:
      amount_mib:
        type: integer
        description: Target balloon size in MiB.
      deflate_on_oom:
        type: boolean
        description: Whether the balloon should deflate when the guest has memory pressure.
      stats_polling_interval_s:
        type: integer
        description: Interval in seconds between refreshing statistics. A non-zero value will enable the statistics. Defaults to 0.
      free_page_hinting:
        type: boolean
        description: Whether the free page hinting feature is enabled.
      free_page_reporting:
        type: boolean
        description: Whether the free page reporting feature is enabled.
  CpuConfig:
    type: object
    description: The CPU configuration template defines a set of bit maps as modifiers of flags accessed by register to be disabled/enabled for the microvm.
    properties:
      kvm_capabilities:
        type: array
        description: A collection of KVM capabilities to be added or removed (both x86_64 and aarch64)
        items:
          type: string
          description: KVM capability as a numeric string. Prefix with '!' to remove capability. Example "121" (add) or "!121" (remove)
      cpuid_modifiers:
        type: array
        description: A collection of CPUID leaf modifiers (x86_64 only)
        items:
          $ref: '#/definitions/CpuidLeafModifier'
      msr_modifiers:
        type: array
        description: A collection of model specific register modifiers (x86_64 only)
        items:
          $ref: '#/definitions/MsrModifier'
      reg_modifiers:
        type: array
        description: A collection of register modifiers (aarch64 only)
        items:
          $ref: '#/definitions/ArmRegisterModifier'
      vcpu_features:
        type: array
        description: A collection of vCPU features to be modified (aarch64 only)
        items:
          $ref: '#/definitions/VcpuFeatures'
  CpuidLeafModifier:
    type: object
    description: Modifier for a CPUID leaf and subleaf (x86_64)
    required:
    - leaf
    - subleaf
    - flags
    - modifiers
    properties:
      leaf:
        type: string
        description: CPUID leaf index as hex, binary, or decimal string (e.g., "0x0", "0b0", "0"))
      subleaf:
        type: string
        description: CPUID subleaf index as hex, binary, or decimal string (e.g., "0x0", "0b0", "0")
      flags:
        type: integer
        format: int32
        description: KVM feature flags for this leaf-subleaf
      modifiers:
        type: array
        description: Register modifiers for this CPUID leaf
        items:
          $ref: '#/definitions/CpuidRegisterModifier'
  Error:
    type: object
    properties:
      fault_message:
        type: string
        description: A description of the error condition
        readOnly: true
  BootSource:
    type: object
    required:
    - kernel_image_path
    description: Boot source descriptor.
    properties:
      boot_args:
        type: string
        description: Kernel boot arguments
      initrd_path:
        type: string
        description: Host level path to the initrd image used to boot the guest
      kernel_image_path:
        type: string
        description: Host level path to the kernel image used to boot the guest
  MachineConfiguration:
    type: object
    description: Describes the number of vCPUs, memory size, SMT capabilities, huge page configuration and the CPU template.
    required:
    - mem_size_mib
    - vcpu_count
    properties:
      cpu_template:
        $ref: '#/definitions/CpuTemplate'
      smt:
        type: boolean
        description: Flag for enabling/disabling simultaneous multithreading. Can be enabled only on x86.
        default: false
      mem_size_mib:
        type: integer
        description: Memory size of VM
      track_dirty_pages:
        type: boolean
        description: Enable dirty page tracking. If this is enabled, then incremental guest memory snapshots can be created. These belong to diff snapshots, which contain, besides the microVM state, only the memory dirtied since a previous snapshot. Full snapshots each contain a full copy of the guest memory.
        default: false
      vcpu_count:
        type: integer
        minimum: 1
        maximum: 32
        description: Number of vCPUs (either 1 or an even number)
      huge_pages:
        type: string
        enum:
        - None
        - 2M
        description: Which huge pages configuration (if any) should be used to back guest memory.
  MsrModifier:
    type: object
    description: Modifier for a model specific register (x86_64)
    required:
    - addr
    - bitmap
    properties:
      addr:
        type: string
        description: 32-bit MSR address as hex, binary, or decimal string (e.g., "0x10a", "0b100001010", "266")
      bitmap:
        type: string
        description: 64-bit bitmap string defining which bits to modify. Format is "0b" followed by 64 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Underscores can be used for readability. Example "0b0000000000000000000000000000000000000000000000000000000000000001"
  TokenBucket:
    type: object
    description: Defines a token bucket with a maximum capacity (size), an initial burst size (one_time_burst) and an interval for refilling purposes (refill_time). The refill-rate is derived from size and refill_time, and it is the constant rate at which the tokens replenish. The refill process only starts happening after the initial burst budget is consumed. Consumption from the token bucket is unbounded in speed which allows for bursts bound in size by the amount of tokens available. Once the token bucket is empty, consumption speed is bound by the refill_rate.
    required:
    - refill_time
    - size
    properties:
      one_time_burst:
        type: integer
        format: int64
        description: The initial size of a token bucket.
        minimum: 0
      refill_time:
        type: integer
        format: int64
        description: The amount of milliseconds it takes for the bucket to refill.
        minimum: 0
      size:
        type: integer
        format: int64
        description: The total number of tokens this bucket can hold.
        minimum: 0
  Drive:
    type: object
    required:
    - drive_id
    - is_root_device
    properties:
      drive_id:
        type: string
      partuuid:
        type: string
        description: Represents the unique id of the boot partition of this device. It is optional and it will be taken into account only if the is_root_device field is true.
      is_root_device:
        type: boolean
      cache_type:
        type: string
        description: Represents the caching strategy for the block device.
        enum:
        - Unsafe
        - Writeback
        default: Unsafe
      is_read_only:
        type: boolean
        description: Is block read only. This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
      path_on_host:
        type: string
        description: Host level path for the guest drive. This field is required for virtio-block config and should be omitted for vhost-user-block configuration.
      rate_limiter:
        $ref: '#/definitions/RateLimiter'
      io_engine:
        type: string
        description: Type of the IO engine used by the device. "Async" is supported on host kernels newer than 5.10.51. This field is optional for virtio-block config and should be omitted for vhost-user-block configuration.
        enum:
        - Sync
        - Async
        default: Sync
      socket:
        type: string
        description: Path to the socket of vhost-user-block backend. This field is required for vhost-user-block config should be omitted for virtio-block configuration.
  VcpuFeatures:
    type: object
    description: vCPU feature modifier (aarch64)
    required:
    - index
    - bitmap
    properties:
      index:
        type: integer
        format: int32
        description: Index in the kvm_vcpu_init.features array
      bitmap:
        type: string
        description: 32-bit bitmap string defining which bits to modify. Format is "0b" followed by 32 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Example "0b00000000000000000000000001100000"
  ArmRegisterModifier:
    type: object
    description: Modifier for an ARM register (aarch64)
    required:
    - addr
    - bitmap
    properties:
      addr:
        type: string
        description: 64-bit register address as hex, binary, or decimal string (e.g., "0x0", "0b0", "0")
      bitmap:
        type: string
        description: 128-bit bitmap string defining which bits to modify. Format is "0b" followed by up to 128 characters where '0' = clear bit, '1' = set bit, 'x' = don't modify. Underscores can be used for readability. Example "0b0000000000000000000000000000000000000000000000000000000000000001"
  Logger:
    type: object
    description: Describes the configuration option for the logging capability.
    properties:
      level:
        type: string
        description: Set the level. The possible values are case-insensitive.
        enum:
        - Error
        - Warning
        - Info
        - Debug
        - Trace
        - false
        default: Info
      log_path:
        type: string
        description: Path to the named pipe or file for the human readable log output.
      show_level:
        type: boolean
        description: Whether or not to output the level in the logs.
        default: false
      show_log_origin:
        type: boolean
        description: Whether or not to include the file path and line number of the log's origin.
        default: false
      module:
        type: string
        description: The module path to filter log messages by.
        example: api_server::request