xref: /cloud-hypervisor/vmm/src/api/openapi/cloud-hypervisor.yaml (revision f67b3f79ea19c9a66e04074cbbf5d292f6529e43) 
1openapi: 3.0.1
2info:
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
10servers:
11- url: http://localhost/api/v1
12
13paths:
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
352components:
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        vhost_mode:
716          type: string
717          default: "Client"
718        id:
719          type: string
720        fd:
721          type: array
722          items:
723            type: integer
724            format: int32
725        rate_limiter_config:
726            $ref: '#/components/schemas/RateLimiterConfig'
727
728    RngConfig:
729      required:
730      - src
731      type: object
732      properties:
733        src:
734          type: string
735          default: "/dev/urandom"
736        iommu:
737          type: boolean
738          default: false
739
740    BalloonConfig:
741      required:
742      - size
743      type: object
744      properties:
745        size:
746          type: integer
747          format: int64
748        deflate_on_oom:
749          type: boolean
750          default: false
751          description: Whether the balloon should deflate when the guest is under memory pressure.
752
753    FsConfig:
754      required:
755      - cache_size
756      - dax
757      - num_queues
758      - queue_size
759      - socket
760      - tag
761      type: object
762      properties:
763        tag:
764          type: string
765        socket:
766          type: string
767        num_queues:
768          type: integer
769          default: 1
770        queue_size:
771          type: integer
772          default: 1024
773        dax:
774          type: boolean
775          default: true
776        cache_size:
777          type: integer
778          format: int64
779          default: 8589934592
780        id:
781          type: string
782
783    PmemConfig:
784      required:
785      - file
786      type: object
787      properties:
788        file:
789          type: string
790        size:
791          type: integer
792          format: int64
793        iommu:
794          type: boolean
795          default: false
796        mergeable:
797          type: boolean
798          default: false
799        discard_writes:
800          type: boolean
801          default: false
802        id:
803          type: string
804
805    ConsoleConfig:
806      required:
807      - mode
808      type: object
809      properties:
810        file:
811          type: string
812        mode:
813          type: string
814          enum: [Off, Pty, Tty, File, Null]
815        iommu:
816          type: boolean
817          default: false
818
819    DeviceConfig:
820      required:
821      - path
822      type: object
823      properties:
824        path:
825          type: string
826        iommu:
827          type: boolean
828          default: false
829        id:
830          type: string
831
832    VsockConfig:
833      required:
834      - cid
835      - socket
836      type: object
837      properties:
838        cid:
839          type: integer
840          format: int64
841          minimum: 3
842          description: Guest Vsock CID
843        socket:
844          type: string
845          description: Path to UNIX domain socket, used to proxy vsock connections.
846        iommu:
847          type: boolean
848          default: false
849        id:
850          type: string
851
852    SgxEpcConfig:
853      required:
854      - id
855      - size
856      type: object
857      properties:
858        id:
859          type: string
860        size:
861          type: integer
862          format: int64
863        prefault:
864          type: boolean
865          default: false
866
867    NumaDistance:
868      required:
869      - destination
870      - distance
871      type: object
872      properties:
873        destination:
874          type: integer
875          format: int32
876        distance:
877          type: integer
878          format: int32
879
880    NumaConfig:
881      required:
882      - guest_numa_id
883      type: object
884      properties:
885        guest_numa_id:
886          type: integer
887          format: int32
888        cpus:
889          type: array
890          items:
891            type: integer
892            format: int32
893        distances:
894          type: array
895          items:
896            $ref: '#/components/schemas/NumaDistance'
897        memory_zones:
898          type: array
899          items:
900            type: string
901        sgx_epc_sections:
902          type: array
903          items:
904            type: string
905
906    VmResize:
907      type: object
908      properties:
909        desired_vcpus:
910          minimum: 1
911          type: integer
912        desired_ram:
913          description: desired memory ram in bytes
914          type: integer
915          format: int64
916        desired_balloon:
917          description: desired balloon size in bytes
918          type: integer
919          format: int64
920
921    VmResizeZone:
922      type: object
923      properties:
924        id:
925          type: string
926        desired_ram:
927          description: desired memory zone size in bytes
928          type: integer
929          format: int64
930
931    VmAddDevice:
932      type: object
933      properties:
934        path:
935          type: string
936        iommu:
937          type: boolean
938          default: false
939        id:
940          type: string
941
942    VmRemoveDevice:
943      type: object
944      properties:
945        id:
946          type: string
947
948    VmSnapshotConfig:
949      type: object
950      properties:
951        destination_url:
952          type: string
953
954    RestoreConfig:
955      required:
956      - source_url
957      type: object
958      properties:
959        source_url:
960          type: string
961        prefault:
962          type: boolean
963