mirror of
https://github.com/cloud-hypervisor/cloud-hypervisor.git
synced 2026-08-05 02:19:16 +00:00
48963e322a
Add the ability for cloud-hypervisor to create, manage and monitor a pty for serial and/or console I/O from a user. The reasoning for having cloud-hypervisor create the ptys is so that clients, libvirt for example, could exit and later re-open the pty without causing I/O issues. If the clients were responsible for creating the pty, when they exit the main pty fd would close and cause cloud-hypervisor to get I/O errors on writes. Ideally the main and subordinate pty fds would be kept in the main vmm's Vm structure. However, because the device manager owns parsing the configuration for the serial and console devices, the information is instead stored in new fields under the DeviceManager structure directly. From there hooking up the main fd is intended to look as close to handling stdin and stdout on the tty as possible (there is some future work ahead for perhaps moving support for the pty into the vmm_sys_utils crate). The main fd is used for reading user input and writing to output of the Vm device. The subordinate fd is used to setup raw mode and it is kept open in order to avoid I/O errors when clients open and close the pty device. The ability to handle multiple inputs as part of this change is intentional. The current code allows serial and console ptys to be created and both be used as input. There was an implementation gap though with the queue_input_bytes needing to be modified so the pty handlers for serial and console could access the methods on the serial and console structures directly. Without this change only a single input source could be processed as the console would switch based on its input type (this is still valid for tty and isn't otherwise modified). Signed-off-by: William Douglas <william.r.douglas@gmail.com>
903 lines
21 KiB
YAML
903 lines
21 KiB
YAML
openapi: 3.0.1
|
|
info:
|
|
title: Cloud Hypervisor API
|
|
description: Local HTTP based API for managing and inspecting a cloud-hypervisor virtual machine.
|
|
license:
|
|
name: Apache 2.0
|
|
url: http://www.apache.org/licenses/LICENSE-2.0.html
|
|
version: 0.3.0
|
|
|
|
servers:
|
|
- url: http://localhost/api/v1
|
|
|
|
paths:
|
|
|
|
/vmm.ping:
|
|
get:
|
|
summary: Ping the VMM to check for API server availability
|
|
responses:
|
|
200:
|
|
description: The VMM information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmmPingResponse'
|
|
|
|
/vmm.shutdown:
|
|
put:
|
|
summary: Shuts the cloud-hypervisor VMM.
|
|
operationId: shutdownVMM
|
|
responses:
|
|
204:
|
|
description: The VMM successfully shutdown.
|
|
|
|
/vm.info:
|
|
get:
|
|
summary: Returns general information about the cloud-hypervisor Virtual Machine (VM) instance.
|
|
responses:
|
|
200:
|
|
description: The VM information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmInfo'
|
|
|
|
/vm.counters:
|
|
get:
|
|
summary: Get counters from the VM
|
|
responses:
|
|
200:
|
|
description: The VM counters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmCounters'
|
|
|
|
/vm.create:
|
|
put:
|
|
summary: Create the cloud-hypervisor Virtual Machine (VM) instance. The instance is not booted, only created.
|
|
operationId: createVM
|
|
requestBody:
|
|
description: The VM configuration
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmConfig'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The VM instance was successfully created.
|
|
|
|
/vm.delete:
|
|
put:
|
|
summary: Delete the cloud-hypervisor Virtual Machine (VM) instance.
|
|
operationId: deleteVM
|
|
responses:
|
|
204:
|
|
description: The VM instance was successfully deleted.
|
|
|
|
/vm.boot:
|
|
put:
|
|
summary: Boot the previously created VM instance.
|
|
operationId: bootVM
|
|
responses:
|
|
204:
|
|
description: The VM instance successfully booted.
|
|
404:
|
|
description: The VM instance could not boot because it is not created yet
|
|
|
|
/vm.pause:
|
|
put:
|
|
summary: Pause a previously booted VM instance.
|
|
operationId: pauseVM
|
|
responses:
|
|
204:
|
|
description: The VM instance successfully paused.
|
|
404:
|
|
description: The VM instance could not pause because it is not created yet
|
|
405:
|
|
description: The VM instance could not pause because it is not booted.
|
|
|
|
/vm.resume:
|
|
put:
|
|
summary: Resume a previously paused VM instance.
|
|
operationId: resumeVM
|
|
responses:
|
|
204:
|
|
description: The VM instance successfully paused.
|
|
404:
|
|
description: The VM instance could not resume because it is not booted yet
|
|
405:
|
|
description: The VM instance could not resume because it is not paused.
|
|
|
|
/vm.shutdown:
|
|
put:
|
|
summary: Shut the VM instance down.
|
|
operationId: shutdownVM
|
|
responses:
|
|
204:
|
|
description: The VM instance successfully shut down.
|
|
404:
|
|
description: The VM instance could not shut down because is not created.
|
|
405:
|
|
description: The VM instance could not shut down because it is not started.
|
|
|
|
/vm.reboot:
|
|
put:
|
|
summary: Reboot the VM instance.
|
|
operationId: rebootVM
|
|
responses:
|
|
204:
|
|
description: The VM instance successfully rebooted.
|
|
404:
|
|
description: The VM instance could not reboot because it is not created.
|
|
405:
|
|
description: The VM instance could not reboot because it is not booted.
|
|
|
|
/vm.power-button:
|
|
put:
|
|
summary: Trigger a power button in the VM
|
|
operationId: power-buttonVM
|
|
responses:
|
|
204:
|
|
description: Power button successfully triggered in the VM
|
|
404:
|
|
description: The button could not be triggered because it is not created yet
|
|
405:
|
|
description: The button could not be triggered because it is not booted.
|
|
|
|
/vm.resize:
|
|
put:
|
|
summary: Resize the VM
|
|
requestBody:
|
|
description: The target size for the VM
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmResize'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The VM instance was successfully resized.
|
|
404:
|
|
description: The VM instance could not be resized because it is not created.
|
|
|
|
/vm.resize-zone:
|
|
put:
|
|
summary: Resize a memory zone
|
|
requestBody:
|
|
description: The target size for the memory zone
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmResizeZone'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The memory zone was successfully resized.
|
|
500:
|
|
description: The memory zone could not be resized.
|
|
|
|
/vm.add-device:
|
|
put:
|
|
summary: Add a new device to the VM
|
|
requestBody:
|
|
description: The path of the new device
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmAddDevice'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new device was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
404:
|
|
description: The new device could not be added to the VM instance.
|
|
|
|
/vm.remove-device:
|
|
put:
|
|
summary: Remove a device from the VM
|
|
requestBody:
|
|
description: The identifier of the device
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmRemoveDevice'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The device was successfully removed from the VM instance.
|
|
404:
|
|
description: The device could not be removed from the VM instance.
|
|
|
|
/vm.add-disk:
|
|
put:
|
|
summary: Add a new disk to the VM
|
|
requestBody:
|
|
description: The details of the new disk
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiskConfig'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new disk was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
500:
|
|
description: The new disk could not be added to the VM instance.
|
|
|
|
/vm.add-fs:
|
|
put:
|
|
summary: Add a new virtio-fs device to the VM
|
|
requestBody:
|
|
description: The details of the new virtio-fs
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FsConfig'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new device was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
500:
|
|
description: The new device could not be added to the VM instance.
|
|
|
|
/vm.add-pmem:
|
|
put:
|
|
summary: Add a new pmem device to the VM
|
|
requestBody:
|
|
description: The details of the new pmem device
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PmemConfig'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new device was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
500:
|
|
description: The new device could not be added to the VM instance.
|
|
|
|
/vm.add-net:
|
|
put:
|
|
summary: Add a new network device to the VM
|
|
requestBody:
|
|
description: The details of the new network device
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/NetConfig'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new device was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
500:
|
|
description: The new device could not be added to the VM instance.
|
|
|
|
/vm.add-vsock:
|
|
put:
|
|
summary: Add a new vsock device to the VM
|
|
requestBody:
|
|
description: The details of the new vsock device
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VsockConfig'
|
|
required: true
|
|
responses:
|
|
200:
|
|
description: The new device was successfully added to the VM instance.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PciDeviceInfo'
|
|
500:
|
|
description: The new device could not be added to the VM instance.
|
|
|
|
|
|
/vm.snapshot:
|
|
put:
|
|
summary: Returns a VM snapshot.
|
|
requestBody:
|
|
description: The snapshot configuration
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/VmSnapshotConfig'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The VM instance was successfully snapshotted.
|
|
404:
|
|
description: The VM instance could not be snapshotted because it is not created.
|
|
405:
|
|
description: The VM instance could not be snapshotted because it is not booted.
|
|
|
|
/vm.restore:
|
|
put:
|
|
summary: Restore a VM from a snapshot.
|
|
requestBody:
|
|
description: The restore configuration
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RestoreConfig'
|
|
required: true
|
|
responses:
|
|
204:
|
|
description: The VM instance was successfully restored.
|
|
404:
|
|
description: The VM instance could not be restored because it is already created.
|
|
|
|
components:
|
|
schemas:
|
|
|
|
VmmPingResponse:
|
|
required:
|
|
- version
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
description: Virtual Machine Monitor information
|
|
|
|
VmInfo:
|
|
required:
|
|
- config
|
|
- state
|
|
type: object
|
|
properties:
|
|
config:
|
|
$ref: '#/components/schemas/VmConfig'
|
|
state:
|
|
type: string
|
|
enum: [Created, Running, Shutdown, Paused]
|
|
memory_actual_size:
|
|
type: integer
|
|
format: int64
|
|
device_tree:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/DeviceNode'
|
|
description: Virtual Machine information
|
|
|
|
DeviceNode:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
resources:
|
|
type: array
|
|
items:
|
|
# Rust enum type (with data) which can't be better represented here
|
|
type: object
|
|
children:
|
|
type: array
|
|
items:
|
|
type: string
|
|
pci_bdf:
|
|
type: integer
|
|
format: int32
|
|
|
|
VmCounters:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
format: int64
|
|
|
|
PciDeviceInfo:
|
|
required:
|
|
- id
|
|
- bdf
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
bdf:
|
|
type: string
|
|
description: Information about a PCI device
|
|
|
|
VmConfig:
|
|
required:
|
|
- kernel
|
|
type: object
|
|
properties:
|
|
cpus:
|
|
$ref: '#/components/schemas/CpusConfig'
|
|
memory:
|
|
$ref: '#/components/schemas/MemoryConfig'
|
|
kernel:
|
|
$ref: '#/components/schemas/KernelConfig'
|
|
initramfs:
|
|
$ref: '#/components/schemas/InitramfsConfig'
|
|
cmdline:
|
|
$ref: '#/components/schemas/CmdLineConfig'
|
|
disks:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DiskConfig'
|
|
net:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NetConfig'
|
|
rng:
|
|
$ref: '#/components/schemas/RngConfig'
|
|
balloon:
|
|
$ref: '#/components/schemas/BalloonConfig'
|
|
fs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/FsConfig'
|
|
pmem:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PmemConfig'
|
|
serial:
|
|
$ref: '#/components/schemas/ConsoleConfig'
|
|
console:
|
|
$ref: '#/components/schemas/ConsoleConfig'
|
|
devices:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/DeviceConfig'
|
|
vsock:
|
|
$ref: '#/components/schemas/VsockConfig'
|
|
sgx_epc:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SgxEpcConfig'
|
|
numa:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NumaConfig'
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
watchdog:
|
|
type: boolean
|
|
default: false
|
|
description: Virtual machine configuration
|
|
|
|
CpuTopology:
|
|
type: object
|
|
properties:
|
|
threads_per_core:
|
|
type: integer
|
|
cores_per_die:
|
|
type: integer
|
|
dies_per_package:
|
|
type: integer
|
|
packages:
|
|
type: integer
|
|
|
|
CpusConfig:
|
|
required:
|
|
- boot_vcpus
|
|
- max_vcpus
|
|
type: object
|
|
properties:
|
|
boot_vcpus:
|
|
minimum: 1
|
|
default: 1
|
|
type: integer
|
|
max_vcpus:
|
|
minimum: 1
|
|
default: 1
|
|
type: integer
|
|
topology:
|
|
$ref: '#/components/schemas/CpuTopology'
|
|
max_phys_bits:
|
|
type: integer
|
|
|
|
MemoryZoneConfig:
|
|
required:
|
|
- id
|
|
- size
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
default: 512 MB
|
|
file:
|
|
type: string
|
|
mergeable:
|
|
type: boolean
|
|
default: false
|
|
shared:
|
|
type: boolean
|
|
default: false
|
|
hugepages:
|
|
type: boolean
|
|
default: false
|
|
hugepage_size:
|
|
type: integer
|
|
format: int64
|
|
host_numa_node:
|
|
type: integer
|
|
format: int32
|
|
hotplug_size:
|
|
type: integer
|
|
format: int64
|
|
hotplugged_size:
|
|
type: integer
|
|
format: int64
|
|
|
|
MemoryConfig:
|
|
required:
|
|
- size
|
|
type: object
|
|
properties:
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
default: 512 MB
|
|
hotplug_size:
|
|
type: integer
|
|
format: int64
|
|
hotplugged_size:
|
|
type: integer
|
|
format: int64
|
|
mergeable:
|
|
type: boolean
|
|
default: false
|
|
hotplug_method:
|
|
type: string
|
|
default: "acpi"
|
|
shared:
|
|
type: boolean
|
|
default: false
|
|
hugepages:
|
|
type: boolean
|
|
default: false
|
|
hugepage_size:
|
|
type: integer
|
|
format: int64
|
|
zones:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/MemoryZoneConfig'
|
|
|
|
KernelConfig:
|
|
required:
|
|
- path
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
|
|
InitramfsConfig:
|
|
nullable: true
|
|
required:
|
|
- path
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
|
|
CmdLineConfig:
|
|
required:
|
|
- args
|
|
type: object
|
|
properties:
|
|
args:
|
|
type: string
|
|
|
|
DiskConfig:
|
|
required:
|
|
- path
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
readonly:
|
|
type: boolean
|
|
default: false
|
|
direct:
|
|
type: boolean
|
|
default: false
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
num_queues:
|
|
type: integer
|
|
default: 1
|
|
queue_size:
|
|
type: integer
|
|
default: 128
|
|
vhost_user:
|
|
type: boolean
|
|
default: false
|
|
vhost_socket:
|
|
type: string
|
|
poll_queue:
|
|
type: boolean
|
|
default: true
|
|
id:
|
|
type: string
|
|
|
|
NetConfig:
|
|
type: object
|
|
properties:
|
|
tap:
|
|
type: string
|
|
default: ""
|
|
ip:
|
|
type: string
|
|
default: "192.168.249.1"
|
|
mask:
|
|
type: string
|
|
default: "255.255.255.0"
|
|
mac:
|
|
type: string
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
num_queues:
|
|
type: integer
|
|
default: 2
|
|
queue_size:
|
|
type: integer
|
|
default: 256
|
|
vhost_user:
|
|
type: boolean
|
|
default: false
|
|
vhost_socket:
|
|
type: string
|
|
id:
|
|
type: string
|
|
fd:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
format: int32
|
|
|
|
RngConfig:
|
|
required:
|
|
- src
|
|
type: object
|
|
properties:
|
|
src:
|
|
type: string
|
|
default: "/dev/urandom"
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
|
|
BalloonConfig:
|
|
required:
|
|
- size
|
|
type: object
|
|
properties:
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
|
|
FsConfig:
|
|
required:
|
|
- cache_size
|
|
- dax
|
|
- num_queues
|
|
- queue_size
|
|
- socket
|
|
- tag
|
|
type: object
|
|
properties:
|
|
tag:
|
|
type: string
|
|
socket:
|
|
type: string
|
|
num_queues:
|
|
type: integer
|
|
default: 1
|
|
queue_size:
|
|
type: integer
|
|
default: 1024
|
|
dax:
|
|
type: boolean
|
|
default: true
|
|
cache_size:
|
|
type: integer
|
|
format: int64
|
|
default: 8589934592
|
|
id:
|
|
type: string
|
|
|
|
PmemConfig:
|
|
required:
|
|
- file
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
mergeable:
|
|
type: boolean
|
|
default: false
|
|
discard_writes:
|
|
type: boolean
|
|
default: false
|
|
id:
|
|
type: string
|
|
|
|
ConsoleConfig:
|
|
required:
|
|
- mode
|
|
type: object
|
|
properties:
|
|
file:
|
|
type: string
|
|
mode:
|
|
type: string
|
|
enum: [Off, Pty, Tty, File, Null]
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
|
|
DeviceConfig:
|
|
required:
|
|
- path
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
id:
|
|
type: string
|
|
|
|
VsockConfig:
|
|
required:
|
|
- cid
|
|
- socket
|
|
type: object
|
|
properties:
|
|
cid:
|
|
type: integer
|
|
format: int64
|
|
minimum: 3
|
|
description: Guest Vsock CID
|
|
socket:
|
|
type: string
|
|
description: Path to UNIX domain socket, used to proxy vsock connections.
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
id:
|
|
type: string
|
|
|
|
SgxEpcConfig:
|
|
required:
|
|
- size
|
|
type: object
|
|
properties:
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
prefault:
|
|
type: boolean
|
|
default: false
|
|
|
|
NumaDistance:
|
|
required:
|
|
- destination
|
|
- distance
|
|
type: object
|
|
properties:
|
|
destination:
|
|
type: integer
|
|
format: int32
|
|
distance:
|
|
type: integer
|
|
format: int32
|
|
|
|
NumaConfig:
|
|
required:
|
|
- guest_numa_id
|
|
type: object
|
|
properties:
|
|
guest_numa_id:
|
|
type: integer
|
|
format: int32
|
|
cpus:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
format: int32
|
|
distances:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/NumaDistance'
|
|
memory_zones:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
VmResize:
|
|
type: object
|
|
properties:
|
|
desired_vcpus:
|
|
minimum: 1
|
|
type: integer
|
|
desired_ram:
|
|
description: desired memory ram in bytes
|
|
type: integer
|
|
format: int64
|
|
desired_balloon:
|
|
description: desired balloon size in bytes
|
|
type: integer
|
|
format: int64
|
|
|
|
VmResizeZone:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
desired_ram:
|
|
description: desired memory zone size in bytes
|
|
type: integer
|
|
format: int64
|
|
|
|
VmAddDevice:
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
iommu:
|
|
type: boolean
|
|
default: false
|
|
id:
|
|
type: string
|
|
|
|
VmRemoveDevice:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
|
|
VmSnapshotConfig:
|
|
type: object
|
|
properties:
|
|
destination_url:
|
|
type: string
|
|
|
|
RestoreConfig:
|
|
required:
|
|
- source_url
|
|
type: object
|
|
properties:
|
|
source_url:
|
|
type: string
|
|
prefault:
|
|
type: boolean
|