DocsKnowledge BaseAPI Explorer
Documentation›Explore more›ZStack ZSphere›API ReferenceZVF
Document navigation

PCI Device Related APIs

QueryPciDevice

API Request

URL
GET zstack/v1/pci-device/pci-devices
GET zstack/v1/pci-device/pci-devices/{uuid}
Header
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/pci-devices
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/pci-devices/051c4bc794a33acc95d5cb0caa56e7b4

Queryable Fields

Run the CLI command tool, enter QueryPciDevice and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {}
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventories List See inventories 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 0.6
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
QueryPciDeviceAction action = new QueryPciDeviceAction();
action.conditions = asList();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryPciDeviceAction.Result res = action.call();
Python SDK
QueryPciDeviceAction action = QueryPciDeviceAction()
action.conditions = []
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryPciDeviceAction.Result res = action.call()

DeletePciDevice

Delete an invalid PCI device. Only PCI devices in Inactive state can be deleted.

API Request

URLs
DELETE zstack/v1/pci-device/pci-devices/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/pci-device/pci-devices/07e2500b59c03a5b8ea3382e083efbd6
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.1
deleteMode (Optional) String url Optional. The delete mode. 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

On success, this API returns an empty JSON structure {}. On error, the returned JSON structure contains an error field. For example: 
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Examples

Java SDK
DeletePciDeviceAction action = new DeletePciDeviceAction();
action.uuid = "07e2500b59c03a5b8ea3382e083efbd6";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeletePciDeviceAction.Result res = action.call();
Python SDK
DeletePciDeviceAction action = DeletePciDeviceAction()
action.uuid = "07e2500b59c03a5b8ea3382e083efbd6"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeletePciDeviceAction.Result res = action.call()

UpdatePciDevice

API Request

URL
PUT zstack/v1/pci-device/pci-devices/{uuid}/actions
Header
Authorization: OAuth the-session-uuid
Body
{
  "updatePciDevice": {
    "state": "Disabled",
    "name": "test pci",
    "description": "test pci",
    "metaData": "key1:value1;key2:value2"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the example above, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updatePciDevice":{"state":"Disabled","name":"test pci","description":"test pci","metaData":"key1:value1;key2:value2"}}' \
http://localhost:8080/zstack/v1/pci-device/pci-devices/4bec7e7c2c1e337599e0455165906fd5/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.1
state (Optional) String body (contained in the updatePciDevice structure) Optional. The resource state.
  • Enabled
  • Disabled
 2.1
description (Optional) String body (contained in the updatePciDevice structure) Resource description 2.1
metaData (Optional) String body (contained in the updatePciDevice structure) Optional. The metadata. 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

Response Example
{
  "inventory": {
    "description": "test pci",
    "hostUuid": "47c749c4520c3c5ba2ddcb6bf725cc40",
    "vmInstanceUuid": "8452e9231dd339158054902001b453d0",
    "type": "GPU_Video_Controller",
    "state": "Disabled",
    "status": "Active",
    "vendorId": "10de",
    "deviceId": "0e0f",
    "subvendorId": "10de",
    "subdeviceId": "118b",
    "pciDeviceAddress": "0000:06:00.1",
    "metaData": {
      "metaData": "render:Equal:true;anime:Equal:true",
      "metaDataEntries": [
        {
          "key": "render",
          "op": "Equal",
          "value": "true"
        },
        {
          "key": "anime",
          "op": "Equal",
          "value": "true"
        }
      ]
    }
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventory PciDeviceInventory See inventory 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 0.6
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
UpdatePciDeviceAction action = new UpdatePciDeviceAction();
action.uuid = "4bec7e7c2c1e337599e0455165906fd5";
action.state = "Disabled";
action.name = "test pci";
action.description = "test pci";
action.metaData = "key1:value1;key2:value2";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdatePciDeviceAction.Result res = action.call();
Python SDK
UpdatePciDeviceAction action = UpdatePciDeviceAction()
action.uuid = "4bec7e7c2c1e337599e0455165906fd5"
action.state = "Disabled"
action.name = "test pci"
action.description = "test pci"
action.metaData = "key1:value1;key2:value2"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdatePciDeviceAction.Result res = action.call()

GetPciDeviceCandidatesForAttachingVm

Get the list of PCI devices that can be attached to a Virtual Machine.

API Request

URLs
GET zstack/v1/vm-instances/{vmInstanceUuid}/candidate-pci-devices
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/517c674367793e7db4f52bfc21839de7/candidate-pci-devices
Parameter List
Name Type Location Description Allowed Values Starting Version
vmInstanceUuid String url Virtual Machine UUID 2.1
systemTags (Optional) List query Optional. The system tags. 2.1
userTags (Optional) List query Optional. The user tags. 2.1
types (Optional) List query Optional. The types. 2.1

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "200cc14b3ed5333da32607a09e8a75cb",
      "hostUuid": "0014ffc881a33fafb9723c9bcd4de3cd",
      "type": "GPU_Video_Controller",
      "status": "Attached",
      "vendorId": "10de",
      "deviceId": "0e0f",
      "subvendorId": "10de",
      "subdeviceId": "118b",
      "pciDeviceAddress": "0000:06:00.1"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventories List See inventories 0.6
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 0.6
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
GetPciDeviceCandidatesForAttachingVmAction action = new GetPciDeviceCandidatesForAttachingVmAction();
action.vmInstanceUuid = "4f19efcf201138bbb34c901505a64e18";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetPciDeviceCandidatesForAttachingVmAction.Result res = action.call();
Python SDK
GetPciDeviceCandidatesForAttachingVmAction action = GetPciDeviceCandidatesForAttachingVmAction()
action.vmInstanceUuid = "b038e94c3b4939efa32edb560e7c9ddd"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetPciDeviceCandidatesForAttachingVmAction.Result res = action.call()

GetPciDeviceCandidatesForNewCreateVm

Get loadable PCI devices for a newly created Virtual Machine.

API Request

URLs
GET zstack/v1/pci-device/candidate-pci-devices-for-new-create-vm
Headers

Authorization: OAuth the-session-uuid
Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/candidate-pci-devices-for-new-create-vm?hostUuid=3376aee6af913e278a1a6aafc28c2e94
Parameter List
Name Type Location Description Allowed Values Starting Version
hostUuid (Optional) String query Host UUID 2.4
clusterUuids (Optional) List query Optional. The cluster UUIDs. 2.4
types (Optional) List query Optional. The types. 2.4
systemTags (Optional) List query Optional. The system tags. 2.4
userTags (Optional) List query Optional. The user tags. 2.4

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "1d2d54391e4d303cbf12543508b208ba",
      "hostUuid": "d98a93185af134fda630723444fd49d4",
      "type": "GPU_Video_Controller",
      "status": "Attached",
      "vendorId": "10de",
      "deviceId": "0e0f",
      "subvendorId": "10de",
      "subdeviceId": "118b",
      "pciDeviceAddress": "0000:06:00.1"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 0.6
inventories List See inventories 0.6
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 0.6
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
GetPciDeviceCandidatesForNewCreateVmAction action = new GetPciDeviceCandidatesForNewCreateVmAction();
action.hostUuid = "3376aee6af913e278a1a6aafc28c2e94";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetPciDeviceCandidatesForNewCreateVmAction.Result res = action.call();
Python SDK
GetPciDeviceCandidatesForNewCreateVmAction action = GetPciDeviceCandidatesForNewCreateVmAction()
action.hostUuid = "3376aee6af913e278a1a6aafc28c2e94"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetPciDeviceCandidatesForNewCreateVmAction.Result res = action.call()

AttachPciDeviceToVm

Attach a PCI device to a Virtual Machine. Administrators can directly attach PCI devices in System or Active state to Virtual Machines in Active or Stopped state.

API Request

URLs
POST zstack/v1/pci-device/pci-devices/{pciDeviceUuid}/attach
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "vmInstanceUuid": "d3f41f8b996b390992cc4607e7bb10dc"
  },
  "systemTags": [],
  "userTags": []
}
Note:

In the example above, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"vmInstanceUuid":"d3f41f8b996b390992cc4607e7bb10dc"}}' \
http://localhost:8080/zstack/v1/pci-device/pci-devices/201b541edbed3dccbebfaa57b3beb9bb/attach
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url PCI device UUID 2.1
vmInstanceUuid String body (contained in the params structure) Virtual Machine UUID 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

Response Example
{
  "inventory": {
    "uuid": "f89ad78682d73e08a2ed52bd4837aadf",
    "hostUuid": "f2d1b937a92a3ac6a446feb1030f6315",
    "vmInstanceUuid": "3daa5e997d023c508a4af3ddda65ddac",
    "type": "GPU_Video_Controller",
    "status": "Attached",
    "vendorId": "10de",
    "deviceId": "0e0f",
    "subvendorId": "10de",
    "subdeviceId": "118b",
    "pciDeviceAddress": "0000:06:00.1"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventory PciDeviceInventory See inventory 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
AttachPciDeviceToVmAction action = new AttachPciDeviceToVmAction();
action.pciDeviceUuid = "201b541edbed3dccbebfaa57b3beb9bb";
action.vmInstanceUuid = "d3f41f8b996b390992cc4607e7bb10dc";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AttachPciDeviceToVmAction.Result res = action.call();
Python SDK
AttachPciDeviceToVmAction action = AttachPciDeviceToVmAction()
action.pciDeviceUuid = "201b541edbed3dccbebfaa57b3beb9bb"
action.vmInstanceUuid = "d3f41f8b996b390992cc4607e7bb10dc"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AttachPciDeviceToVmAction.Result res = action.call()

DetachPciDeviceFromVm

Detach a PCI device from a Virtual Machine.

API Request

URLs
POST zstack/v1/pci-device/pci-devices/{pciDeviceUuid}/detach
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "vmInstanceUuid": "42d2fcfc217f38faa02035132e7b4b16"
  },
  "systemTags": [],
  "userTags": []
}
Note:

In the example above, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"vmInstanceUuid":"42d2fcfc217f38faa02035132e7b4b16"}}' \
http://localhost:8080/zstack/v1/pci-device/pci-devices/f44964a4252a3de3a435d2ab04bb9fb8/detach
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url The PCI device UUID. 2.1
vmInstanceUuid String body (contained in the params structure) Virtual Machine UUID 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

Response Example
{
  "inventory": {
    "uuid": "b4e48cb6b04f328fb92dfb6cb9e804a3",
    "hostUuid": "93b41d6ac72f360f88fb33ff62dfcfa1",
    "type": "GPU_Video_Controller",
    "status": "Active",
    "vendorId": "10de",
    "deviceId": "0e0f",
    "subvendorId": "10de",
    "subdeviceId": "118b",
    "pciDeviceAddress": "0000:06:00.1"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventory PciDeviceInventory See inventory 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 0.6
description String Brief description of the error 0.6
details String Detailed error information 0.6
elaboration String Reserved field, defaults to null 0.6
opaque LinkedHashMap Reserved field, defaults to null 0.6
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 0.6
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 3.5.0
description String Resource description 2.1
hostUuid String Host UUID 2.1
parentUuid String Physical PCI device UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 2.1
pciSpecUuid String PCI device offering UUID 3.5.0
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
pciDeviceAddress String PCI device address 2.1
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceType See type 2.1
state PciDeviceState See state 2.1
status PciDeviceStatus See status 2.1
virtStatus PciDeviceVirtStatus See virtStatus 3.5.0
chooser PciDeviceChooser See chooser 4.1.0
metaData PciDeviceMetaData See metaData 2.1
matchedPciDeviceOfferingRef List See matchedPciDeviceOfferingRef 2.1
mdevSpecRefs List See mdevSpecRefs 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceState Enabled 2.1
Disabled PciDeviceState Disabled 2.1
#status
Name Type Description Starting Version
Active PciDeviceStatus Ready 2.1
Attached PciDeviceStatus Attached 2.1
System PciDeviceStatus System 2.1
#virtStatus
Name Type Description Starting Version
UNVIRTUALIZABLE PciDeviceVirtStatus Unvirtualizable 3.5.0
SRIOV_VIRTUALIZABLE PciDeviceVirtStatus SRIOV virtualizable 3.5.0
VFIO_MDEV_VIRTUALIZABLE PciDeviceVirtStatus VFIO_MDEV virtualizable 3.5.0
SRIOV_VIRTUALIZED PciDeviceVirtStatus SRIOV virtualized 3.5.0
VFIO_MDEV_VIRTUALIZED PciDeviceVirtStatus VFIO_MDEV virtualized 3.5.0
SRIOV_VIRTUAL PciDeviceVirtStatus SRIOV virtual device 3.5.0
UNKNOWN PciDeviceVirtStatus Unknown 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.8.0
Device PciDeviceChooser The Device value. 4.8.0
Spec PciDeviceChooser The Spec value. 4.8.0
#metaData
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDeviceOfferingRef
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
#mdevSpecRefs
Name Type Description Starting Version
pciDeviceUuid String PCI device UUID 3.5.0
mdevSpecUuid String MDEV device offering UUID 3.5.0
effective Boolean Whether the current MDEV specification is used to partition this PCI device 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
DetachPciDeviceFromVmAction action = new DetachPciDeviceFromVmAction();
action.pciDeviceUuid = "f44964a4252a3de3a435d2ab04bb9fb8";
action.vmInstanceUuid = "42d2fcfc217f38faa02035132e7b4b16";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DetachPciDeviceFromVmAction.Result res = action.call();
Python SDK
DetachPciDeviceFromVmAction action = DetachPciDeviceFromVmAction()
action.pciDeviceUuid = "f44964a4252a3de3a435d2ab04bb9fb8"
action.vmInstanceUuid = "42d2fcfc217f38faa02035132e7b4b16"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DetachPciDeviceFromVmAction.Result res = action.call()

CreatePciDeviceOffering

API Request

URLs
POST zstack/v1/pci-device/pci-device-offerings
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "test",
    "vendorId": "10de",
    "deviceId": "0e0f"
  },
  "systemTags": [],
  "userTags": []
}
Note:

In the example above, the systemTags and userTags fields can be omitted. They are listed to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"test","vendorId":"10de","deviceId":"0e0f"}}' \
http://localhost:8080/zstack/v1/pci-device/pci-device-offerings
Parameter List
Name Type Location Description Allowed Values Starting Version
name (Optional) String body (contained in the params structure) Resource name 2.1
description (Optional) String body (contained in the params structure) Resource description 2.1
vendorId String body (contained in the params structure) Vendor ID 2.1
deviceId String body (contained in the params structure) Device ID 2.1
subvendorId (Optional) String body (contained in the params structure) Sub-vendor ID 2.1
subdeviceId (Optional) String body (contained in the params structure) Sub-device ID 2.1
ramSize (Optional) String body (contained in the params structure) RAM capacity 3.5.0
resourceUuid (Optional) String body (contained in the params structure) Optional. The resource UUID. 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1
tagUuids (Optional) List body (contained in the params structure) Tag UUID list 3.4.0

API Response

Response Example
{
  "inventory": {
    "type": "GPU_Video",
    "vendorId": "10de",
    "deviceId": "0e0f",
    "subvendorId": "10de",
    "subdeviceId": "118b"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventory PciDeviceOfferingInventory See inventory 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 2.1
description String Resource description 2.1
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
ramSize String GPU memory capacity 3.5.0
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceOfferingType See type 2.1
attachedInstanceOfferings List See attachedInstanceOfferings 2.1
matchedPciDevices List See matchedPciDevices 2.1
#type
Name Type Description Starting Version
GPU_Video PciDeviceOfferingType GPU video 2.1
GPU_Audio PciDeviceOfferingType GPU audio 2.1
Generic PciDeviceOfferingType Generic device 2.1
#attachedInstanceOfferings
Name Type Description Starting Version
id long The resource ID. 2.1
instanceOfferingUuid String Compute offering UUID 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
pciDeviceCount Integer The number of PCI device. 2.1
metadata PciDeviceMetaData See metadata 2.1
#metadata
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String Key 2.1
value String Value 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDevices
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1

SDK Examples

Java SDK
CreatePciDeviceOfferingAction action = new CreatePciDeviceOfferingAction();
action.name = "test";
action.vendorId = "10de";
action.deviceId = "0e0f";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreatePciDeviceOfferingAction.Result res = action.call();
Python SDK
CreatePciDeviceOfferingAction action = CreatePciDeviceOfferingAction()
action.name = "test"
action.vendorId = "10de"
action.deviceId = "0e0f"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
CreatePciDeviceOfferingAction.Result res = action.call()

DeletePciDeviceOffering

API Request

URLs
DELETE zstack/v1/pci-device/pci-device-offerings/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/pci-device/pci-device-offerings/900f2eefdec630c68313eb025123375d
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource. Uniquely identifies the resource. 2.1
deleteMode (Optional) String url Optional. The delete mode. 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

On success, this API returns an empty JSON structure {}. On failure, the returned JSON structure contains an error field, for example:
{
    "error": {
        "code": "SYS.1001",
        "description": "A message or a operation timeout",
        "details": "Create VM on KVM timeout after 300s"
    }
}

SDK Examples

Java SDK
DeletePciDeviceOfferingAction action = new DeletePciDeviceOfferingAction();
action.uuid = "900f2eefdec630c68313eb025123375d";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeletePciDeviceOfferingAction.Result res = action.call();
Python SDK
DeletePciDeviceOfferingAction action = DeletePciDeviceOfferingAction()
action.uuid = "900f2eefdec630c68313eb025123375d"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DeletePciDeviceOfferingAction.Result res = action.call()

QueryPciDeviceSpec

API Request

URLs
GET zstack/v1/pci-device-specs
GET zstack/v1/pci-device-specs/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device-specs?q=uuid=148eb0059a193de59e5278395c36baa7
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device-specs/f5caf15dfb98366cbf87d41aa01385b9

Queryable Fields

Run the CLI command tool, enter QueryPciDeviceSpec and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "6a2537202e134f9fa240f0455fc507cc",
      "name": "MSI_GTX1060",
      "description": "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller",
      "vendorId": "10de",
      "deviceId": "1c03",
      "subvendorId": "1462",
      "subdeviceId": "3283",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "romVersion": "86.06.0E.00.28",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
vendorId String Vendor ID 3.5.0
deviceId String Device ID 3.5.0
subvendorId String Sub-vendor ID 3.5.0
subdeviceId String Sub-device ID 3.5.0
ramSize String GPU memory capacity 3.5.0
maxPartNum Integer Maximum partition number 3.5.0
isVirtual Boolean Whether it is a virtual device 3.5.0
romVersion String Firmware version 3.5.0
romMd5sum String Firmware MD5 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type PciDeviceType See type 3.5.0
state PciDeviceSpecState See state 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceSpecState Enabled 3.5.0
Disabled PciDeviceSpecState Disabled 3.5.0

SDK Examples

Java SDK
QueryPciDeviceSpecAction action = new QueryPciDeviceSpecAction();
action.conditions = asList("uuid=96a05dc8dbee32ddb15c63680df63792");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryPciDeviceSpecAction.Result res = action.call();
Python SDK
QueryPciDeviceSpecAction action = QueryPciDeviceSpecAction()
action.conditions = ["uuid=362f676642ba3288bf02c98fcee26d74"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryPciDeviceSpecAction.Result res = action.call()

QueryPciDeviceOffering

API Request

URLs
GET zstack/v1/pci-device/pci-device-offerings
GET zstack/v1/pci-device/pci-device-offerings/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/pci-device-offerings
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/pci-device-offerings/f0d1dc75b5323546aa5c6bda3733019c

Queryable Fields

Run the CLI command tool, enter QueryPciDeviceOffering and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {}
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventories List See inventories 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 2.1
name String Resource name 2.1
description String Resource description 2.1
vendorId String Vendor ID 2.1
deviceId String Device ID 2.1
subvendorId String Sub-vendor ID 2.1
subdeviceId String Sub-device ID 2.1
ramSize String GPU memory capacity 3.5.0
createDate Timestamp Create date 2.1
lastOpDate Timestamp Last update date 2.1
type PciDeviceOfferingType See type 2.1
attachedInstanceOfferings List See attachedInstanceOfferings 2.1
matchedPciDevices List See matchedPciDevices 2.1
#type
Name Type Description Starting Version
GPU_Video PciDeviceOfferingType GPU video 2.1
GPU_Audio PciDeviceOfferingType GPU audio 2.1
Generic PciDeviceOfferingType Generic device 2.1
#attachedInstanceOfferings
Name Type Description Starting Version
id long The resource ID. 2.1
instanceOfferingUuid String Compute offering UUID 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1
pciDeviceCount Integer The number of PCI device. 2.1
metadata PciDeviceMetaData See metadata 2.1
#metadata
Name Type Description Starting Version
metaData String The metadata. 2.1
metaDataEntries List See metaDataEntries 2.1
#metaDataEntries
Name Type Description Starting Version
key String The key. 2.1
value String The field value. 2.1
op PciDeviceMetaDataOperator See op 2.1
#op
Name Type Description Starting Version
Equal PciDeviceMetaDataOperator Equal 2.1
Unequal PciDeviceMetaDataOperator Unequal 2.1
#matchedPciDevices
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1

SDK Examples

Java SDK
QueryPciDeviceOfferingAction action = new QueryPciDeviceOfferingAction();
action.conditions = asList();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryPciDeviceOfferingAction.Result res = action.call();
Python SDK
QueryPciDeviceOfferingAction action = QueryPciDeviceOfferingAction()
action.conditions = []
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryPciDeviceOfferingAction.Result res = action.call()

QueryPciDevicePciDeviceOffering

API Request

URLs
GET zstack/v1/pci-devices/pci-devices/pci-device-offerings
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-devices/pci-devices/pci-device-offerings

Queryable Fields

Run the CLI command tool, enter QueryPciDevicePciDeviceOffering and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {
      "id": 0
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
inventories List See inventories 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#inventories
Name Type Description Starting Version
pciDeviceUuid String The PCI device UUID. 2.1
pciDeviceOfferingUuid String The PCI device offering UUID. 2.1

SDK Examples

Java SDK
QueryPciDevicePciDeviceOfferingAction action = new QueryPciDevicePciDeviceOfferingAction();
action.conditions = asList();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryPciDevicePciDeviceOfferingAction.Result res = action.call();
Python SDK
QueryPciDevicePciDeviceOfferingAction action = QueryPciDevicePciDeviceOfferingAction()
action.conditions = []
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryPciDevicePciDeviceOfferingAction.Result res = action.call()

UpdatePciDeviceSpec

API Request

URLs
PUT zstack/v1/pci-device-specs/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updatePciDeviceSpec": {
    "name": "MSI_GTX1060",
    "description": "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller",
    "romContent": "*BASE64 ENCODED ROM CONTENT*",
    "romVersion": "86.06.0E.00.29",
    "abandonSpecRom": false,
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updatePciDeviceSpec":{"name":"MSI_GTX1060","description":"NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller","romContent":"*BASE64 ENCODED ROM CONTENT*","romVersion":"86.06.0E.00.29","abandonSpecRom":false,"state":"Enabled"}}' http://localhost:8080/zstack/v1/pci-device-specs/78ba2350be1e451597c2d42f778d0241/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 3.5.0
name (Optional) String body(inside the updatePciDeviceSpec structure) Resource name 3.5.0
description (Optional) String body(inside the updatePciDeviceSpec structure) Resource description 3.5.0
romContent (Optional) String body(inside the updatePciDeviceSpec structure) BASE64 encoded firmware content 3.5.0
romVersion (Optional) String body(inside the updatePciDeviceSpec structure) Firmware version 3.5.0
abandonSpecRom (Optional) boolean body(inside the updatePciDeviceSpec structure) Delete existing firmware 3.5.0
state (Optional) String body(inside the updatePciDeviceSpec structure) PCI device spec state
  • Enabled
  • Disabled
 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "uuid": "304bc9b4af93442fb666bef79e84243a",
    "name": "MSI_GTX1060",
    "description": "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller",
    "vendorId": "10de",
    "deviceId": "1c03",
    "subvendorId": "1462",
    "subdeviceId": "3283",
    "type": "GPU_Video_Controller",
    "state": "Enabled",
    "romVersion": "86.06.0E.00.28",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory PciDeviceSpecInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
vendorId String Vendor ID 3.5.0
deviceId String Device ID 3.5.0
subvendorId String Sub-vendor ID 3.5.0
subdeviceId String Sub-device ID 3.5.0
ramSize String GPU memory capacity 3.5.0
maxPartNum Integer Maximum partition number 3.5.0
isVirtual Boolean Whether it is a virtual device 3.5.0
romVersion String Firmware version 3.5.0
romMd5sum String Firmware MD5 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type PciDeviceType See type 3.5.0
state PciDeviceSpecState See state 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceSpecState Enabled 3.5.0
Disabled PciDeviceSpecState Disabled 3.5.0

SDK Examples

Java SDK
UpdatePciDeviceSpecAction action = new UpdatePciDeviceSpecAction();
action.uuid = "2e9160ddd31245dca87eee7d7d2a2ac8";
action.name = "MSI_GTX1060";
action.description = "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller";
action.romContent = "*BASE64 ENCODED ROM CONTENT*";
action.romVersion = "86.06.0E.00.29";
action.abandonSpecRom = false;
action.state = "Enabled";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdatePciDeviceSpecAction.Result res = action.call();
Python SDK
UpdatePciDeviceSpecAction action = UpdatePciDeviceSpecAction()
action.uuid = "2589cc1b20294e0b85d75f652f7dcf77"
action.name = "MSI_GTX1060"
action.description = "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller"
action.romContent = "*BASE64 ENCODED ROM CONTENT*"
action.romVersion = "86.06.0E.00.29"
action.abandonSpecRom = false
action.state = "Enabled"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdatePciDeviceSpecAction.Result res = action.call()

AddPciDeviceSpecToVmInstance

API Request

URLs
POST zstack/v1/pci-device-specs/{pciSpecUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "pciDeviceNumber": 1
  },
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"pciDeviceNumber":1}}' \
http://localhost:8080/zstack/v1/pci-device-specs/ace129cb77d93012bf47f839b9429881/vm-instances/16ecb900082437e8aaf554ce19620030
Parameter List
Name Type Location Description Allowed Values Starting Version
pciSpecUuid String url PCI device spec UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
pciDeviceNumber (Optional) Integer body(inside the params structure) Optional. The number of PCI device. 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "vmInstanceUuid": "ac37ee1208aa4a9582a9b4efc95b5456",
    "pciSpecUuid": "5cfc996fdab140d086e2fa51cb2882e6",
    "pciDeviceNumber": 1,
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory VmInstancePciDeviceSpecRefInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
vmInstanceUuid String Virtual Machine UUID 3.5.0
pciSpecUuid String PCI device spec UUID 3.5.0
pciDeviceNumber Integer Number of PCI devices matching the device spec to attach to the VM, defaults to 1 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
AddPciDeviceSpecToVmInstanceAction action = new AddPciDeviceSpecToVmInstanceAction();
action.pciSpecUuid = "ace129cb77d93012bf47f839b9429881";
action.vmInstanceUuid = "16ecb900082437e8aaf554ce19620030";
action.pciDeviceNumber = 1;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AddPciDeviceSpecToVmInstanceAction.Result res = action.call();
Python SDK
AddPciDeviceSpecToVmInstanceAction action = AddPciDeviceSpecToVmInstanceAction()
action.pciSpecUuid = "ace129cb77d93012bf47f839b9429881"
action.vmInstanceUuid = "16ecb900082437e8aaf554ce19620030"
action.pciDeviceNumber = 1
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AddPciDeviceSpecToVmInstanceAction.Result res = action.call()

RemovePciDeviceSpecFromVmInstance

API Request

URLs
DELETE zstack/v1/pci-device-specs/{pciSpecUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/pci-device-specs/1c8f91c1699c35bfbb1847d2c20f7371/vm-instances/422fe51c278930f085e1323b0e858e3f
Parameter List
Name Type Location Description Allowed Values Starting Version
pciSpecUuid String url PCI device spec UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
RemovePciDeviceSpecFromVmInstanceAction action = new RemovePciDeviceSpecFromVmInstanceAction();
action.pciSpecUuid = "1c8f91c1699c35bfbb1847d2c20f7371";
action.vmInstanceUuid = "422fe51c278930f085e1323b0e858e3f";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
RemovePciDeviceSpecFromVmInstanceAction.Result res = action.call();
Python SDK
RemovePciDeviceSpecFromVmInstanceAction action = RemovePciDeviceSpecFromVmInstanceAction()
action.pciSpecUuid = "1c8f91c1699c35bfbb1847d2c20f7371"
action.vmInstanceUuid = "422fe51c278930f085e1323b0e858e3f"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
RemovePciDeviceSpecFromVmInstanceAction.Result res = action.call()

GetPciDeviceSpecCandidates

API Request

URLs
GET zstack/v1/pci-device-specs/candidates
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device-specs/candidates?clusterUuids=d3305a8348d937ba97d260fb0af0e87d&clusterUuids=4943e8ab691435f98f7d22e3196f36a0&hostUuid=8bcb6475294a3283b5105f36c52c4aa9&vmInstanceUuid=c4bd1f978e843300b8de214567841c3a&types=GPU_Video_Controller&types=GPU_Audio_Controller
Parameter List
Name Type Location Description Allowed Values Starting Version
clusterUuids (Optional) List query Cluster UUID 3.5.0
hostUuid (Optional) String query Host UUID 3.5.0
vmInstanceUuid (Optional) String query Virtual Machine UUID 3.5.0
vmInstanceUuids (Optional) List query Virtual Machine UUID list 3.6.1
types (Optional) List query Device type 3.5.0
systemTags (Optional) List query System tags 3.5.0
userTags (Optional) List query User tags 3.5.0

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "7ba9feb4d0f445ad9dbff82e0e408fc7",
      "name": "MSI_GTX1060",
      "description": "NVIDIA Corporation, GP106 [GeForce GTX 1060 6GB], a1, VGA compatible controller",
      "vendorId": "10de",
      "deviceId": "1c03",
      "subvendorId": "1462",
      "subdeviceId": "3283",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "romVersion": "86.06.0E.00.28",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
vendorId String Vendor ID 3.5.0
deviceId String Device ID 3.5.0
subvendorId String Sub-vendor ID 3.5.0
subdeviceId String Sub-device ID 3.5.0
ramSize String GPU memory capacity 3.5.0
maxPartNum Integer Maximum partition number 3.5.0
isVirtual Boolean Whether it is a virtual device 3.5.0
romVersion String Firmware version 3.5.0
romMd5sum String Firmware MD5 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type PciDeviceType See type 3.5.0
state PciDeviceSpecState See state 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller PciDeviceType GPU video controller 2.1
GPU_Audio_Controller PciDeviceType GPU audio controller 2.1
GPU_3D_Controller PciDeviceType GPU 3D controller 2.1
Moxa_Device PciDeviceType MOXA card 2.1
Generic PciDeviceType Generic device 2.1
#state
Name Type Description Starting Version
Enabled PciDeviceSpecState Enabled 3.5.0
Disabled PciDeviceSpecState Disabled 3.5.0

SDK Examples

Java SDK
GetPciDeviceSpecCandidatesAction action = new GetPciDeviceSpecCandidatesAction();
action.clusterUuids = asList("d3305a8348d937ba97d260fb0af0e87d","4943e8ab691435f98f7d22e3196f36a0");
action.hostUuid = "8bcb6475294a3283b5105f36c52c4aa9";
action.vmInstanceUuid = "c4bd1f978e843300b8de214567841c3a";
action.types = asList("GPU_Video_Controller","GPU_Audio_Controller");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetPciDeviceSpecCandidatesAction.Result res = action.call();
Python SDK
GetPciDeviceSpecCandidatesAction action = GetPciDeviceSpecCandidatesAction()
action.clusterUuids = [d3305a8348d937ba97d260fb0af0e87d, 4943e8ab691435f98f7d22e3196f36a0]
action.hostUuid = "8bcb6475294a3283b5105f36c52c4aa9"
action.vmInstanceUuid = "c4bd1f978e843300b8de214567841c3a"
action.types = [GPU_Video_Controller, GPU_Audio_Controller]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetPciDeviceSpecCandidatesAction.Result res = action.call()

QueryVmInstancePciDeviceSpecRef

API Request

URLs
GET zstack/v1/vm-instances/{vmInstanceUuid}/pci-device-specs
GET zstack/v1/vm-instances/{vmInstanceUuid}/pci-device-specs/{pciSpecUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/{vmInstanceUuid}/pci-device-specs?q=vmInstanceUuid=e58abf7fd2d0332bb18ba348195be863
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/{vmInstanceUuid}/pci-device-specs/{pciSpecUuid}?q=vmInstanceUuid=34ff56e0fd1e3cd789a30d66fd4bf3aa

Queryable Fields

Run the CLI command tool, enter QueryVmInstancePciDeviceSpecRef and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {
      "vmInstanceUuid": "bf5c475cc0954616adacebb9b2b2a9e2",
      "pciSpecUuid": "260464ce341043588f0cc30dde70ed42",
      "pciDeviceNumber": 1,
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
vmInstanceUuid String Virtual Machine UUID 3.5.0
pciSpecUuid String PCI device spec UUID 3.5.0
pciDeviceNumber Integer Number of PCI devices matching the device spec to attach to the VM, defaults to 1 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
QueryVmInstancePciDeviceSpecRefAction action = new QueryVmInstancePciDeviceSpecRefAction();
action.conditions = asList("vmInstanceUuid=67c3ebbb1c683373a52310b218164181");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryVmInstancePciDeviceSpecRefAction.Result res = action.call();
Python SDK
QueryVmInstancePciDeviceSpecRefAction action = QueryVmInstancePciDeviceSpecRefAction()
action.conditions = ["vmInstanceUuid=aef75bdacefd33349d9f15eb0f96fe89"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryVmInstancePciDeviceSpecRefAction.Result res = action.call()

GetHostIommuState

API Request

URLs
GET zstack/v1/pci-device/hosts/{uuid}/state
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/hosts/dbd7601b48053ec9a753047fce55082a/state
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String query UUID of the resource, uniquely identifies the resource 2.1
systemTags (Optional) List query Optional. The system tags. 2.1
userTags (Optional) List query Optional. The user tags. 2.1

API Response

Response Example
{
  "state": "Enabled"
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 2.1
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
state HostIommuStateType See state 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#state
Name Type Description Starting Version
name String Resource name 2.1
ordinal int The ordinal number. 2.1

SDK Examples

Java SDK
GetHostIommuStateAction action = new GetHostIommuStateAction();
action.uuid = "dbd7601b48053ec9a753047fce55082a";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetHostIommuStateAction.Result res = action.call();
Python SDK
GetHostIommuStateAction action = GetHostIommuStateAction()
action.uuid = "dbd7601b48053ec9a753047fce55082a"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetHostIommuStateAction.Result res = action.call()

GetHostIommuStatus

API Request

URLs
GET zstack/v1/pci-device/hosts/{uuid}/status
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/pci-device/hosts/0ec53c2f753331f1a2c62b378821e9b7/status
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.1
systemTags (Optional) List query Optional. The system tags. 2.1
userTags (Optional) List query Optional. The user tags. 2.1

API Response

Response Example
{
  "status": "Active"
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 2.1
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
status HostIommuStatusType See status 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#status
Name Type Description Starting Version
type String Host IOMMU ready status, can be Active or Inactive 2.1

SDK Examples

Java SDK
GetHostIommuStatusAction action = new GetHostIommuStatusAction();
action.uuid = "0ec53c2f753331f1a2c62b378821e9b7";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetHostIommuStatusAction.Result res = action.call();
Python SDK
GetHostIommuStatusAction action = GetHostIommuStatusAction()
action.uuid = "0ec53c2f753331f1a2c62b378821e9b7"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetHostIommuStatusAction.Result res = action.call()

UpdateHostIommuState

API Request

URLs
PUT zstack/v1/pci-device/hosts/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateHostIommuState": {
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note:

systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.

Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateHostIommuState":{"state":"Enabled"}}' \
http://localhost:8080/zstack/v1/pci-device/hosts/7619742c9ff43b898487db33e1f096a4/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 2.1
state String body(inside the updateHostIommuState structure) The resource state.
  • Enabled
  • Disabled
 2.1
systemTags (Optional) List body Optional. The system tags. 2.1
userTags (Optional) List body Optional. The user tags. 2.1

API Response

Response Example
{
  "state": "Enabled"
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 2.1
state HostIommuStateType See state 2.1
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 2.1
description String Brief description of the error 2.1
details String Detailed error information 2.1
elaboration String Reserved field, defaults to null 2.1
opaque LinkedHashMap Reserved field, defaults to null 2.1
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 2.1
#state
Name Type Description Starting Version
name String Resource name 0.6
ordinal int The ordinal number. 0.6

SDK Examples

Java SDK
UpdateHostIommuStateAction action = new UpdateHostIommuStateAction();
action.uuid = "7619742c9ff43b898487db33e1f096a4";
action.state = "Enabled";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateHostIommuStateAction.Result res = action.call();
Python SDK
UpdateHostIommuStateAction action = UpdateHostIommuStateAction()
action.uuid = "7619742c9ff43b898487db33e1f096a4"
action.state = "Enabled"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateHostIommuStateAction.Result res = action.call()

GenerateSriovPciDevices

API Request

URLs
PUT zstack/v1/pci-devices/{pciDeviceUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "generateSriovPciDevices": {
    "virtPartNum": 4
  },
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"generateSriovPciDevices":{"virtPartNum":4}}' http://localhost:8080/zstack/v1/pci-devices/ce07829a08273d129f3b9d11cdf830b9/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url PCI UUID 3.5.0
virtPartNum Integer body(inside the generateSriovPciDevices structure) Partition number 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
GenerateSriovPciDevicesAction action = new GenerateSriovPciDevicesAction();
action.pciDeviceUuid = "ce07829a08273d129f3b9d11cdf830b9";
action.virtPartNum = 4;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GenerateSriovPciDevicesAction.Result res = action.call();
Python SDK
GenerateSriovPciDevicesAction action = GenerateSriovPciDevicesAction()
action.pciDeviceUuid = "ce07829a08273d129f3b9d11cdf830b9"
action.virtPartNum = 4
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GenerateSriovPciDevicesAction.Result res = action.call()

UngenerateSriovPciDevices

API Request

URLs
PUT zstack/v1/pci-devices/{pciDeviceUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "ungenerateSriovPciDevices": {},
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"ungenerateSriovPciDevices":{}}' http://localhost:8080/zstack/v1/pci-devices/31f8b8c366c63901ac928106568eca85/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url PCI UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
UngenerateSriovPciDevicesAction action = new UngenerateSriovPciDevicesAction();
action.pciDeviceUuid = "31f8b8c366c63901ac928106568eca85";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UngenerateSriovPciDevicesAction.Result res = action.call();
Python SDK
UngenerateSriovPciDevicesAction action = UngenerateSriovPciDevicesAction()
action.pciDeviceUuid = "31f8b8c366c63901ac928106568eca85"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UngenerateSriovPciDevicesAction.Result res = action.call()

GenerateMdevDevices

API Request

URLs
PUT zstack/v1/pci-devices/{pciDeviceUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "generateMdevDevices": {
    "mdevSpecUuid": "013f5f259daa3e119ec79496ed2f5697"
  },
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"generateMdevDevices":{"mdevSpecUuid":"013f5f259daa3e119ec79496ed2f5697"}}' http://localhost:8080/zstack/v1/pci-devices/b5b60d1bc9353c948c635a500a044c97/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url PCI device UUID 3.5.0
mdevSpecUuid String body(inside the generateMdevDevices structure) MDEV device spec UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
GenerateMdevDevicesAction action = new GenerateMdevDevicesAction();
action.pciDeviceUuid = "b5b60d1bc9353c948c635a500a044c97";
action.mdevSpecUuid = "013f5f259daa3e119ec79496ed2f5697";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GenerateMdevDevicesAction.Result res = action.call();
Python SDK
GenerateMdevDevicesAction action = GenerateMdevDevicesAction()
action.pciDeviceUuid = "b5b60d1bc9353c948c635a500a044c97"
action.mdevSpecUuid = "013f5f259daa3e119ec79496ed2f5697"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GenerateMdevDevicesAction.Result res = action.call()

UngenerateMdevDevices

API Request

URLs
PUT zstack/v1/pci-devices/{pciDeviceUuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "ungenerateMdevDevices": {},
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"ungenerateMdevDevices":{}}' http://localhost:8080/zstack/v1/pci-devices/772a0f2d8aaa3626964e080122a48c25/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
pciDeviceUuid String url Sliced PCI device UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

This API returns an empty JSON structure {} on success. On error, the returned JSON contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
UngenerateMdevDevicesAction action = new UngenerateMdevDevicesAction();
action.pciDeviceUuid = "772a0f2d8aaa3626964e080122a48c25";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UngenerateMdevDevicesAction.Result res = action.call();
Python SDK
UngenerateMdevDevicesAction action = UngenerateMdevDevicesAction()
action.pciDeviceUuid = "772a0f2d8aaa3626964e080122a48c25"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UngenerateMdevDevicesAction.Result res = action.call()

QueryMdevDevice

API Request

URLs
GET zstack/v1/mdev-devices
GET zstack/v1/mdev-devices/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-devices
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-devices/9fa9e261caad306f89ccde6f0dca7a1d

Queryable Fields

Run the CLI command tool, enter QueryMdevDevice and press Tab to view all queryable fields and cross-resource names.

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "597624b580d1458f82671b0ef77cf6a4",
      "name": "GRID M60-2A",
      "parentUuid": "90c171f07b21452b87b6d5ee58f4d687",
      "hostUuid": "b440c9393fc644cc8394d789ea1e18e1",
      "mdevSpecUuid": "91b07312092741f18a382942a92f1373",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "status": "Active",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceState Enabled 3.5.0
Disabled MdevDeviceState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0

SDK Examples

Java SDK
QueryMdevDeviceAction action = new QueryMdevDeviceAction();
action.conditions = asList();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryMdevDeviceAction.Result res = action.call();
Python SDK
QueryMdevDeviceAction action = QueryMdevDeviceAction()
action.conditions = []
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryMdevDeviceAction.Result res = action.call()

AttachMdevDeviceToVm

API Request

URLs
POST zstack/v1/mdev-devices/{mdevDeviceUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {},
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{}}' http://localhost:8080/zstack/v1/mdev-devices/2a23f189ed803f869deab2b22ef83b4d/vm-instances/e4108c6e45303e3bbd9743093127b894
Parameter List
Name Type Location Description Allowed Values Starting Version
mdevDeviceUuid String url MDEV device UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "uuid": "0eae7167f0db486aace15529dbc38be9",
    "name": "GRID M60-2A",
    "parentUuid": "9ab8975b943f4b8f82450629386ddf74",
    "hostUuid": "f6db3ae1ef974f539b340851b11bb750",
    "mdevSpecUuid": "c4ee001ad1924cc398f3d17c89a12bfb",
    "type": "GPU_Video_Controller",
    "state": "Enabled",
    "status": "Active",
    "chooser": "None",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory MdevDeviceInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
chooser MdevDeviceChooser See chooser 4.1.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceState Enabled 3.5.0
Disabled MdevDeviceState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.2.0
Device PciDeviceChooser The Device value. 4.2.0
Spec PciDeviceChooser The Spec value. 4.2.0

SDK Examples

Java SDK
AttachMdevDeviceToVmAction action = new AttachMdevDeviceToVmAction();
action.mdevDeviceUuid = "2a23f189ed803f869deab2b22ef83b4d";
action.vmInstanceUuid = "e4108c6e45303e3bbd9743093127b894";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AttachMdevDeviceToVmAction.Result res = action.call();
Python SDK
AttachMdevDeviceToVmAction action = AttachMdevDeviceToVmAction()
action.mdevDeviceUuid = "2a23f189ed803f869deab2b22ef83b4d"
action.vmInstanceUuid = "e4108c6e45303e3bbd9743093127b894"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AttachMdevDeviceToVmAction.Result res = action.call()

DetachMdevDeviceFromVm

API Request

URLs
DELETE zstack/v1/mdev-devices/{mdevDeviceUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/mdev-devices/4c2897ae50b8370489aa2e0caa96d370/vm-instances/16aefa196d5535f6836ec25d301ee3aa
Parameter List
Name Type Location Description Allowed Values Starting Version
mdevDeviceUuid String url MDEV device UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "uuid": "b90d8a5edba0445e9d6380e63088c093",
    "name": "GRID M60-2A",
    "parentUuid": "9fecab9ef7624472be4be166cff7feb7",
    "hostUuid": "102b8a84cae6470c907d6a9de3265b05",
    "mdevSpecUuid": "70130eb2ba7c4ac9bc139808bf4d4ef1",
    "type": "GPU_Video_Controller",
    "state": "Enabled",
    "status": "Active",
    "chooser": "None",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory MdevDeviceInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
chooser MdevDeviceChooser See chooser 4.1.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceState Enabled 3.5.0
Disabled MdevDeviceState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.2.0
Device PciDeviceChooser The Device value. 4.2.0
Spec PciDeviceChooser The Spec value. 4.2.0

SDK Examples

Java SDK
DetachMdevDeviceFromVmAction action = new DetachMdevDeviceFromVmAction();
action.mdevDeviceUuid = "4c2897ae50b8370489aa2e0caa96d370";
action.vmInstanceUuid = "16aefa196d5535f6836ec25d301ee3aa";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DetachMdevDeviceFromVmAction.Result res = action.call();
Python SDK
DetachMdevDeviceFromVmAction action = DetachMdevDeviceFromVmAction()
action.mdevDeviceUuid = "4c2897ae50b8370489aa2e0caa96d370"
action.vmInstanceUuid = "16aefa196d5535f6836ec25d301ee3aa"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
DetachMdevDeviceFromVmAction.Result res = action.call()

UpdateMdevDevice

API Request

URLs
PUT zstack/v1/mdev-devices/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateMdevDevice": {
    "name": "NVIDIA_M60-2A",
    "description": "NVIDIA_M60-2A_2048MB_1920*1080_4Ins_60FPS",
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note: systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateMdevDevice":{"name":"NVIDIA_M60-2A","description":"NVIDIA_M60-2A_2048MB_1920*1080_4Ins_60FPS","state":"Enabled"}}' http://localhost:8080/zstack/v1/mdev-devices/d89cea7c8a03306790d91e68fb0d0e65/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 3.5.0
name (Optional) String body(inside the updateMdevDevice structure) Resource name 3.5.0
description (Optional) String body(inside the updateMdevDevice structure) Resource description 3.5.0
state (Optional) String body(inside the updateMdevDevice structure) Device state
  • Enabled
  • Disabled
 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "uuid": "90bb72d3dba94fbc99310c9804f9dee7",
    "name": "GRID M60-2A",
    "parentUuid": "343e4227833b4774b09d2c0dd24bf8c7",
    "hostUuid": "fa552bef7681478d84806671d28e70f7",
    "mdevSpecUuid": "542b87b26baf403cb2745164ce10e550",
    "type": "GPU_Video_Controller",
    "state": "Enabled",
    "status": "Active",
    "chooser": "None",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory MdevDeviceInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
chooser MdevDeviceChooser See chooser 4.1.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceState Enabled 3.5.0
Disabled MdevDeviceState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.2.0
Device PciDeviceChooser The Device value. 4.2.0
Spec PciDeviceChooser The Spec value. 4.2.0

SDK Examples

Java SDK
UpdateMdevDeviceAction action = new UpdateMdevDeviceAction();
action.uuid = "d89cea7c8a03306790d91e68fb0d0e65";
action.name = "NVIDIA_M60-2A";
action.description = "NVIDIA_M60-2A_2048MB_1920*1080_4Ins_60FPS";
action.state = "Enabled";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateMdevDeviceAction.Result res = action.call();
Python SDK
UpdateMdevDeviceAction action = UpdateMdevDeviceAction()
action.uuid = "d89cea7c8a03306790d91e68fb0d0e65"
action.name = "NVIDIA_M60-2A"
action.description = "NVIDIA_M60-2A_2048MB_1920*1080_4Ins_60FPS"
action.state = "Enabled"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateMdevDeviceAction.Result res = action.call()

GetMdevDeviceSpecCandidates

API Request

URLs
GET zstack/v1/mdev-device-specs/candidates
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-device-specs/candidates?vmInstanceUuid=319897b485313c7a96b0af986b91baea&types=GPU_Video_Controller
Parameter List
Name Type Location Description Allowed Values Starting Version
clusterUuids (Optional) List query Cluster UUID 3.5.0
hostUuid (Optional) String query Host UUID 3.5.0
vmInstanceUuid (Optional) String query Virtual Machine UUID 3.5.0
vmInstanceUuids (Optional) List query Virtual Machine UUID List 3.6.1
types (Optional) List query Device Type 3.5.0
systemTags (Optional) List query System Tags 3.5.0
userTags (Optional) List query User Tags 3.5.0

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "b6051f3e98c143d1bee891ff69f8fad4",
      "name": "GRID_M60-2A",
      "specification": "{Max Resolution\u003d1920*1080, GRID License\u003dGRID-Virtual-Apps,3.0, Instance Number\u003d4, Display Heads\u003d4, Vendor\u003dNVIDIA, Frame Rate Limit\u003d60FPS, Name\u003dGRID_M60-2A, RAM\u003d2048MB}",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
specification String Specification details 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last modified date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceSpecState See state 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceSpecState Enabled 3.5.0
Disabled MdevDeviceSpecState Disabled 3.5.0

SDK Examples

Java SDK
GetMdevDeviceSpecCandidatesAction action = new GetMdevDeviceSpecCandidatesAction();
action.vmInstanceUuid = "319897b485313c7a96b0af986b91baea";
action.types = asList("GPU_Video_Controller");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetMdevDeviceSpecCandidatesAction.Result res = action.call();
Python SDK
GetMdevDeviceSpecCandidatesAction action = GetMdevDeviceSpecCandidatesAction()
action.vmInstanceUuid = "319897b485313c7a96b0af986b91baea"
action.types = [GPU_Video_Controller]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetMdevDeviceSpecCandidatesAction.Result res = action.call()

QueryMdevDeviceSpec

API Request

URLs
GET zstack/v1/mdev-device-specs
GET zstack/v1/mdev-device-specs/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-device-specs?q=uuid=80e1584c51673827abf32ad7c57fa5ed
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-device-specs/21accb3c691435f4a453de1566f19a37

Queryable Fields

Run the CLI command tool, enter QueryMdevDeviceSpec and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "b127c9ba357a459aa1c3b92eb40e8277",
      "name": "GRID M60-2A",
      "parentUuid": "284f35b038ae4b23847238f995281a64",
      "hostUuid": "c461675365b9439ab5794f86c8652fce",
      "mdevSpecUuid": "891086ddf1d0414c94d2a7adbfec15fe",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "status": "Active",
      "chooser": "None",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceSpecState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
chooser MdevDeviceChooser See chooser 4.1.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceSpecState Enabled 3.5.0
Disabled MdevDeviceSpecState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.2.0
Device PciDeviceChooser The Device value. 4.2.0
Spec PciDeviceChooser The Spec value. 4.2.0

SDK Examples

Java SDK
QueryMdevDeviceAction action = new QueryMdevDeviceAction();
action.conditions = asList();
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryMdevDeviceAction.Result res = action.call();
Python SDK
QueryMdevDeviceAction action = QueryMdevDeviceAction()
action.conditions = []
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryMdevDeviceAction.Result res = action.call()

AddMdevDeviceSpecToVmInstance

API Request

URLs
POST zstack/v1/mdev-device-specs/{mdevSpecUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "mdevDeviceNumber": 1
  },
  "systemTags": [],
  "userTags": []
}
Note: The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"mdevDeviceNumber":1.0}}' \
http://localhost:8080/zstack/v1/mdev-device-specs/dbcfe5ae889933a2a740584935e63e72/vm-instances/3d0b1d8b82ba3dd0b95a7903f735bdd1
Parameter List
Name Type Location Description Allowed Values Starting Version
mdevSpecUuid String url MDEV device spec UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
mdevDeviceNumber (Optional) Integer body(contained in params structure) Optional. The number of mdev device. 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "vmInstanceUuid": "0f3a0fd4cd7646afb445e601e885b83e",
    "mdevSpecUuid": "621c2f8c637b4d7ebbfe5a55f60c8a60",
    "mdevDeviceNumber": 1,
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory VmInstanceMdevDeviceSpecRefInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
mdevDeviceNumber Integer Number of mdev devices that meet the spec to attach to the VM, defaults to 1 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
AddMdevDeviceSpecToVmInstanceAction action = new AddMdevDeviceSpecToVmInstanceAction();
action.mdevSpecUuid = "dbcfe5ae889933a2a740584935e63e72";
action.vmInstanceUuid = "3d0b1d8b82ba3dd0b95a7903f735bdd1";
action.mdevDeviceNumber = 1;
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
AddMdevDeviceSpecToVmInstanceAction.Result res = action.call();
Python SDK
AddMdevDeviceSpecToVmInstanceAction action = AddMdevDeviceSpecToVmInstanceAction()
action.mdevSpecUuid = "dbcfe5ae889933a2a740584935e63e72"
action.vmInstanceUuid = "3d0b1d8b82ba3dd0b95a7903f735bdd1"
action.mdevDeviceNumber = 1
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
AddMdevDeviceSpecToVmInstanceAction.Result res = action.call()

RemoveMdevDeviceSpecFromVmInstance

API Request

URLs
DELETE zstack/v1/mdev-device-specs/{mdevSpecUuid}/vm-instances/{vmInstanceUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X DELETE http://localhost:8080/zstack/v1/mdev-device-specs/195f9b240d4a3f8b9946950694745fff/vm-instances/76ce5da88e383ee983955f3a24aea5cf?deleteMode=Permissive
Parameter List
Name Type Location Description Allowed Values Starting Version
mdevSpecUuid String url MDEV device spec UUID 3.5.0
vmInstanceUuid String url Virtual Machine UUID 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

On success, this API returns an empty JSON structure {}. On error, the returned JSON structure contains an error field, for example:
{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK
RemoveMdevDeviceSpecFromVmInstanceAction action = new RemoveMdevDeviceSpecFromVmInstanceAction();
action.mdevSpecUuid = "195f9b240d4a3f8b9946950694745fff";
action.vmInstanceUuid = "76ce5da88e383ee983955f3a24aea5cf";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
RemoveMdevDeviceSpecFromVmInstanceAction.Result res = action.call();
Python SDK
RemoveMdevDeviceSpecFromVmInstanceAction action = RemoveMdevDeviceSpecFromVmInstanceAction()
action.mdevSpecUuid = "195f9b240d4a3f8b9946950694745fff"
action.vmInstanceUuid = "76ce5da88e383ee983955f3a24aea5cf"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
RemoveMdevDeviceSpecFromVmInstanceAction.Result res = action.call()

UpdateMdevDeviceSpec

API Request

URLs
PUT zstack/v1/mdev-device-specs/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateMdevDeviceSpec": {
    "name": "GRID_M60-2A",
    "description": "NVIDIA Corporation, GM204GL [Tesla M60], a1, VGA compatible controller",
    "state": "Enabled"
  },
  "systemTags": [],
  "userTags": []
}
Note: The systemTags and userTags fields can be omitted in the above example. They are listed to indicate that the body can contain these two fields.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateMdevDeviceSpec":{"name":"GRID_M60-2A","description":"NVIDIA Corporation, GM204GL [Tesla M60], a1, VGA compatible controller","state":"Enabled"}}' http://localhost:8080/zstack/v1/mdev-device-specs/fab85387affa4b74b2806ff2c538725e/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url UUID of the resource, uniquely identifies the resource 3.5.0
name (Optional) String body(contained in updateMdevDeviceSpec structure) Resource name 3.5.0
description (Optional) String body(contained in updateMdevDeviceSpec structure) Resource description 3.5.0
state (Optional) String body(contained in updateMdevDeviceSpec structure) Spec state
  • Enabled
  • Disabled
 3.5.0
systemTags (Optional) List body System tags 3.5.0
userTags (Optional) List body User tags 3.5.0

API Response

Response Example
{
  "inventory": {
    "uuid": "61d09af331304b40a80eb67fdd5e86d7",
    "name": "GRID_M60-2A",
    "specification": "{Max Resolution\u003d1920*1080, GRID License\u003dGRID-Virtual-Apps,3.0, Instance Number\u003d4, Display Heads\u003d4, Vendor\u003dNVIDIA, Frame Rate Limit\u003d60FPS, Name\u003dGRID_M60-2A, RAM\u003d2048MB}",
    "type": "GPU_Video_Controller",
    "state": "Enabled",
    "createDate": "Nov 14, 2017 10:20:57 PM",
    "lastOpDate": "Nov 14, 2017 10:20:57 PM"
  }
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventory MdevDeviceSpecInventory See inventory 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventory
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
specification String Spec details 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceSpecState See state 3.5.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceSpecState Enabled 3.5.0
Disabled MdevDeviceSpecState Disabled 3.5.0

SDK Examples

Java SDK
UpdateMdevDeviceSpecAction action = new UpdateMdevDeviceSpecAction();
action.uuid = "54e2b878d3d9473ab611794ad04d24b7";
action.name = "GRID_M60-2A";
action.description = "NVIDIA Corporation, GM204GL [Tesla M60], a1, VGA compatible controller";
action.state = "Enabled";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateMdevDeviceSpecAction.Result res = action.call();
Python SDK
UpdateMdevDeviceSpecAction action = UpdateMdevDeviceSpecAction()
action.uuid = "e351f911f77f422f9229cf0426ffa608"
action.name = "GRID_M60-2A"
action.description = "NVIDIA Corporation, GM204GL [Tesla M60], a1, VGA compatible controller"
action.state = "Enabled"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
UpdateMdevDeviceSpecAction.Result res = action.call()

GetMdevDeviceCandidates

API Request

URLs
GET zstack/v1/mdev-devices/candidates
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/mdev-devices/candidates?vmInstanceUuid=3be91dd3332a3ef0b57831dcfc28a0c2&types=GPU_Video_Controller
Parameter List
Name Type Location Description Allowed Values Starting Version
clusterUuids (Optional) List query Cluster UUID 3.5.0
hostUuid (Optional) String query Host UUID 3.5.0
vmInstanceUuid (Optional) String query Virtual Machine UUID 3.5.0
types (Optional) List query Device type 3.5.0
systemTags (Optional) List query System tags 3.5.0
userTags (Optional) List query User tags 3.5.0

API Response

Response Example
{
  "inventories": [
    {
      "uuid": "ff09c7d3eb084e0c92d91f91559b0015",
      "name": "GRID M60-2A",
      "parentUuid": "cd35f76c62ec4e0ca5af3f93434f9410",
      "hostUuid": "55c3da7722a442fcbf5cc2373cb45dc7",
      "mdevSpecUuid": "55d7980cf5604dd6b45e2946fa75a312",
      "type": "GPU_Video_Controller",
      "state": "Enabled",
      "status": "Active",
      "chooser": "None",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
uuid String UUID of the resource, uniquely identifies the resource 3.5.0
name String Resource name 3.5.0
description String Resource description 3.5.0
parentUuid String Physical PCI device UUID 3.5.0
hostUuid String Host UUID 3.5.0
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0
type MdevDeviceType See type 3.5.0
state MdevDeviceState See state 3.5.0
status MdevDeviceStatus See status 3.5.0
chooser MdevDeviceChooser See chooser 4.1.0
#type
Name Type Description Starting Version
GPU_Video_Controller MdevDeviceType GPU video controller 3.5.0
#state
Name Type Description Starting Version
Enabled MdevDeviceState Enabled 3.5.0
Disabled MdevDeviceState Disabled 3.5.0
#status
Name Type Description Starting Version
Active MdevDeviceStatus Ready 3.5.0
Attached MdevDeviceStatus Attached 3.5.0
#chooser
Name Type Description Starting Version
None PciDeviceChooser The None value. 4.2.0
Device PciDeviceChooser The Device value. 4.2.0
Spec PciDeviceChooser The Spec value. 4.2.0

SDK Examples

Java SDK
GetMdevDeviceCandidatesAction action = new GetMdevDeviceCandidatesAction();
action.vmInstanceUuid = "3be91dd3332a3ef0b57831dcfc28a0c2";
action.types = asList("GPU_Video_Controller");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
GetMdevDeviceCandidatesAction.Result res = action.call();
Python SDK
GetMdevDeviceCandidatesAction action = GetMdevDeviceCandidatesAction()
action.vmInstanceUuid = "3be91dd3332a3ef0b57831dcfc28a0c2"
action.types = [GPU_Video_Controller]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
GetMdevDeviceCandidatesAction.Result res = action.call()

QueryVmInstanceMdevDeviceSpecRef

API Request

URLs
GET zstack/v1/vm-instances/{vmInstanceUuid}/mdev-device-specs
GET zstack/v1/vm-instances/{vmInstanceUuid}/mdev-device-specs/{mdevSpecUuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/{vmInstanceUuid}/mdev-device-specs?q=vmInstanceUuid=15ea1f7027833d9ea566ea590184d5d2
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/vm-instances/{vmInstanceUuid}/mdev-device-specs/{mdevSpecUuid}?q=vmInstanceUuid=5e3c68fed5ef39089614830ff30dfd50

Queryable Fields

Run the CLI command tool, enter QueryVmInstanceMdevDeviceSpecRef and press Tab to view all queryable fields and resource names that support cross-table queries.

API Response

Response Example
{
  "inventories": [
    {
      "vmInstanceUuid": "87fbb32e8d5b47be9c79611ea8b8dbca",
      "mdevSpecUuid": "75c34cf335f84f7e85bba4289a9d5257",
      "mdevDeviceNumber": 1,
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the operation succeeded. 0.6
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. See error 3.5.0
inventories List See inventories 3.5.0
#error
Name Type Description Starting Version
code String Error code, a globally unique identifier of the error, e.g. SYS.1000, HOST.1001 3.5.0
description String Brief description of the error 3.5.0
details String Detailed error information 3.5.0
elaboration String Reserved field, defaults to null 3.5.0
opaque LinkedHashMap Reserved field, defaults to null 3.5.0
cause ErrorCode Root cause, the source error that caused the current error, null if no original error 3.5.0
#inventories
Name Type Description Starting Version
vmInstanceUuid String Virtual Machine UUID 3.5.0
mdevSpecUuid String MDEV device spec UUID 3.5.0
mdevDeviceNumber Integer Number of mdev devices that meet the spec to attach to the VM, defaults to 1 3.5.0
createDate Timestamp Create date 3.5.0
lastOpDate Timestamp Last update date 3.5.0

SDK Examples

Java SDK
QueryVmInstanceMdevDeviceSpecRefAction action = new QueryVmInstanceMdevDeviceSpecRefAction();
action.conditions = asList("vmInstanceUuid=308f8eccec9b320bbe082f233e7f822c");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryVmInstanceMdevDeviceSpecRefAction.Result res = action.call();
Python SDK
QueryVmInstanceMdevDeviceSpecRefAction action = QueryVmInstanceMdevDeviceSpecRefAction()
action.conditions = ["vmInstanceUuid=254f7f2f30bb3b7bb26595fc5120a63b"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
QueryVmInstanceMdevDeviceSpecRefAction.Result res = action.call()
PreviousHost Hardware Device APIsNextUSB Redirect Related Interfaces
API Reference | ZStack ZSphere · ZVF | ZStack Resource Center