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

     1  openapi: 3.0.1
     2  info:
     3    title: Cloud Hypervisor API
     4    description: Local HTTP based API for managing and inspecting a cloud-hypervisor virtual machine.
     5    license:
     6      name: Apache 2.0
     7      url: http://www.apache.org/licenses/LICENSE-2.0.html
     8    version: 0.3.0
     9  
    10  servers:
    11  - url: http://localhost/api/v1
    12  
    13  paths:
    14  
    15    /vmm.ping:
    16      get:
    17        summary: Ping the VMM to check for API server availability
    18        responses:
    19          200:
    20            description: The VMM information
    21            content:
    22              application/json:
    23                schema:
    24                  $ref: '#/components/schemas/VmmPingResponse'
    25  
    26    /vmm.shutdown:
    27      put:
    28        summary: Shuts the cloud-hypervisor VMM.
    29        operationId: shutdownVMM
    30        responses:
    31          204:
    32            description: The VMM successfully shutdown.
    33  
    34    /vm.info:
    35      get:
    36        summary: Returns general information about the cloud-hypervisor Virtual Machine (VM) instance.
    37        responses:
    38          200:
    39            description: The VM information
    40            content:
    41              application/json:
    42                schema:
    43                  $ref: '#/components/schemas/VmInfo'
    44  
    45    /vm.counters:
    46      get:
    47        summary: Get counters from the VM
    48        responses:
    49          200:
    50            description: The VM counters
    51            content:
    52              application/json:
    53                schema:
    54                  $ref: '#/components/schemas/VmCounters'
    55  
    56    /vm.create:
    57      put:
    58        summary: Create the cloud-hypervisor Virtual Machine (VM) instance. The instance is not booted, only created.
    59        operationId: createVM
    60        requestBody:
    61          description: The VM configuration
    62          content:
    63            application/json:
    64              schema:
    65                $ref: '#/components/schemas/VmConfig'
    66          required: true
    67        responses:
    68          204:
    69            description: The VM instance was successfully created.
    70  
    71    /vm.delete:
    72      put:
    73        summary: Delete the cloud-hypervisor Virtual Machine (VM) instance.
    74        operationId: deleteVM
    75        responses:
    76          204:
    77            description: The VM instance was successfully deleted.
    78  
    79    /vm.boot:
    80      put:
    81        summary: Boot the previously created VM instance.
    82        operationId: bootVM
    83        responses:
    84          204:
    85            description: The VM instance successfully booted.
    86          404:
    87            description: The VM instance could not boot because it is not created yet
    88  
    89    /vm.pause:
    90      put:
    91        summary: Pause a previously booted VM instance.
    92        operationId: pauseVM
    93        responses:
    94          204:
    95            description: The VM instance successfully paused.
    96          404:
    97            description: The VM instance could not pause because it is not created yet
    98          405:
    99            description: The VM instance could not pause because it is not booted.
   100  
   101    /vm.resume:
   102      put:
   103        summary: Resume a previously paused VM instance.
   104        operationId: resumeVM
   105        responses:
   106          204:
   107            description: The VM instance successfully paused.
   108          404:
   109            description: The VM instance could not resume because it is not booted yet
   110          405:
   111            description: The VM instance could not resume because it is not paused.
   112  
   113    /vm.shutdown:
   114      put:
   115        summary: Shut the VM instance down.
   116        operationId: shutdownVM
   117        responses:
   118          204:
   119            description: The VM instance successfully shut down.
   120          404:
   121            description: The VM instance could not shut down because is not created.
   122          405:
   123            description: The VM instance could not shut down because it is not started.
   124  
   125    /vm.reboot:
   126      put:
   127        summary: Reboot the VM instance.
   128        operationId: rebootVM
   129        responses:
   130          204:
   131            description: The VM instance successfully rebooted.
   132          404:
   133            description: The VM instance could not reboot because it is not created.
   134          405:
   135            description: The VM instance could not reboot because it is not booted.
   136  
   137    /vm.power-button:
   138      put:
   139        summary: Trigger a power button in the VM
   140        operationId: power-buttonVM
   141        responses:
   142          204:
   143            description: Power button successfully triggered in the VM
   144          404:
   145            description: The button could not be triggered because it is not created yet
   146          405:
   147            description: The button could not be triggered because it is not booted.
   148  
   149    /vm.resize:
   150      put:
   151        summary: Resize the VM
   152        requestBody:
   153          description: The target size for the VM
   154          content:
   155            application/json:
   156              schema:
   157                $ref: '#/components/schemas/VmResize'
   158          required: true
   159        responses:
   160          204:
   161            description: The VM instance was successfully resized.
   162          404:
   163            description: The VM instance could not be resized because it is not created.
   164  
   165    /vm.resize-zone:
   166      put:
   167        summary: Resize a memory zone
   168        requestBody:
   169          description: The target size for the memory zone
   170          content:
   171            application/json:
   172              schema:
   173                $ref: '#/components/schemas/VmResizeZone'
   174          required: true
   175        responses:
   176          204:
   177            description: The memory zone was successfully resized.
   178          500:
   179            description: The memory zone could not be resized.
   180  
   181    /vm.add-device:
   182      put:
   183        summary: Add a new device to the VM
   184        requestBody:
   185          description: The path of the new device
   186          content:
   187            application/json:
   188              schema:
   189                $ref: '#/components/schemas/VmAddDevice'
   190          required: true
   191        responses:
   192          200:
   193            description: The new device was successfully added to the VM instance.
   194            content:
   195              application/json:
   196                schema:
   197                  $ref: '#/components/schemas/PciDeviceInfo'
   198          404:
   199            description: The new device could not be added to the VM instance.
   200  
   201    /vm.remove-device:
   202      put:
   203        summary: Remove a device from the VM
   204        requestBody:
   205          description: The identifier of the device
   206          content:
   207            application/json:
   208              schema:
   209                $ref: '#/components/schemas/VmRemoveDevice'
   210          required: true
   211        responses:
   212          204:
   213            description: The device was successfully removed from the VM instance.
   214          404:
   215            description: The device could not be removed from the VM instance.
   216  
   217    /vm.add-disk:
   218      put:
   219        summary: Add a new disk to the VM
   220        requestBody:
   221          description: The details of the new disk
   222          content:
   223            application/json:
   224              schema:
   225                $ref: '#/components/schemas/DiskConfig'
   226          required: true
   227        responses:
   228          200:
   229            description: The new disk was successfully added to the VM instance.
   230            content:
   231              application/json:
   232                schema:
   233                  $ref: '#/components/schemas/PciDeviceInfo'
   234          500:
   235            description: The new disk could not be added to the VM instance.
   236  
   237    /vm.add-fs:
   238      put:
   239        summary: Add a new virtio-fs device to the VM
   240        requestBody:
   241          description: The details of the new virtio-fs
   242          content:
   243            application/json:
   244              schema:
   245                $ref: '#/components/schemas/FsConfig'
   246          required: true
   247        responses:
   248          200:
   249            description: The new device was successfully added to the VM instance.
   250            content:
   251              application/json:
   252                schema:
   253                  $ref: '#/components/schemas/PciDeviceInfo'
   254          500:
   255            description: The new device could not be added to the VM instance.
   256  
   257    /vm.add-pmem:
   258      put:
   259        summary: Add a new pmem device to the VM
   260        requestBody:
   261          description: The details of the new pmem device
   262          content:
   263            application/json:
   264              schema:
   265                $ref: '#/components/schemas/PmemConfig'
   266          required: true
   267        responses:
   268          200:
   269            description: The new device was successfully added to the VM instance.
   270            content:
   271              application/json:
   272                schema:
   273                  $ref: '#/components/schemas/PciDeviceInfo'
   274          500:
   275            description: The new device could not be added to the VM instance.
   276  
   277    /vm.add-net:
   278      put:
   279        summary: Add a new network device to the VM
   280        requestBody:
   281          description: The details of the new network device
   282          content:
   283            application/json:
   284              schema:
   285                $ref: '#/components/schemas/NetConfig'
   286          required: true
   287        responses:
   288          200:
   289            description: The new device was successfully added to the VM instance.
   290            content:
   291              application/json:
   292                schema:
   293                  $ref: '#/components/schemas/PciDeviceInfo'
   294          500:
   295            description: The new device could not be added to the VM instance.
   296  
   297    /vm.add-vsock:
   298      put:
   299        summary: Add a new vsock device to the VM
   300        requestBody:
   301          description: The details of the new vsock device
   302          content:
   303            application/json:
   304              schema:
   305                $ref: '#/components/schemas/VsockConfig'
   306          required: true
   307        responses:
   308          200:
   309            description: The new device was successfully added to the VM instance.
   310            content:
   311              application/json:
   312                schema:
   313                  $ref: '#/components/schemas/PciDeviceInfo'
   314          500:
   315            description: The new device could not be added to the VM instance.
   316  
   317  
   318    /vm.snapshot:
   319      put:
   320        summary: Returns a VM snapshot.
   321        requestBody:
   322          description: The snapshot configuration
   323          content:
   324            application/json:
   325              schema:
   326                $ref: '#/components/schemas/VmSnapshotConfig'
   327          required: true
   328        responses:
   329          204:
   330            description: The VM instance was successfully snapshotted.
   331          404:
   332            description: The VM instance could not be snapshotted because it is not created.
   333          405:
   334            description: The VM instance could not be snapshotted because it is not booted.
   335  
   336    /vm.restore:
   337      put:
   338        summary: Restore a VM from a snapshot.
   339        requestBody:
   340          description: The restore configuration
   341          content:
   342            application/json:
   343              schema:
   344                $ref: '#/components/schemas/RestoreConfig'
   345          required: true
   346        responses:
   347          204:
   348            description: The VM instance was successfully restored.
   349          404:
   350            description: The VM instance could not be restored because it is already created.
   351  
   352  components:
   353    schemas:
   354  
   355      VmmPingResponse:
   356        required:
   357        - version
   358        type: object
   359        properties:
   360          version:
   361            type: string
   362        description: Virtual Machine Monitor information
   363  
   364      VmInfo:
   365        required:
   366        - config
   367        - state
   368        type: object
   369        properties:
   370          config:
   371            $ref: '#/components/schemas/VmConfig'
   372          state:
   373            type: string
   374            enum: [Created, Running, Shutdown, Paused]
   375          memory_actual_size:
   376            type: integer
   377            format: int64
   378          device_tree:
   379            type: object
   380            additionalProperties:
   381              $ref: '#/components/schemas/DeviceNode'
   382        description: Virtual Machine information
   383  
   384      DeviceNode:
   385        type: object
   386        properties:
   387          id:
   388            type: string
   389          resources:
   390            type: array
   391            items:
   392              # Rust enum type (with data) which can't be better represented here
   393              type: object
   394          children:
   395            type: array
   396            items:
   397              type: string
   398          pci_bdf:
   399            type: integer
   400            format: int32
   401  
   402      VmCounters:
   403        type: object
   404        additionalProperties:
   405          type: object
   406          additionalProperties:
   407            type: integer
   408            format: int64
   409  
   410      PciDeviceInfo:
   411        required:
   412        - id
   413        - bdf
   414        type: object
   415        properties:
   416          id:
   417            type: string
   418          bdf:
   419            type: string
   420        description: Information about a PCI device
   421  
   422      VmConfig:
   423        required:
   424        - kernel
   425        type: object
   426        properties:
   427          cpus:
   428            $ref: '#/components/schemas/CpusConfig'
   429          memory:
   430            $ref: '#/components/schemas/MemoryConfig'
   431          kernel:
   432            $ref: '#/components/schemas/KernelConfig'
   433          initramfs:
   434            $ref: '#/components/schemas/InitramfsConfig'
   435          cmdline:
   436            $ref: '#/components/schemas/CmdLineConfig'
   437          disks:
   438            type: array
   439            items:
   440              $ref: '#/components/schemas/DiskConfig'
   441          net:
   442            type: array
   443            items:
   444              $ref: '#/components/schemas/NetConfig'
   445          rng:
   446            $ref: '#/components/schemas/RngConfig'
   447          balloon:
   448            $ref: '#/components/schemas/BalloonConfig'
   449          fs:
   450            type: array
   451            items:
   452              $ref: '#/components/schemas/FsConfig'
   453          pmem:
   454            type: array
   455            items:
   456              $ref: '#/components/schemas/PmemConfig'
   457          serial:
   458            $ref: '#/components/schemas/ConsoleConfig'
   459          console:
   460            $ref: '#/components/schemas/ConsoleConfig'
   461          devices:
   462            type: array
   463            items:
   464              $ref: '#/components/schemas/DeviceConfig'
   465          vsock:
   466              $ref: '#/components/schemas/VsockConfig'
   467          sgx_epc:
   468            type: array
   469            items:
   470              $ref: '#/components/schemas/SgxEpcConfig'
   471          numa:
   472            type: array
   473            items:
   474              $ref: '#/components/schemas/NumaConfig'
   475          iommu:
   476            type: boolean
   477            default: false
   478          watchdog:
   479            type: boolean
   480            default: false
   481        description: Virtual machine configuration
   482  
   483      CpuTopology:
   484        type: object
   485        properties:
   486          threads_per_core:
   487            type: integer
   488          cores_per_die:
   489            type: integer
   490          dies_per_package:
   491            type: integer
   492          packages:
   493            type: integer
   494  
   495      CpusConfig:
   496        required:
   497        - boot_vcpus
   498        - max_vcpus
   499        type: object
   500        properties:
   501          boot_vcpus:
   502            minimum: 1
   503            default: 1
   504            type: integer
   505          max_vcpus:
   506            minimum: 1
   507            default: 1
   508            type: integer
   509          topology:
   510              $ref: '#/components/schemas/CpuTopology'
   511          max_phys_bits:
   512            type: integer
   513  
   514      MemoryZoneConfig:
   515        required:
   516        - id
   517        - size
   518        type: object
   519        properties:
   520          id:
   521            type: string
   522          size:
   523            type: integer
   524            format: int64
   525            default: 512 MB
   526          file:
   527            type: string
   528          mergeable:
   529            type: boolean
   530            default: false
   531          shared:
   532            type: boolean
   533            default: false
   534          hugepages:
   535            type: boolean
   536            default: false
   537          hugepage_size:
   538            type: integer
   539            format: int64
   540          host_numa_node:
   541            type: integer
   542            format: int32
   543          hotplug_size:
   544            type: integer
   545            format: int64
   546          hotplugged_size:
   547            type: integer
   548            format: int64
   549  
   550      MemoryConfig:
   551        required:
   552        - size
   553        type: object
   554        properties:
   555          size:
   556            type: integer
   557            format: int64
   558            default: 512 MB
   559          hotplug_size:
   560            type: integer
   561            format: int64
   562          hotplugged_size:
   563            type: integer
   564            format: int64
   565          mergeable:
   566            type: boolean
   567            default: false
   568          hotplug_method:
   569            type: string
   570            default: "acpi"
   571          shared:
   572            type: boolean
   573            default: false
   574          hugepages:
   575            type: boolean
   576            default: false
   577          hugepage_size:
   578            type: integer
   579            format: int64
   580          zones:
   581            type: array
   582            items:
   583              $ref: '#/components/schemas/MemoryZoneConfig'
   584  
   585      KernelConfig:
   586        required:
   587        - path
   588        type: object
   589        properties:
   590          path:
   591            type: string
   592  
   593      InitramfsConfig:
   594        nullable: true
   595        required:
   596        - path
   597        type: object
   598        properties:
   599          path:
   600            type: string
   601  
   602      CmdLineConfig:
   603        required:
   604        - args
   605        type: object
   606        properties:
   607          args:
   608            type: string
   609  
   610      TokenBucket:
   611        required:
   612        - size
   613        - refill_time
   614        type: object
   615        properties:
   616          size:
   617            type: integer
   618            format: int64
   619            minimum: 0
   620            description: The total number of tokens this bucket can hold.
   621          one_time_burst:
   622            type: integer
   623            format: int64
   624            minimum: 0
   625            description: The initial size of a token bucket.
   626          refill_time:
   627            type: integer
   628            format: int64
   629            minimum: 0
   630            description: The amount of milliseconds it takes for the bucket to refill.
   631        description:
   632          Defines a token bucket with a maximum capacity (_size_), an initial burst size
   633          (_one_time_burst_) and an interval for refilling purposes (_refill_time_).
   634          The refill-rate is derived from _size_ and _refill_time_, and it is the constant
   635          rate at which the tokens replenish. The refill process only starts happening after
   636          the initial burst budget is consumed.
   637          Consumption from the token bucket is unbounded in speed which allows for bursts
   638          bound in size by the amount of tokens available.
   639          Once the token bucket is empty, consumption speed is bound by the refill-rate.
   640  
   641      RateLimiterConfig:
   642        type: object
   643        properties:
   644          bandwidth:
   645            $ref: '#/components/schemas/TokenBucket'
   646          ops:
   647            $ref: '#/components/schemas/TokenBucket'
   648        description:
   649          Defines an IO rate limiter with independent bytes/s and ops/s limits.
   650          Limits are defined by configuring each of the _bandwidth_ and _ops_ token buckets.
   651  
   652      DiskConfig:
   653        required:
   654        - path
   655        type: object
   656        properties:
   657          path:
   658            type: string
   659          readonly:
   660            type: boolean
   661            default: false
   662          direct:
   663            type: boolean
   664            default: false
   665          iommu:
   666            type: boolean
   667            default: false
   668          num_queues:
   669            type: integer
   670            default: 1
   671          queue_size:
   672            type: integer
   673            default: 128
   674          vhost_user:
   675            type: boolean
   676            default: false
   677          vhost_socket:
   678            type: string
   679          poll_queue:
   680            type: boolean
   681            default: true
   682          rate_limiter_config:
   683              $ref: '#/components/schemas/RateLimiterConfig'
   684          id:
   685            type: string
   686  
   687      NetConfig:
   688        type: object
   689        properties:
   690          tap:
   691            type: string
   692            default: ""
   693          ip:
   694            type: string
   695            default: "192.168.249.1"
   696          mask:
   697            type: string
   698            default: "255.255.255.0"
   699          mac:
   700            type: string
   701          iommu:
   702            type: boolean
   703            default: false
   704          num_queues:
   705            type: integer
   706            default: 2
   707          queue_size:
   708            type: integer
   709            default: 256
   710          vhost_user:
   711            type: boolean
   712            default: false
   713          vhost_socket:
   714            type: string
   715          id:
   716            type: string
   717          fd:
   718            type: array
   719            items:
   720              type: integer
   721              format: int32
   722          rate_limiter_config:
   723              $ref: '#/components/schemas/RateLimiterConfig'
   724  
   725      RngConfig:
   726        required:
   727        - src
   728        type: object
   729        properties:
   730          src:
   731            type: string
   732            default: "/dev/urandom"
   733          iommu:
   734            type: boolean
   735            default: false
   736  
   737      BalloonConfig:
   738        required:
   739        - size
   740        type: object
   741        properties:
   742          size:
   743            type: integer
   744            format: int64
   745  
   746      FsConfig:
   747        required:
   748        - cache_size
   749        - dax
   750        - num_queues
   751        - queue_size
   752        - socket
   753        - tag
   754        type: object
   755        properties:
   756          tag:
   757            type: string
   758          socket:
   759            type: string
   760          num_queues:
   761            type: integer
   762            default: 1
   763          queue_size:
   764            type: integer
   765            default: 1024
   766          dax:
   767            type: boolean
   768            default: true
   769          cache_size:
   770            type: integer
   771            format: int64
   772            default: 8589934592
   773          id:
   774            type: string
   775  
   776      PmemConfig:
   777        required:
   778        - file
   779        type: object
   780        properties:
   781          file:
   782            type: string
   783          size:
   784            type: integer
   785            format: int64
   786          iommu:
   787            type: boolean
   788            default: false
   789          mergeable:
   790            type: boolean
   791            default: false
   792          discard_writes:
   793            type: boolean
   794            default: false
   795          id:
   796            type: string
   797  
   798      ConsoleConfig:
   799        required:
   800        - mode
   801        type: object
   802        properties:
   803          file:
   804            type: string
   805          mode:
   806            type: string
   807            enum: [Off, Pty, Tty, File, Null]
   808          iommu:
   809            type: boolean
   810            default: false
   811  
   812      DeviceConfig:
   813        required:
   814        - path
   815        type: object
   816        properties:
   817          path:
   818            type: string
   819          iommu:
   820            type: boolean
   821            default: false
   822          id:
   823            type: string
   824  
   825      VsockConfig:
   826        required:
   827        - cid
   828        - socket
   829        type: object
   830        properties:
   831          cid:
   832            type: integer
   833            format: int64
   834            minimum: 3
   835            description: Guest Vsock CID
   836          socket:
   837            type: string
   838            description: Path to UNIX domain socket, used to proxy vsock connections.
   839          iommu:
   840            type: boolean
   841            default: false
   842          id:
   843            type: string
   844  
   845      SgxEpcConfig:
   846        required:
   847        - size
   848        type: object
   849        properties:
   850          size:
   851            type: integer
   852            format: int64
   853          prefault:
   854            type: boolean
   855            default: false
   856  
   857      NumaDistance:
   858        required:
   859        - destination
   860        - distance
   861        type: object
   862        properties:
   863          destination:
   864            type: integer
   865            format: int32
   866          distance:
   867            type: integer
   868            format: int32
   869  
   870      NumaConfig:
   871        required:
   872        - guest_numa_id
   873        type: object
   874        properties:
   875          guest_numa_id:
   876            type: integer
   877            format: int32
   878          cpus:
   879            type: array
   880            items:
   881              type: integer
   882              format: int32
   883          distances:
   884            type: array
   885            items:
   886              $ref: '#/components/schemas/NumaDistance'
   887          memory_zones:
   888            type: array
   889            items:
   890              type: string
   891  
   892      VmResize:
   893        type: object
   894        properties:
   895          desired_vcpus:
   896            minimum: 1
   897            type: integer
   898          desired_ram:
   899            description: desired memory ram in bytes
   900            type: integer
   901            format: int64
   902          desired_balloon:
   903            description: desired balloon size in bytes
   904            type: integer
   905            format: int64
   906  
   907      VmResizeZone:
   908        type: object
   909        properties:
   910          id:
   911            type: string
   912          desired_ram:
   913            description: desired memory zone size in bytes
   914            type: integer
   915            format: int64
   916  
   917      VmAddDevice:
   918        type: object
   919        properties:
   920          path:
   921            type: string
   922          iommu:
   923            type: boolean
   924            default: false
   925          id:
   926            type: string
   927  
   928      VmRemoveDevice:
   929        type: object
   930        properties:
   931          id:
   932            type: string
   933  
   934      VmSnapshotConfig:
   935        type: object
   936        properties:
   937          destination_url:
   938            type: string
   939  
   940      RestoreConfig:
   941        required:
   942        - source_url
   943        type: object
   944        properties:
   945          source_url:
   946            type: string
   947          prefault:
   948            type: boolean