7.7 Виртуальная машина (ВМ, или VM)
В таблице 1 представлено описание объекта Виртуальная машина.
| name | value | type |
|---|---|---|
| id | 77 | int |
| created | 1562760517 | timestamp (unix time) |
| modified | 1562760517 | timestamp (unit time) |
| create_completed | 1 | boolean |
| pool | 12800781820671582173 | numeric(20) |
| root_dataset | 12287180497637788286 | numeric(20) |
| status | 3 | int |
| oper_status | 3 | int |
| oper_status_ts | 3 | timestamp (unix time) |
| vdc | 2 | int |
| locked | 0 | boolean |
| ndmp_address | 10.78.141.203 | inet |
| name | PostgreSQL 12.0 shard03 | string(255) |
| description | Cluster05 shard03 | string |
| cpus | 2 | int (1-16) |
| ram | 2147483648 | bigint |
| cpu_priority | 3 | integer (1-20) |
| boot_media | 1 | integer |
| vcpu_class | 1 | integer |
| os_type | 1 | int |
| os_profile | 6 | int |
| guest | секция guest | кастомизация и информация о работе гостевой ОС |
| pool_selector | 2 | селектор пула для создаваемой ВМ |
| disks | [] | disk[] |
| network_ports | [] | network_port[] |
Свойство boot_media служит указателем на id образа, используемого в качестве носителя для восстановлеия (recovery media). Словарь образов можно получить с помощью метода vm-boot_media-list(). Установка данного свойства в значение 0 выключает использование recovery media.
Свойство pool_selector используется для выбора пула создаваемой виртуальной машиной. Значения предопределенных «автоматических» селекторов:
- 0 - пул с наименьшим количеством провизированного пространства;
- 1 - пул с наименьшим количеством провизированных vCPU;
- 2 - пул с наименьшим количеством провизированной RAM.
По умолчанию используется селектор 2.
Возможно явное указание идентификатора пула (guid) в качестве селектора. Это может быть полезно для размещения виртуальных машин горизонтально-масштабируемой системы «на каждом из пулов», что в штатном режиме тождественно подходу «на каждом из узлов» (при количестве пулов в кластере равном количеству узлов).
Описание объекта disk представлено в таблице 2.
| name | value | type |
|---|---|---|
| guid | 13023737523627764036 | numeric(20) |
| slot | 1 | int |
| size | 25769803776 | bigint |
| iops_limit | 3500 | int |
| mbps_limit | 128 | int |
| label | Metadata disk 17 | string(127) |
| sector_size | {} | sector_size |
Описание объекта sector_size приведено в таблице 3.
| name | value | type |
|---|---|---|
| logical | 512|4096 | int |
| physical | 512|4096 | int |
С помощью данных параметров можно привести характеристики диска к поведению тождественному 512e (512/4096) или 4kn (4096/4096). Эти параметры можно указать только при создании диска, т.к. при их изменении у уже существующих дисков изменяется адресация (LBA), что приводит к их неработоспособности.
Размер самого диска должен быть кратен размеру как логического, так и физического сектора.
В таблице 4 представлено описание объекта network_port.
| name | value | type |
|---|---|---|
| port_id | 15692 | int |
| mac | ca:07:d1:70:ab:f2 | MAC address |
| address | 10.128.15.72 | inet(4) |
| network_id | 72 | int |
| ip_guard | 0 | boolean |
| slot | 1 | int |
| ratelimit_mbits | 2048 | int |
Свойство ip_guard определяет использование фильтрации трафика на порту по IP-адресу, по умолчанию это свойство включено. Выключение возможно только для портов в изолированных сетях. Данная возможность может быть необходима для виртуальных машин, у которых несколько сетевых портов, выполняющих функцию NAT/gateway или балансировщика.
Объекты disk и network_port имеют особый параметр slot, который определяет «очерёдность» объекта, видимую для гостевой ОС.
В качестве загрузочного диска используется диск со значением slot равным 1. Размер сектора для такого диска изменить нельзя.
Методы¶
7.7.1 vm-statuses()¶
Данный метод позволяет получить список (словарь) статусов ВМ.
Запрос:
Ответ:
{
"id" : "5689dc14-ab9e-11ed-8bcc-33b94e83c07e",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"1" : "Offline",
"2" : "Starting",
"3" : "Started",
"4" : "Start failed",
"5" : "Stopping",
"6" : "Stop failed",
"7" : "Creating",
"8" : "Deleting",
"9" : "Deleted",
"10" : "Created",
"11" : "Suspended",
"12" : "Suspending",
"13" : "Suspend failed",
"14" : "Resuming",
"15" : "Resume failed",
"16" : "Create failed",
"17" : "Delete failed"
}
}
}
7.7.2 vm-profiles()¶
С помощью этого метода можно получить словарь профилей ВМ (ID для полей vm_os_type и vm_os_profile).
Запрос:
Ответ:
{
"id" : "a163d320-dad2-11e9-a9b9-6a1583008659",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"1" : {
"name" : "FreeBSD",
"profiles" : [
{
"description" : "FreeBSD 12.0-RELEASE",
"id" : 14,
"min_size" : 4294967296,
"name" : "cloud-FreeBSD-x64-12.0"
}
]
},
"6" : {
"name" : "Linux",
"profiles" : [
{
"description" : "Debian 10.1 cloud image",
"id" : 15,
"min_size" : 4294967296,
"name" : "cloud-Debian-x64-10.1"
},
{
"description" : "CentOS 7.7 cloud image",
"id" : 4,
"min_size" : 4294967296,
"name" : "cloud-CentOS-7-x86_64"
},
{
"description" : "Ubuntu 18.04 cloud image",
"id" : 8,
"min_size" : 4294967296,
"name" : "cloud-ubuntuserver-amd64-18.04"
}
]
},
"7" : {
"name" : "Windows",
"profiles" : [
{
"description" : "Windows Server 2019 standard",
"id" : 12,
"min_size" : 17179869184,
"name" : "cloud-Windows-Server-2019-standart-x64"
}
]
}
}
}
}
7.7.3 vm-boot_media-list()¶
Используя vm-boot_media-list(), можно получить словарь recovery media для свойства boot_media.
Запрос:
Ответ:
{
"id": "d0f6f026-de1a-11ea-bd0a-2ad555bcd16b",
"jsonrpc": "2.0",
"result": {
"code": 1,
"data": {
"0": "none",
"1": "FreeBSD 12.1-RELEASE",
"2": "SystemRescueCD-amd64-6.1.7"
}
}
}
7.7.4 vm-list()¶
Этот метод позволяет получить список ВМ. При отсутствии в запросе секции params->vdc будет возвращен список всех ВМ из всех ВЦОД, доступных пользователю.
В ответ включены два элемента, которые не являются явными свойствами объекта ВМ: address и storage_provisioned. Они носят вспомогательный характер для предотвращения необходимости вызова метода vm-get() для каждого экземпляра ВМ. При этом элемент address содержит IP-адрес NIC из первого слота.
Запрос:
Ответ:
{
"id" : "8189a890-9640-11ed-90f4-7f5fb0b91e77",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : [
{
"address" : "10.78.27.22",
"admin_status" : 1,
"cpu_count" : 2,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 2147483648,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 15032385536,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1030,
"vm_name" : "vStack top performance VM",
"vm_status" : 1
},
{
"address" : "10.78.27.38",
"admin_status" : 1,
"cpu_count" : 2,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 2147483648,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 70866960384,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1052,
"vm_name" : "free z03 good",
"vm_status" : 1
},
{
"address" : "10.78.27.36",
"admin_status" : 1,
"cpu_count" : 1,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 1073741824,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 15032385536,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1053,
"vm_name" : "free z03 remove me",
"vm_status" : 1
},
]
}
}
При указании параметра objective возможно получение альтернативного варианта ответа:
Уровень 1: vm_id
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-list",
"id": "2141f914-9641-11ed-b2b5-36f3aeb91e77",
"params": {
"objective": "yo"
}
}
Ответ:
{
"id" : "2141f914-9641-11ed-b2b5-36f3aeb91e77",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"1030" : {
"address" : "10.78.27.22",
"admin_status" : 1,
"cpu_count" : 2,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 2147483648,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 15032385536,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1030,
"vm_name" : "vStack top performance VM",
"vm_status" : 1
},
"1052" : {
"address" : "10.78.27.38",
"admin_status" : 1,
"cpu_count" : 2,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 2147483648,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 70866960384,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1052,
"vm_name" : "free z03 good",
"vm_status" : 1
},
"1053" : {
"address" : "10.78.27.36",
"admin_status" : 1,
"cpu_count" : 1,
"create_completed" : 1,
"hw_version" : 4,
"locked" : 0,
"memory_count" : 1073741824,
"oper_status" : 1,
"oper_status_ts" : 1672301415,
"os_profile" : 1031,
"os_type" : 1,
"storage_provisioned" : 15032385536,
"vcpu_class" : 1,
"vdc_id" : 1000,
"vm_id" : 1053,
"vm_name" : "free z03 remove me",
"vm_status" : 1
}
}
}
}
7.7.5 vm-history()¶
С помощью vm-history() можно получить историю состояния ВМ. Словарь статусов ВМ возвращает метод vm-statuses().
Опциональные параметры ts_start и ts_finish могут использоваться для ограничения вывода диапазоном времени.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-history",
"id": "3d9bf2be-ab99-11ed-b667-a3ba4e83c07e",
"params": {
"vm_id": 5041,
"lines": 105
}
}
Ответ:
{
"id" : "3d9bf2be-ab99-11ed-b667-a3ba4e83c07e",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : [
{
"progress" : 30,
"status" : 7,
"ts" : 1676291002,
"ts_nano" : 1676291001776543
},
{
"progress" : 100,
"status" : 10,
"ts" : 1676291002,
"ts_nano" : 1676291002114813
},
{
"progress" : 0,
"status" : 7,
"ts" : 1676291002,
"ts_nano" : 1676291002182200
},
{
"progress" : 50,
"status" : 7,
"ts" : 1676291002,
"ts_nano" : 1676291002186576
},
{
"progress" : 100,
"status" : 10,
"ts" : 1676291002,
"ts_nano" : 1676291002190521
},
{
"progress" : 0,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033341247
},
{
"progress" : 10,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033345756
},
{
"progress" : 20,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033350039
},
{
"progress" : 30,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033353878
},
{
"progress" : 40,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033358191
},
{
"progress" : 90,
"status" : 2,
"ts" : 1676291033,
"ts_nano" : 1676291033362514
},
{
"progress" : 100,
"status" : 3,
"ts" : 1676291035,
"ts_nano" : 1676291034844467
},
{
"progress" : 90,
"status" : 5,
"ts" : 1676291266,
"ts_nano" : 1676291266208952
},
{
"progress" : 100,
"status" : 1,
"ts" : 1676291266,
"ts_nano" : 1676291266216060
},
{
"progress" : 0,
"status" : 2,
"ts" : 1676291266,
"ts_nano" : 1676291266220959
},
{
"progress" : 20,
"status" : 2,
"ts" : 1676291266,
"ts_nano" : 1676291266225953
},
{
"progress" : 30,
"status" : 2,
"ts" : 1676291266,
"ts_nano" : 1676291266231047
},
{
"progress" : 40,
"status" : 2,
"ts" : 1676291266,
"ts_nano" : 1676291266235765
},
{
"progress" : 90,
"status" : 2,
"ts" : 1676291266,
"ts_nano" : 1676291266240700
},
{
"progress" : 100,
"status" : 3,
"ts" : 1676291268,
"ts_nano" : 1676291267738372
},
{
"progress" : 0,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304680461
},
{
"progress" : 10,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304685137
},
{
"progress" : 20,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304689507
},
{
"progress" : 30,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304693717
},
{
"progress" : 40,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304698013
},
{
"progress" : 50,
"status" : 5,
"ts" : 1676291305,
"ts_nano" : 1676291304702592
},
{
"progress" : 90,
"status" : 5,
"ts" : 1676291316,
"ts_nano" : 1676291315719761
},
{
"progress" : 100,
"status" : 1,
"ts" : 1676291316,
"ts_nano" : 1676291315727029
}
]
}
}
Запрос с опциональными параметрами:
{
"jsonrpc": "2.0",
"method": "vm-history",
"id": "6161098a-ac54-11ed-962d-00244f83c07e",
"params": {
"vm_id": 5041,
"ts_start": 1676291305,
"ts_finish": 1776291305
}
}
{
"id" : "6161098a-ac54-11ed-962d-00244f83c07e",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : [
{
"progress" : 90,
"status" : 5,
"ts" : 1676291316,
"ts_nano" : 1676291315719761
},
{
"progress" : 100,
"status" : 1,
"ts" : 1676291316,
"ts_nano" : 1676291315727029
}
]
}
}
7.7.6 vm-get()¶
Этот метод позволяет получить свойства ВМ.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-get",
"id": "87752d96-9641-11ed-b22c-7d10afb91e77",
"params": {
"id": 1408
}
}
Ответ:
{
"id" : "87752d96-9641-11ed-b22c-7d10afb91e77",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"admin_status" : 1,
"boot_media_id" : 0,
"cpu_priority" : 1,
"cpus" : 32,
"create_completed" : 1,
"created" : 1651234850,
"description" : null,
"disks" : [
{
"guid" : "14141982221421462910",
"iops_limit" : null,
"label" : null,
"mbps_limit" : null,
"sector_size" : {
"logical" : 512,
"physical" : 4096
},
"size" : 107374182400,
"slot" : 1
}
],
"gc_id" : 2,
"gc_name" : "Cloud-init: SmartOS",
"guest" : {
"ram_balloon_performed": 4294967296,
"ram_balloon_requested": 4294967296,
"ram_used": 6545944576
},
"hv_faults" : {
"sigabort" : {
"interval" : 60,
"restarts" : 5
}
},
"hw_version" : 4,
"id" : 1408,
"incarnation" : 16723014161,
"locked" : 0,
"modified" : 1672301416,
"name" : "freebsd32vcpu",
"ndmp_address" : "10.78.141.203",
"network_ports" : [
{
"address" : "10.78.27.131",
"ip_guard" : 1,
"mac" : "ca:09:ed:4d:63:e2",
"network_id" : 101,
"port_id" : 1706,
"ratelimit_mbits" : null,
"slot" : 1
}
],
"oper_status" : 1,
"oper_status_ts" : 1672301419,
"os_profile" : "1031",
"os_type" : 1,
"pool" : "4182847010042355858",
"ram" : 2147483648,
"root_dataset" : 7816353313262474251,
"status" : 1,
"vcpu_class" : 0,
"vdc" : 1000
}
}
}
7.7.7 vms-create()¶
С помощью vms-create() можно создавать ВМ.
В данном примере создается ВМ с двумя дисками, второй из которых создаётся в виде 4kn. Кроме этого, создаются две NIC, и IP-адреса назначаются автоматически с использованием функциональности пула IP-адресов каждой из сетей.
В секции настроек гостевой ОС описаны назначение пользователю root двух SSH-ключей и установка пароля, создание пользователя volobuev, назначение ему одного SSH-ключа и установка пароля, а также назначение конфигурации resolver, установка hostname и назначение команды, выполняемой при каждой загрузке.
Запрос:
{
"jsonrpc": "2.0",
"method": "vms-create",
"id": "de2ccf8c-764f-11ea-8c88-601744f6ef2b",
"params": {
"name": "Ubuntu docker/snap",
"description": null,
"cpus": 2,
"ram": 4294967296,
"os_type": 6,
"os_profile": 8,
"vdc_id": 8,
"disks" : [
{
"size": 23622352896,
"slot": 1
},
{
"sector_size": {
"logical": 4096,
"physical": 4096
},
"size": 47244705792,
"label": "44GB 4Kn redo logs",
"slot": 2
}
],
"network_ports" : [
{
"network_id": 1,
"slot": 1
},
{
"network_id": 4,
"slot": 2
}
],
"guest": {
"users": {
"root": {
"ssh-authorized-keys": [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEkIzoBL/vwQ1fbdhH8MGq/CPXA1QQtU2buiy03sVbn5 evgueni.gavrilov@vStack.com",
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJnT4MAS9coPy2nZhOiXXQeLcc4RoCaQJEBMbSp4ZAhs allan@vStack.com"
],
"password": "$6$csNIFbubwcx.vLWM$ua7n12KtekpzPhYi8hSS5xSITPFAyOwGKylUam4owBbtZVO2uUH1t3d8PcZj3f.w6OsSgODbRy8mozhDSCBjV."
},
"volobuev": {
"ssh-authorized-keys": [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILBz8xQUuLBZzVqSph0RGVLIuqyYMOTLYp/y1e3jmV7F vol@nsa.gov"
],
"password": "$6$csNIFbubwcx.vLWM$ua7n12KtekpzPhYi8hSS5xSITPFAyOwGKylUam4owBbtZVO2uUH1t3d8PcZj3f.w6OsSgODbRy8mozhDSCBjV."
}
},
"ssh_password_auth": 1,
"resolver": {
"name_server": [
"8.8.8.8",
"8.8.4.4",
"1.1.1.1"
],
"search": "nsa.gov"
},
"boot_cmds": [
"swapoff -a"
],
"run_cmds": [
"systemctl restart ntpd"
],
"hostname": "ubuntu-07-snap.docker.us.nsa.gov"
}
}
}
Ответ:
{
"id" : "de2ccf8c-764f-11ea-8c88-601744f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"cpus" : 2,
"create_completed" : 1,
"created" : 1585989706,
"description" : null,
"disks" : [
{
"guid" : "18299855202392410869",
"iops_limit" : null,
"mbps_limit" : null,
"sector_size" : {
"logical" : 512,
"physical" : 4096
},
"size" : 23622352896,
"slot" : 1
},
{
"guid" : "1075373250829122474",
"iops_limit" : null,
"label": "44GB 4Kn redo logs",
"mbps_limit" : null,
"sector_size" : {
"logical" : 4096,
"physical" : 4096
},
"size" : 47244705792,
"slot" : 2
}
],
"hw_version" : 4,
"id" : 2088,
"incarnation" : 15859897060,
"modified" : 1585989706,
"name" : "Ubuntu docker/snap",
"network_ports" : [
{
"address" : "10.78.28.119",
"mac" : "ca:07:49:25:ab:6c",
"network_id" : 1,
"port_id" : 1411,
"ratelimit_mbits" : null,
"slot" : 1
},
{
"address" : "10.100.200.25",
"mac" : "ca:07:c8:a3:c6:fa",
"network_id" : 4,
"port_id" : 1412,
"ratelimit_mbits" : null,
"slot" : 2
}
],
"os_profile" : 8,
"os_type" : 6,
"pool" : "1139178722141106475",
"ram" : 4294967296,
"root_dataset" : "14979019997914453111",
"status" : 10,
"vdc" : 8
}
}
}
7.7.8 vm-change-vdc()¶
vm-change-vdc() позволяет сменить ВЦОД у ВМ (перенести ВМ из одного ВЦОД в другой). Использование данного метода возможно при следующих условиях:
- Пользователь, выполняющий данную операцию, назначена роль Админа ВЦОД в обоих ВЦОД.
- В обоих ВЦОД есть все сети, используемые в ВМ.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-change-vdc",
"id": "1ccca298-c822-11ea-b43f-e7f855bcd16b",
"params": {
"vm_id": 1141,
"src_vdc": 15,
"dst_vdc": 72
}
}
Ответ:
{
"id" : "1ccca298-c822-11ea-b43f-e7f855bcd16b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "Changed without errors"
}
}
}
7.7.9 vms-add-disk()¶
Добавление диска к ВМ.
Параметр slot является опциональным. При его отсутствии будет использован первый свободный слот.
После успешного выполнения запроса необходимо выполнить рестарт ВМ (не перезагрузку гостевой ОС).
Запрос:
{
"jsonrpc": "2.0",
"id": "b797ae5e-839d-11ea-b900-6b3f44f6ef2b",
"method": "vms-add-disk",
"params": {
"vm_id": 2214,
"size": 1073741824,
"slot": 5,
"label": "4Kn 1GB redo for standby",
"sector_size": {
"logical": 4096,
"physical": 4096
}
}
}
Ответ:
{
"id" : "b797ae5e-839d-11ea-b900-6b3f44f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"guid" : "11143651807831677732",
"sector_size" : {
"logical" : 4096,
"physical" : 4096
},
"size" : 1073741824,
"label": "4Kn 1GB redo for standby",
"slot" : 5
}
}
}
7.7.10 vms-add-nic()¶
С помощью vms-add-nic() можно добавить сетевую карту (NIC) к ВМ.
Параметр slot является опциональным. При его отсутствии будет использован первый свободный слот.
Добавление сетевого интерфейса возможно только к ВМ, находящейся в состоянии offline.
Запрос:
{
"jsonrpc": "2.0",
"id": "fc771022-839e-11ea-b5bc-477f44f6ef2b",
"method": "vms-add-nic",
"params": {
"id": 2251,
"network_id": 7,
"slot": 3
}
Ответ:
{
"jsonrpc": "2.0",
"id": "fc771022-839e-11ea-b5bc-477f44f6ef2b",
"result": {
"code": 1,
"data": {
"address": "10.70.10.6",
"mac": "ca:07:97:e0:92:c5",
"network_id": 7,
"port_id": 1697,
"slot": 3
}
}
}
7.7.11 vms-disk-resize()¶
Используя метод vms-disk-resize(), можно увеличить размер диска. В зависимости от гостевой операционной системы, её версии и конфигурации может понадобиться или не понадобиться обновление информации о дисках (т.е. rescan).
Запрос:
{
"jsonrpc": "2.0",
"id": "c41b3a76-7e19-11ea-8239-053143f6ef2b",
"method": "vms-disk-resize",
"params": {
"id": 2214,
"disk_guid": 5781408142104719029,
"size": 4294967296
}
}
Ответ:
7.7.12 vm-disk-set-label()¶
С помощью метода vm-disk-set-label() можно изменить метку диска.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-disk-set-label",
"id": "f4dcb9f0-3fa6-11eb-b6cb-a9662812b729",
"params": {
"vm_id": 3558,
"guid": 12832987975931186134,
"label": "Arch logs for now"
}
}
Ответ:
7.7.13 vms-snapshot()¶
Данный метод позволяет создать снимок ВМ.
Снимок ВМ представляет из себя состояние ВМ (дисков, конфигурации) в определенный момент времени.
Также возможен откат к снимку ВМ, но при этом все последующие снимки удаляются. Размер снимка отражает объем изменений, произошедших в дисках ВМ с момента создания снимка.
В имени снимка разрешены символы [A-Z,a-z,0-9,_].
Запрос:
{
"jsonrpc": "2.0",
"id": "c4afa444-7e56-11ea-94c3-2e7544f6ef2b",
"method": "vms-snapshot",
"params": {
"vm_id": 2200,
"snapshot_name": "20200414_1651"
}
}
Ответ:
{
"id" : "c4afa444-7e56-11ea-94c3-2e7544f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"guid" : "11129989502823419063",
"name" : "20200414_1651",
"time" : "1586872285"
}
}
}
7.7.14 vm-snapshot-list()¶
Этот метод позволяет получить список снимков ВМ.
При указании опционального параметра objective возможен альтернативный вариант ответа.
Запрос:
{
"jsonrpc": "2.0",
"id": "e21903c4-7e63-11ea-bcb5-76c343f6ef2b",
"method": "vm-snapshot-list",
"params": {
"vm_id": 2200
}
}
Ответ:
{
"id" : "e21903c4-7e63-11ea-bcb5-76c343f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : [
{
"creation_time" : 1586872285,
"guid" : "11129989502823419063",
"name" : "20200414_1651",
"size" : 0
},
{
"creation_time" : 1586856415,
"guid" : "15105571301450284651",
"name" : "20200414_1226",
"size" : 22521384
},
{
"creation_time" : 1586872190,
"guid" : "17564511416473906207",
"name" : "20200414_1649",
"size" : 0
},
{
"creation_time" : 1586859834,
"guid" : "6457973076157998916",
"name" : "20200414_1323",
"size" : 4785630480
}
]
}
}
Запрос (objective):
{
"jsonrpc": "2.0",
"id": "e2190900-7e63-11ea-bcb5-76c343f6ef2b",
"method": "vm-snapshot-list",
"params": {
"vm_id": 2200,
"objective": 100
}
}
Ответ (objective):
{
"id" : "e2190900-7e63-11ea-bcb5-76c343f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"11129989502823419063" : {
"creation_time" : 1586872285,
"guid" : "11129989502823419063",
"name" : "20200414_1651",
"size" : 0
},
"15105571301450284651" : {
"creation_time" : 1586856415,
"guid" : "15105571301450284651",
"name" : "20200414_1226",
"size" : 22521384
},
"17564511416473906207" : {
"creation_time" : 1586872190,
"guid" : "17564511416473906207",
"name" : "20200414_1649",
"size" : 0
},
"6457973076157998916" : {
"creation_time" : 1586859834,
"guid" : "6457973076157998916",
"name" : "20200414_1323",
"size" : 4785630480
}
}
}
}
7.7.15 vms-rollback()¶
С помощью этого метода можно откатить ВМ к состоянию на тот момент, когда был сделан снимок ВМ.
При откате ВМ к состоянию на время выбранного снимка все снимки, сделанные после указанного снимка, безвозвратно удаляются. Снимок, к которому выполняется процедура отката, остается.
Запрос:
{
"jsonrpc": "2.0",
"id": "de1be646-7f31-11ea-864f-a13f43f6ef2b",
"method": "vms-rollback",
"params": {
"vm_id": 2200,
"snapshot_name": "20200414_1323"
}
}
Ответ:
{
"id" : "de1be646-7f31-11ea-864f-a13f43f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "Welcome back to the future"
}
}
}
7.7.16 vm-remove-nic()¶
Данный метод позволяет удалить сетевой интерфейс (NIC) у ВМ.
Конфигурация NIC сохраняется при наличии у виртуальной машины снимков для возможности отката к ним. Аналогичным образом резервируется slot, в который назначен данный NIC.
Удаление сетевого интерфейса возможно только у ВМ, находящейся в состоянии offline.
Запрос:
{
"jsonrpc": "2.0",
"id": "08d9d1b6-8470-11ea-9b1a-9d6a44f6ef2b",
"method": "vm-remove-nic",
"params": {
"vm_id": 2251,
"port_id": 1697
}
}
Ответ:
{
"id" : "08d9d1b6-8470-11ea-9b1a-9d6a44f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "NIC of port_id=1697 has been removed",
}
}
}
7.7.17 vms-snapshot-remove()¶
Используя vms-snapshot-remove(), можно удалить снимок ВМ.
При наличии в снимке конфигурации элементов, которые были удалены после его создания, такие элементы безвозвратно удаляются.
Запрос:
{
"jsonrpc": "2.0",
"id": "ddcf336a-84b2-11ea-8ad8-e37744f6ef2b",
"method": "vms-snapshot-remove",
"params": {
"vm_id": 2251,
"snapshot_name": "20200421_1757"
}
}
Ответ:
{
"id" : "ddcf336a-84b2-11ea-8ad8-e37744f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "Snapshot has been removed"
}
}
}
7.7.18 vm-remove-disk()¶
Используя метод vm-remove-disk(), можно удалить диск ВМ.
При наличии снимка ВМ, созданного до удаления диска, диск, его slot и конфигурация будут удержаны для возможности отката к этому снимку. При его удалении будет удален и диск.
Операция удаления диска возможна только у ВМ, которая находится в состоянии offline.
Запрос:
{
"jsonrpc": "2.0",
"id": "76f8b1b8-8640-11ea-a8ae-b89e43f6ef2b",
"method": "vm-remove-disk",
"params": {
"vm_id": 2297,
"disk_guid": "18159859341532866844"
}
}
Ответ:
{
"id" : "76f8b1b8-8640-11ea-a8ae-b89e43f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "disk 18159859341532866844 has been removed"
}
}
}
7.7.19 vm-ratelimit-disk()¶
С помощью этого метода можно установить ограничения на производительность диска ВМ. Данная возможность может быть полезна для исключения негативного влияние одной ВМ, потребляющей большое количество ресурса IO.
Возможна установка лимита пропускной способности (mbps_limit) как совместно с лимитом IOps (iops_limit), так и отдельно.
Для снятия лимита необходимо отправить значение необходимого параметра равное нулю (0). Изменение данного параметра на работающей ВМ применяется сразу.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-ratelimit-disk",
"id": "fd086efc-8df1-11ea-9fdf-daa043f6ef2b",
"params": {
"vm_id": 1141,
"disk_guid": 5793432017665474692,
"mbps_limit": 256,
"iops_limit": 200
}
}
Ответ:
{
"id" : "fd086efc-8df1-11ea-9fdf-daa043f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "Ratelimit has been set"
}
}
}
7.7.20 vm-ratelimit-nic()¶
Этот метод позволяет установить ограничения производительности сетевого интерфейса (NIC) ВМ. Данная возможность может быть полезной для исключения негативного влияния одной ВМ, потребляющей большое количество сетевых ресурсов.
Для снятия лимита необходимо отправить значение параметра ratelimit_mbits равное нулю (0). Изменение данного параметра на работающей ВМ применяется сразу.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-ratelimit-nic",
"id": "fd086fec-8df1-11ea-9fdf-daa043f6ef2b",
"params": {
"vm_id": 1141,
"port_id": 1125,
"ratelimit_mbits": 33
}
}
Ответ:
{
"id" : "fd086fec-8df1-11ea-9fdf-daa043f6ef2b",
"jsonrpc" : "2.0",
"result" : {
"code" : 1,
"data" : {
"message" : "Ratelimit has been set"
}
}
}
7.7.21 vms-vcpu-class()¶
С помощью vms-vcpu-class() можно установить класс vCPU ВМ. Класс определяет методику выделения квантов vCPU в условиях overcommit.
Таблица описания классов vCPU представлена ниже.
| class | Описание |
|---|---|
| 0 | выделение квантов vCPU без ограничений |
| 1 | конфигурация выделения квантов изменяется динамически исходя из утилизации физических CPU хоста |
| 2 | класс с фиксированной конфигурацией для ВМ с чрезмерным использованием vCPU |
| 3 | пользовательский класс 3 |
| 4 | пользовательский класс 4 |
| 5 | пользовательский класс 5 |
По умолчанию у ВМ установлен 1 класс.
Запрс:
{
"jsonrpc": "2.0",
"id": "92560366-7ea0-11ec-8338-4bc064c0ce9b",
"method": "vms-vcpu-class",
"params": {
"vm_id": 5932,
"vcpu_class": 3
}
}
Ответ:
{
"id": "92560366-7ea0-11ec-8338-4bc064c0ce9b",
"jsonrpc": "2.0",
"result": {
"code": 1
"data": {}
}
7.7.22 vms-start(), vms-stop(),vms-restart()¶
Эти методы позволяют соответственно запускать, останавливать и перезагружать ВМ. Для vms-stop() и vms-restart() опционально могут быть использованы следующие параметры:
- noacpi: при изменении данного парметра на 1 происходит выключение/рестарт ВМ без использования ACPI.
- hard_timeout: при использовании ACPI ждать N секунд выключения ВМ средствами гостевой ОС, после чего выключить машину.
Запрос:
{
"jsonrpc": "2.0",
"method": "vms-stop",
"id": "c0a6127e-563e-11ea-8e17-1fac9c0cd5ca",
"params": {
"id": 31
}
}
Ответ:
{
"id": "c0a6127e-563e-11ea-8e17-1fac9c0cd5ca",
"jsonrpc": "2.0",
"result" : {
"code" : 1,
"data" : {
}
}
}
7.7.23 vm-set()¶
Используя метод vm-set() можно установить свойства ВМ. Необязательно использовать все свойства, можно изменить только необходимые.
Запрос:
{
"jsonrpc": "2.0",
"method": "vm-set",
"id": "b063e954-b12f-11e9-8b23-18091bc8006e",
"params": {
"id": 32,
"vm_params": {
"cpus": 4,
"ram": 2147483648,
"name": "CPU test 32",
"description": "CPU tricks (всяккая шляпа, например)"
}
}
}
Ответ:
7.7.24 vm-console()¶
Этот метод позволяет получить реквизиты в виде WSS URL для подключения к консоли ВМ.
При наличии существующего подключения оно прерывается. В качестве параметра передается VM ID.
Запрос:
{
"jsonrpc": "2.0",
"id": "a845e8e2-ab54-11ea-b5b5-1d5a8c0e90c8",
"method": "vm-console",
"params": {
"id": 41
}
}
Ответ:
{
"id": "a845e8e2-ab54-11ea-b5b5-1d5a8c0e90c8",
"jsonrpc": "2.0",
"result": {
"code": 1,
"data": {
"id": 41,
"wss": "wss://wss.jp17.z.vstack.com/.wss/wss96078107_40434067_44716324"
}
}
}
7.7.25 vm-perfdata()¶
С помощью vm-perfdata() можно запросить данные о производительности (performance data) ВМ. Возможные метрики (параметр metric):
- CPU;
- disk;
- net;
- RAM;
- all (всё вышеперечисленное).
Также есть возможность указания отрезка времени в виде интервала от текущего момента, либо с явным указанием начала и конца отрезка времени.
Запрос (интервал):
{
"jsonrpc": "2.0",
"method": "vm-perfdata",
"id": "79af636a-ea6a-11e9-b548-9796663b5a12",
"params": {
"metric": "cpu",
"vm_id": 389,
"interval": "3m",
"slice": "1m"
}
}
Запрос (явное указание начала и конца):
{
"jsonrpc": "2.0",
"method": "vm-perfdata",
"id": "c202de98-6989-11ed-a676-9482afb91e77",
"params": {
"metric": "all",
"vm_id": 1764,
"begin_time": 1669024800,
"end_time": 1669025400,
"slice": "1m"
}
}
Ответ:
{
"id": "c202de98-6989-11ed-a676-9482afb91e77",
"jsonrpc": "2.0",
"result": {
"code": 1,
"data": {
"results": [
{
"series": [
{
"columns": [
"time",
"cpu",
"vm_cpus"
],
"name": "bhyve_cpu",
"values": [
[
1669024800,
1,
2
],
[
1669024860,
1,
2
],
[
1669024920,
1,
2
],
[
1669024980,
3.83333333333333,
2
],
[
1669025040,
43,
2
],
[
1669025100,
15.5,
2
],
[
1669025160,
1,
2
],
[
1669025220,
1,
2
],
[
1669025280,
1,
2
],
[
1669025340,
1,
2
]
]
}
],
"statement_id": 0
},
{
"series": [
{
"columns": [
"time",
"read_bytes",
"write_bytes",
"read_iops",
"write_iops"
],
"name": "virtio_blk",
"tags": {
"slot": "1"
},
"values": [
[
1669024800,
0,
0,
0,
0
],
[
1669024860,
0,
0,
0,
0
],
[
1669024920,
0,
0,
0,
0
],
[
1669024980,
232163.555555556,
5176.88888888856,
2.3,
0.277777777777768
],
[
1669025100,
1479479.46666667,
2060340.62222222,
28.4055555555556,
58.35
],
[
1669025160,
0,
397266.488888889,
0,
1.49444444444445
],
[
1669025220,
0,
0,
0,
0
],
[
1669025280,
0,
0,
0,
0
],
[
1669025340,
0,
216.177777777612,
0,
0.0416666666666667
]
]
},
{
"columns": [
"time",
"read_bytes",
"write_bytes",
"read_iops",
"write_iops"
],
"name": "virtio_blk",
"tags": {
"slot": "2"
},
"values": [
[
1669024800,
0,
0,
0,
0
],
[
1669024860,
0,
0,
0,
0
],
[
1669024920,
0,
0,
0,
0
],
[
1669024980,
0,
0,
0,
0
],
[
1669025040,
null,
0,
null,
0
],
[
1669025100,
9011.2,
0,
0.425,
0
],
[
1669025160,
0,
0,
0,
0
],
[
1669025220,
0,
0,
0,
0
],
[
1669025280,
0,
0,
0,
0
],
[
1669025340,
0,
0,
0,
0
]
]
}
],
"statement_id": 1
},
{
"series": [
{
"columns": [
"time",
"rx_bytes",
"tx_bytes",
"rx_pps",
"tx_pps"
],
"name": "virtio_net",
"tags": {
"slot": "1"
},
"values": [
[
1669024800,
17.6666666666667,
14.6666666666667,
0.222222222222626,
0.222222222222172
],
[
1669024860,
10,
0,
0.138888888889293,
0
],
[
1669024920,
45.3333333333333,
23.3333333333333,
0.583333333333333,
0.333333333333333
],
[
1669024980,
18157.8611111111,
992.527777777781,
16.3611111111107,
6.86111111111116
],
[
1669025040,
386863.916666667,
null,
null,
null
],
[
1669025100,
4601257.88888889,
22487.9722222222,
2070.91666666667,
148
],
[
1669025160,
209.5,
143.5,
2.08333333333333,
1.91666666666667
],
[
1669025220,
223.166666666667,
141.666666666667,
2.25,
1.83333333333333
],
[
1669025280,
218.666666666667,
142.166666666667,
2.22222222222202,
1.91666666666667
],
[
1669025340,
220,
153.5,
2.19444444444465,
2.02777777777775
]
]
}
],
"statement_id": 2
},
{
"series": [
{
"columns": [
"time",
"guest_mem",
"VM_mem",
"hv_mem"
],
"name": "bhyve_cpu",
"values": [
[
1669024800,
220057600,
4382359552,
541466624
],
[
1669024860,
220057600,
4382359552,
541466624
],
[
1669024920,
220057600,
4382359552,
541466624
],
[
1669024980,
234446848,
4382359552,
571880106.666667
],
[
1669025040,
351754922.666667,
4381638656,
848883712
],
[
1669025100,
550424576,
4382359552,
903999488
],
[
1669025160,
573599744,
4382359552,
903999488
],
[
1669025220,
573599744,
4382359552,
903999488
],
[
1669025280,
573599744,
4382359552,
903999488
],
[
1669025340,
573599744,
4382359552,
903999488
]
]
}
],
"statement_id": 3
}
]
}
}
}
7.7.26 vms-remove()¶
Данный метод позволяет удалить ВМ.
Запрос:
{
"jsonrpc": "2.0",
"method": "vms-remove",
"id": "c0a6172e-563e-11ea-8e17-1fac9c0cd5ca",
"params": {
"id": 46,
"vdc_id": 2
}
}
Ответ:
{
"id": "c0a6172e-563e-11ea-8e17-1fac9c0cd5ca",
"jsonrpc": "2.0",
"result": {
"code": 1,
"data": {
"Message": "..."
}
}
}
7.7.27 vms-suspend()¶
С помощью этого метода можно приостановить работу ВМ.
Запрос:
{
"id": "2ba6396c-f2f7-11ec-894e-34bbd613a730",
"jsonrpc": "2.0",
"method": "vms-suspend",
"params": {
"vm_id": 1423
}
}
Ответ:
{
"id": "2ba6396c-f2f7-11ec-894e-34bbd613a730",
"jsonrpc": "2.0",
"result" : {
"code": 1,
"data": {}
}
}
7.7.28 vms-resume()¶
vms-resume() позволяет возобновить работу ВМ, которая была ранее приостановлена с помощью vms-suspend().
Запрос:
{
"id": "23218486-f2f7-11ec-ad2f-6cb9d613a730",
"jsonrpc": "2.0",
"method": "vms-resume",
"params": {
"vm_id": 1423
}
}
Ответ:
{
"id": "23218486-f2f7-11ec-ad2f-6cb9d613a730",
"jsonrpc": "2.0",
"result": {
"code": 1,
"data": {}
}
}
7.7.29 vms-balloon()¶
С помощью vms-balloon() можно освободить RAM гостевой ОС виртуальной машины таким образом, чтобы освобождение памяти затронуло и гипервизор.
Работа этой функции происходит в два этапа:
- Метод вызывается с ненулевым значением параметра bytes (указанный объём памяти распределяется в гостевой ОС).
- Метод вызывается с нулевым значением параметра bytes (указанный объём памяти освобождается и в гостевой ОС, и на уровне гипервизора)
Доступна при ненулевом значении кластерной опции feature.balloon.
Запрос:
{
"jsonrpc": "2.0",
"id": "1c809bb6-4302-11ed-a338-f8ffafb91e77",
"method": "vms-balloon",
"params": {
"vm_id": 1694,
"bytes": 4096
}
}
Ответ: