github.com/kata-containers/runtime@v0.0.0-20210505125100-04f29832a923/virtcontainers/pkg/firecracker/firecracker.yaml (about)

     1  swagger: "2.0"
     2  info:
     3    title: Firecracker API
     4    description: RESTful public-facing API.
     5                 The API is accessible through HTTP calls on specific URLs
     6                 carrying JSON modeled data.
     7                 The transport medium is a Unix Domain Socket.
     8    version: 0.21.1
     9    termsOfService: ""
    10    contact:
    11      email: "compute-capsule@amazon.com"
    12    license:
    13      name: "Apache 2.0"
    14      url: "http://www.apache.org/licenses/LICENSE-2.0.html"
    15  
    16  host: "localhost"
    17  basePath: "/"
    18  
    19  schemes:
    20    - http
    21  consumes:
    22    - application/json
    23  produces:
    24    - application/json
    25  
    26  paths:
    27    /:
    28      get:
    29        summary: Returns general information about an instance.
    30        operationId: describeInstance
    31        responses:
    32          200:
    33            description: The instance information
    34            schema:
    35              $ref: "#/definitions/InstanceInfo"
    36          default:
    37            description: Internal Server Error
    38            schema:
    39              $ref: "#/definitions/Error"
    40  
    41    /actions:
    42      put:
    43        summary: Creates a synchronous action.
    44        operationId: createSyncAction
    45        parameters:
    46        - name: info
    47          in: body
    48          required: true
    49          schema:
    50            $ref: "#/definitions/InstanceActionInfo"
    51        responses:
    52          204:
    53            description: The update was successful
    54          400:
    55            description: The action cannot be executed due to bad input
    56            schema:
    57              $ref: "#/definitions/Error"
    58          default:
    59            description: Internal Server Error
    60            schema:
    61              $ref: "#/definitions/Error"
    62  
    63    /boot-source:
    64      put:
    65        summary: Creates or updates the boot source.
    66        description:
    67          Creates new boot source if one does not already exist, otherwise updates it.
    68          Will fail if update is not possible.
    69          Note that the only currently supported boot source is LocalImage.
    70        operationId: putGuestBootSource
    71        parameters:
    72        - name: body
    73          in: body
    74          description: Guest boot source properties
    75          required: true
    76          schema:
    77            $ref: "#/definitions/BootSource"
    78        responses:
    79          204:
    80            description: Boot source created/updated
    81          400:
    82            description: Boot source cannot be created due to bad input
    83            schema:
    84              $ref: "#/definitions/Error"
    85          default:
    86            description: Internal server error
    87            schema:
    88              $ref: "#/definitions/Error"
    89  
    90    /drives/{drive_id}:
    91      put:
    92        summary: Creates or updates a drive.
    93        description:
    94          Creates new drive with ID specified by drive_id path parameter.
    95          If a drive with the specified ID already exists, updates its state based on new input.
    96          Will fail if update is not possible.
    97        operationId: putGuestDriveByID
    98        parameters:
    99        - name: drive_id
   100          in: path
   101          description: The id of the guest drive
   102          required: true
   103          type: string
   104        - name: body
   105          in: body
   106          description: Guest drive properties
   107          required: true
   108          schema:
   109            $ref: "#/definitions/Drive"
   110        responses:
   111          204:
   112            description: Drive created/updated
   113          400:
   114            description: Drive cannot be created/updated due to bad input
   115            schema:
   116              $ref: "#/definitions/Error"
   117          default:
   118            description: Internal server error.
   119            schema:
   120              $ref: "#/definitions/Error"
   121      patch:
   122        summary: Updates the properties of a drive.
   123        description:
   124          Updates the properties of the drive with the ID specified by drive_id path parameter.
   125          Will fail if update is not possible.
   126        operationId: patchGuestDriveByID
   127        parameters:
   128        - name: drive_id
   129          in: path
   130          description: The id of the guest drive
   131          required: true
   132          type: string
   133        - name: body
   134          in: body
   135          description: Guest drive properties
   136          required: true
   137          schema:
   138            $ref: "#/definitions/PartialDrive"
   139        responses:
   140          204:
   141            description: Drive updated
   142          400:
   143            description: Drive cannot be updated due to bad input
   144            schema:
   145              $ref: "#/definitions/Error"
   146          default:
   147            description: Internal server error.
   148            schema:
   149              $ref: "#/definitions/Error"
   150  
   151    /logger:
   152        put:
   153          summary: Initializes the logger by specifying two named pipes (i.e. for the logs and metrics output).
   154          operationId: putLogger
   155          parameters:
   156          - name: body
   157            in: body
   158            description: Logging system description
   159            required: true
   160            schema:
   161              $ref: "#/definitions/Logger"
   162          responses:
   163            204:
   164              description: Logger created.
   165            400:
   166              description: Logger cannot be initialized due to bad input.
   167              schema:
   168                $ref: "#/definitions/Error"
   169            default:
   170              description: Internal server error.
   171              schema:
   172                $ref: "#/definitions/Error"
   173  
   174    /machine-config:
   175      get:
   176        summary: Gets the machine configuration of the VM.
   177        description:
   178          Gets the machine configuration of the VM. When called before the PUT operation, it
   179          will return the default values for the vCPU count (=1), memory size (=128 MiB).
   180          By default Hyperthreading is disabled and there is no CPU Template.
   181        operationId: getMachineConfiguration
   182        responses:
   183          200:
   184            description: OK
   185            schema:
   186              $ref: "#/definitions/MachineConfiguration"
   187          default:
   188            description: Internal server error
   189            schema:
   190              $ref: "#/definitions/Error"
   191  
   192      put:
   193        summary: Updates the Machine Configuration of the VM.
   194        description:
   195          Updates the Virtual Machine Configuration with the specified input.
   196          Firecracker starts with default values for vCPU count (=1) and memory size (=128 MiB).
   197          With Hyperthreading enabled, the vCPU count is restricted to be 1 or an even number,
   198          otherwise there are no restrictions regarding the vCPU count.
   199          If any of the parameters has an incorrect value, the whole update fails.
   200        operationId: putMachineConfiguration
   201        parameters:
   202        - name: body
   203          in: body
   204          description: Machine Configuration Parameters
   205          schema:
   206            $ref: "#/definitions/MachineConfiguration"
   207        responses:
   208          204:
   209            description: Machine Configuration created/updated
   210          400:
   211            description: Machine Configuration cannot be updated due to bad input
   212            schema:
   213              $ref: "#/definitions/Error"
   214          default:
   215            description: Internal server error
   216            schema:
   217              $ref: "#/definitions/Error"
   218  
   219      patch:
   220        summary: Partially updates the Machine Configuration of the VM.
   221        description:
   222          Partially updates the Virtual Machine Configuration with the specified input.
   223          If any of the parameters has an incorrect value, the whole update fails.
   224        operationId: patchMachineConfiguration
   225        parameters:
   226        - name: body
   227          in: body
   228          description: A subset of Machine Configuration Parameters
   229          schema:
   230            $ref: "#/definitions/MachineConfiguration"
   231        responses:
   232          204:
   233            description: Machine Configuration created/updated
   234          400:
   235            description: Machine Configuration cannot be updated due to bad input
   236            schema:
   237              $ref: "#/definitions/Error"
   238          default:
   239            description: Internal server error
   240            schema:
   241              $ref: "#/definitions/Error"
   242  
   243    /mmds:
   244      put:
   245        summary: Creates a MMDS (Microvm Metadata Service) data store.
   246        parameters:
   247          - name: body
   248            in: body
   249            description: The MMDS data store as JSON.
   250            schema:
   251              type: object
   252        responses:
   253          204:
   254            description: MMDS data store created/updated.
   255          400:
   256            description: MMDS data store cannot be created due to bad input.
   257            schema:
   258              $ref: "#/definitions/Error"
   259          default:
   260            description: Internal server error
   261            schema:
   262              $ref: "#/definitions/Error"
   263      patch:
   264        summary: Updates the MMDS data store.
   265        parameters:
   266          - name: body
   267            in: body
   268            description: The MMDS data store patch JSON.
   269            schema:
   270              type: object
   271        responses:
   272          204:
   273            description: MMDS data store updated.
   274          400:
   275            description: MMDS data store cannot be updated due to bad input.
   276            schema:
   277              $ref: "#/definitions/Error"
   278          default:
   279            description: Internal server error
   280            schema:
   281              $ref: "#/definitions/Error"
   282      get:
   283        summary: Get the MMDS data store.
   284        responses:
   285          200:
   286            description: The MMDS data store JSON.
   287            schema:
   288              type: object
   289          400:
   290            description: Cannot get the MMDS data store due to bad input.
   291            schema:
   292              $ref: "#/definitions/Error"
   293          default:
   294            description: Internal server error
   295            schema:
   296              $ref: "#/definitions/Error"
   297  
   298    /network-interfaces/{iface_id}:
   299      put:
   300        summary: Creates a network interface.
   301        description:
   302          Creates new network interface with ID specified by iface_id path parameter.
   303        operationId: putGuestNetworkInterfaceByID
   304        parameters:
   305        - name: iface_id
   306          in: path
   307          description: The id of the guest network interface
   308          required: true
   309          type: string
   310        - name: body
   311          in: body
   312          description: Guest network interface properties
   313          required: true
   314          schema:
   315            $ref: "#/definitions/NetworkInterface"
   316        responses:
   317          204:
   318            description: Network interface created/updated
   319          400:
   320            description: Network interface cannot be created due to bad input
   321            schema:
   322              $ref: "#/definitions/Error"
   323          default:
   324            description: Internal server error
   325            schema:
   326              $ref: "#/definitions/Error"
   327      patch:
   328        summary: Updates the rate limiters applied to a network interface.
   329        description:
   330          Updates the rate limiters applied to a network interface.
   331        operationId: patchGuestNetworkInterfaceByID
   332        parameters:
   333          - name: iface_id
   334            in: path
   335            description: The id of the guest network interface
   336            required: true
   337            type: string
   338          - name: body
   339            in: body
   340            description: A subset of the guest network interface properties
   341            required: true
   342            schema:
   343              $ref: "#/definitions/PartialNetworkInterface"
   344        responses:
   345          204:
   346            description: Network interface updated
   347          400:
   348            description: Network interface cannot be updated due to bad input
   349            schema:
   350              $ref: "#/definitions/Error"
   351          default:
   352            description: Internal server error
   353            schema:
   354              $ref: "#/definitions/Error"
   355  
   356    /vsock:
   357      put:
   358        summary: Creates/updates a vsock device.
   359        description:
   360          The first call creates the device with the configuration specified
   361          in body. Subsequent calls will update the device configuration.
   362          May fail if update is not possible.
   363        operationId: putGuestVsock
   364        parameters:
   365        - name: body
   366          in: body
   367          description: Guest vsock properties
   368          required: true
   369          schema:
   370            $ref: "#/definitions/Vsock"
   371        responses:
   372          204:
   373            description: Vsock created/updated
   374          400:
   375            description: Vsock cannot be created due to bad input
   376            schema:
   377              $ref: "#/definitions/Error"
   378          default:
   379            description: Internal server error
   380            schema:
   381              $ref: "#/definitions/Error"
   382  
   383  definitions:
   384    BootSource:
   385      type: object
   386      required:
   387        - kernel_image_path
   388      description:
   389        Boot source descriptor.
   390      properties:
   391        kernel_image_path:
   392          type: string
   393          description: Host level path to the kernel image used to boot the guest
   394        initrd_path:
   395          type: string
   396          description: Host level path to the initrd image used to boot the guest
   397        boot_args:
   398          type: string
   399          description: Kernel boot arguments
   400  
   401    CpuTemplate:
   402      type: string
   403      description:
   404        The CPU Template defines a set of flags to be disabled from the microvm so that
   405        the features exposed to the guest are the same as in the selected instance type.
   406      enum:
   407        - C3
   408        - T2
   409  
   410    Drive:
   411      type: object
   412      required:
   413        - drive_id
   414        - path_on_host
   415        - is_root_device
   416        - is_read_only
   417      properties:
   418        drive_id:
   419          type: string
   420        path_on_host:
   421          type: string
   422          description: Host level path for the guest drive
   423        is_root_device:
   424          type: boolean
   425        partuuid:
   426          type: string
   427          description:
   428            Represents the unique id of the boot partition of this device. It is
   429            optional and it will be taken into account only if the is_root_device
   430            field is true.
   431        is_read_only:
   432          type: boolean
   433        rate_limiter:
   434          $ref: "#/definitions/RateLimiter"
   435  
   436    Error:
   437      type: object
   438      properties:
   439        fault_message:
   440          type: string
   441          description: A description of the error condition
   442          readOnly: true
   443  
   444    InstanceActionInfo:
   445      type: object
   446      description:
   447        Variant wrapper containing the real action.
   448      required:
   449        - action_type
   450      properties:
   451        action_type:
   452          description: Enumeration indicating what type of action is contained in the payload
   453          type: string
   454          enum:
   455          - FlushMetrics
   456          - InstanceStart
   457          - SendCtrlAltDel
   458  
   459    InstanceInfo:
   460      type: object
   461      description:
   462        Describes MicroVM instance information.
   463      required:
   464        - id
   465        - state
   466        - vmm_version
   467      properties:
   468        id:
   469          description: MicroVM / instance ID.
   470          type: string
   471        state:
   472          description:
   473            The current detailed state of the Firecracker instance.
   474            This value is read-only for the control-plane.
   475          type: string
   476          enum:
   477            - Uninitialized
   478            - Starting
   479            - Running
   480        vmm_version:
   481          description: MicroVM hypervisor build version.
   482          type: string
   483  
   484    Logger:
   485      type: object
   486      description:
   487        Describes the configuration option for the logging capability.
   488      required:
   489        - log_fifo
   490        - metrics_fifo
   491      properties:
   492        log_fifo:
   493          type: string
   494          description: The named pipe for the human readable log output.
   495        metrics_fifo:
   496          type: string
   497          description: The named pipe where the JSON-formatted metrics will be flushed.
   498        level:
   499          type: string
   500          description: Set the level.
   501          enum: [Error, Warning, Info, Debug]
   502          default: Warning
   503        show_level:
   504          type: boolean
   505          description: Whether or not to output the level in the logs.
   506          default: false
   507        show_log_origin:
   508          type: boolean
   509          description: Whether or not to include the file path and line number of the log's origin.
   510          default: false
   511  
   512    MachineConfiguration:
   513      type: object
   514      description:
   515        Describes the number of vCPUs, memory size, Hyperthreading capabilities and
   516        the CPU template.
   517      required:
   518        - vcpu_count
   519        - mem_size_mib
   520        - ht_enabled
   521      properties:
   522        vcpu_count:
   523          type: integer
   524          minimum: 1
   525          maximum: 32
   526          description: Number of vCPUs (either 1 or an even number)
   527        mem_size_mib:
   528          type: integer
   529          description: Memory size of VM
   530        ht_enabled:
   531          type: boolean
   532          description: Flag for enabling/disabling Hyperthreading
   533        cpu_template:
   534          $ref: "#/definitions/CpuTemplate"
   535  
   536    NetworkInterface:
   537      type: object
   538      description:
   539        Defines a network interface.
   540      required:
   541        - iface_id
   542        - host_dev_name
   543      properties:
   544        iface_id:
   545          type: string
   546        guest_mac:
   547          type: string
   548        host_dev_name:
   549          type: string
   550          description: Host level path for the guest network interface
   551        allow_mmds_requests:
   552          type: boolean
   553          description:
   554            If this field is set, the device model will reply to HTTP GET
   555            requests sent to the MMDS address via this interface. In this case,
   556            both ARP requests for 169.254.169.254 and TCP segments heading to the
   557            same address are intercepted by the device model, and do not reach
   558            the associated TAP device.
   559        rx_rate_limiter:
   560          $ref: "#/definitions/RateLimiter"
   561        tx_rate_limiter:
   562          $ref: "#/definitions/RateLimiter"
   563  
   564    PartialDrive:
   565      type: object
   566      required:
   567        - drive_id
   568        - path_on_host
   569      properties:
   570        drive_id:
   571          type: string
   572        path_on_host:
   573          type: string
   574          description: Host level path for the guest drive
   575  
   576    PartialNetworkInterface:
   577      type: object
   578      description:
   579        Defines a partial network interface structure, used to update the rate limiters
   580        for that interface, after microvm start.
   581      required:
   582        - iface_id
   583      properties:
   584        iface_id:
   585          type: string
   586        rx_rate_limiter:
   587          $ref: "#/definitions/RateLimiter"
   588        tx_rate_limiter:
   589          $ref: "#/definitions/RateLimiter"
   590  
   591    RateLimiter:
   592      type: object
   593      description:
   594        Defines an IO rate limiter with independent bytes/s and ops/s limits.
   595        Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets.
   596      properties:
   597        bandwidth:
   598          $ref: "#/definitions/TokenBucket"
   599          description: Token bucket with bytes as tokens
   600        ops:
   601          $ref: "#/definitions/TokenBucket"
   602          description: Token bucket with operations as tokens
   603  
   604    TokenBucket:
   605      type: object
   606      description:
   607        Defines a token bucket with a maximum capacity (size), an initial burst size
   608        (one_time_burst) and an interval for refilling purposes (refill_time).
   609        The refill-rate is derived from size and refill_time, and it is the constant
   610        rate at which the tokens replenish. The refill process only starts happening after
   611        the initial burst budget is consumed.
   612        Consumption from the token bucket is unbounded in speed which allows for bursts
   613        bound in size by the amount of tokens available.
   614        Once the token bucket is empty, consumption speed is bound by the refill_rate.
   615      required:
   616        - size
   617        - refill_time
   618      properties:
   619        size:
   620          type: integer
   621          format: int64
   622          description: The total number of tokens this bucket can hold.
   623          minimum: 0
   624        one_time_burst:
   625          type: integer
   626          format: int64
   627          description: The initial size of a token bucket.
   628          minimum: 0
   629        refill_time:
   630          type: integer
   631          format: int64
   632          description: The amount of milliseconds it takes for the bucket to refill.
   633          minimum: 0
   634  
   635    Vsock:
   636      type: object
   637      description:
   638        Defines a vsock device, backed by a set of Unix Domain Sockets, on the host side.
   639        For host-initiated connections, Firecracker will be listening on the Unix socket
   640        identified by the path `uds_path`. Firecracker will create this socket, bind and
   641        listen on it. Host-initiated connections will be performed by connection to this
   642        socket and issuing a connection forwarding request to the desired guest-side vsock
   643        port (i.e. `CONNECT 52\n`, to connect to port 52).
   644        For guest-initiated connections, Firecracker will expect host software to be
   645        bound and listening on Unix sockets at `uds_path_<PORT>`.
   646        E.g. "/path/to/host_vsock.sock_52" for port number 52.
   647      required:
   648        - vsock_id
   649        - guest_cid
   650        - uds_path
   651      properties:
   652        vsock_id:
   653          type: string
   654        guest_cid:
   655          type: integer
   656          minimum: 3
   657          description: Guest Vsock CID
   658        uds_path:
   659          type: string
   660          description: Path to UNIX domain socket, used to proxy vsock connections.