gitee.com/leisunstar/runtime@v0.0.0-20200521203717-5cef3e7b53f9/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        boot_args:
   395          type: string
   396          description: Kernel boot arguments
   397  
   398    CpuTemplate:
   399      type: string
   400      description:
   401        The CPU Template defines a set of flags to be disabled from the microvm so that
   402        the features exposed to the guest are the same as in the selected instance type.
   403      enum:
   404        - C3
   405        - T2
   406  
   407    Drive:
   408      type: object
   409      required:
   410        - drive_id
   411        - path_on_host
   412        - is_root_device
   413        - is_read_only
   414      properties:
   415        drive_id:
   416          type: string
   417        path_on_host:
   418          type: string
   419          description: Host level path for the guest drive
   420        is_root_device:
   421          type: boolean
   422        partuuid:
   423          type: string
   424          description:
   425            Represents the unique id of the boot partition of this device. It is
   426            optional and it will be taken into account only if the is_root_device
   427            field is true.
   428        is_read_only:
   429          type: boolean
   430        rate_limiter:
   431          $ref: "#/definitions/RateLimiter"
   432  
   433    Error:
   434      type: object
   435      properties:
   436        fault_message:
   437          type: string
   438          description: A description of the error condition
   439          readOnly: true
   440  
   441    InstanceActionInfo:
   442      type: object
   443      description:
   444        Variant wrapper containing the real action.
   445      required:
   446        - action_type
   447      properties:
   448        action_type:
   449          description: Enumeration indicating what type of action is contained in the payload
   450          type: string
   451          enum:
   452          - FlushMetrics
   453          - InstanceStart
   454          - SendCtrlAltDel
   455  
   456    InstanceInfo:
   457      type: object
   458      description:
   459        Describes MicroVM instance information.
   460      required:
   461        - id
   462        - state
   463        - vmm_version
   464      properties:
   465        id:
   466          description: MicroVM / instance ID.
   467          type: string
   468        state:
   469          description:
   470            The current detailed state of the Firecracker instance.
   471            This value is read-only for the control-plane.
   472          type: string
   473          enum:
   474            - Uninitialized
   475            - Starting
   476            - Running
   477        vmm_version:
   478          description: MicroVM hypervisor build version.
   479          type: string
   480  
   481    Logger:
   482      type: object
   483      description:
   484        Describes the configuration option for the logging capability.
   485      required:
   486        - log_fifo
   487        - metrics_fifo
   488      properties:
   489        log_fifo:
   490          type: string
   491          description: The named pipe for the human readable log output.
   492        metrics_fifo:
   493          type: string
   494          description: The named pipe where the JSON-formatted metrics will be flushed.
   495        level:
   496          type: string
   497          description: Set the level.
   498          enum: [Error, Warning, Info, Debug]
   499          default: Warning
   500        show_level:
   501          type: boolean
   502          description: Whether or not to output the level in the logs.
   503          default: false
   504        show_log_origin:
   505          type: boolean
   506          description: Whether or not to include the file path and line number of the log's origin.
   507          default: false
   508  
   509    MachineConfiguration:
   510      type: object
   511      description:
   512        Describes the number of vCPUs, memory size, Hyperthreading capabilities and
   513        the CPU template.
   514      required:
   515        - vcpu_count
   516        - mem_size_mib
   517        - ht_enabled
   518      properties:
   519        vcpu_count:
   520          type: integer
   521          minimum: 1
   522          maximum: 32
   523          description: Number of vCPUs (either 1 or an even number)
   524        mem_size_mib:
   525          type: integer
   526          description: Memory size of VM
   527        ht_enabled:
   528          type: boolean
   529          description: Flag for enabling/disabling Hyperthreading
   530        cpu_template:
   531          $ref: "#/definitions/CpuTemplate"
   532  
   533    NetworkInterface:
   534      type: object
   535      description:
   536        Defines a network interface.
   537      required:
   538        - iface_id
   539        - host_dev_name
   540      properties:
   541        iface_id:
   542          type: string
   543        guest_mac:
   544          type: string
   545        host_dev_name:
   546          type: string
   547          description: Host level path for the guest network interface
   548        allow_mmds_requests:
   549          type: boolean
   550          description:
   551            If this field is set, the device model will reply to HTTP GET
   552            requests sent to the MMDS address via this interface. In this case,
   553            both ARP requests for 169.254.169.254 and TCP segments heading to the
   554            same address are intercepted by the device model, and do not reach
   555            the associated TAP device.
   556        rx_rate_limiter:
   557          $ref: "#/definitions/RateLimiter"
   558        tx_rate_limiter:
   559          $ref: "#/definitions/RateLimiter"
   560  
   561    PartialDrive:
   562      type: object
   563      required:
   564        - drive_id
   565        - path_on_host
   566      properties:
   567        drive_id:
   568          type: string
   569        path_on_host:
   570          type: string
   571          description: Host level path for the guest drive
   572  
   573    PartialNetworkInterface:
   574      type: object
   575      description:
   576        Defines a partial network interface structure, used to update the rate limiters
   577        for that interface, after microvm start.
   578      required:
   579        - iface_id
   580      properties:
   581        iface_id:
   582          type: string
   583        rx_rate_limiter:
   584          $ref: "#/definitions/RateLimiter"
   585        tx_rate_limiter:
   586          $ref: "#/definitions/RateLimiter"
   587  
   588    RateLimiter:
   589      type: object
   590      description:
   591        Defines an IO rate limiter with independent bytes/s and ops/s limits.
   592        Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets.
   593      properties:
   594        bandwidth:
   595          $ref: "#/definitions/TokenBucket"
   596          description: Token bucket with bytes as tokens
   597        ops:
   598          $ref: "#/definitions/TokenBucket"
   599          description: Token bucket with operations as tokens
   600  
   601    TokenBucket:
   602      type: object
   603      description:
   604        Defines a token bucket with a maximum capacity (size), an initial burst size
   605        (one_time_burst) and an interval for refilling purposes (refill_time).
   606        The refill-rate is derived from size and refill_time, and it is the constant
   607        rate at which the tokens replenish. The refill process only starts happening after
   608        the initial burst budget is consumed.
   609        Consumption from the token bucket is unbounded in speed which allows for bursts
   610        bound in size by the amount of tokens available.
   611        Once the token bucket is empty, consumption speed is bound by the refill_rate.
   612      required:
   613        - size
   614        - refill_time
   615      properties:
   616        size:
   617          type: integer
   618          format: int64
   619          description: The total number of tokens this bucket can hold.
   620          minimum: 0
   621        one_time_burst:
   622          type: integer
   623          format: int64
   624          description: The initial size of a token bucket.
   625          minimum: 0
   626        refill_time:
   627          type: integer
   628          format: int64
   629          description: The amount of milliseconds it takes for the bucket to refill.
   630          minimum: 0
   631  
   632    Vsock:
   633      type: object
   634      description:
   635        Defines a vsock device, backed by a set of Unix Domain Sockets, on the host side.
   636        For host-initiated connections, Firecracker will be listening on the Unix socket
   637        identified by the path `uds_path`. Firecracker will create this socket, bind and
   638        listen on it. Host-initiated connections will be performed by connection to this
   639        socket and issuing a connection forwarding request to the desired guest-side vsock
   640        port (i.e. `CONNECT 52\n`, to connect to port 52).
   641        For guest-initiated connections, Firecracker will expect host software to be
   642        bound and listening on Unix sockets at `uds_path_<PORT>`.
   643        E.g. "/path/to/host_vsock.sock_52" for port number 52.
   644      required:
   645        - vsock_id
   646        - guest_cid
   647        - uds_path
   648      properties:
   649        vsock_id:
   650          type: string
   651        guest_cid:
   652          type: integer
   653          minimum: 3
   654          description: Guest Vsock CID
   655        uds_path:
   656          type: string
   657          description: Path to UNIX domain socket, used to proxy vsock connections.