virt.instance.device_add

Add a device to an instance.

Type: object

Call parameters

Type: array
No Additional Items

Tuple Validation

Parameter 1: id

id

Type: string

ID of the virtual instance to add device to.

Parameter 2: device

device

Device configuration to add to the instance.

One of

• Disk
• GPU
• Proxy
• TPM
• USB
• NIC
• PCI
• CDROM

Disk

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for virtual disk devices.

Must be one of:

• "DISK"

Specific value: "DISK"

source

Source

Default: null

For CONTAINER instances, this would be a valid pool path. For VM instances, it can be a valid zvol path or an incus storage volume name.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

destination

Destination

Default: null

Target path where the disk appears inside the virtualized instance.

Any of

• Option 1
• Option 2

Type: string

Type: null

boot_priority

Boot Priority

Default: null

Boot priority for this disk device. Lower numbers boot first. null means non-bootable.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 0

Type: null

io_bus

Io Bus

Type: enum (of null or string) Default: null

Storage bus type for optimal performance and compatibility.

Must be one of:

• "NVME"
• "VIRTIO-BLK"
• "VIRTIO-SCSI"
• null

storage_pool

Storage Pool

Default: null

Storage pool in which the device is located. This must be one of the storage pools listed in virt.global.config output.
If this is set to None during device creation, then the default storage pool defined in virt.global.config will be used.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

GPU

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for graphics processing units.

Must be one of:

• "GPU"

Specific value: "GPU"

gpu_type Required

Gpu Type

Type: enum (of string)

Type of GPU virtualization (physical passthrough, mediated device, etc.).

Must be one of:

• "PHYSICAL"
• "MDEV"
• "MIG"
• "SRIOV"

id

Id

Default: null

Unique identifier for the GPU device.

Any of

• Option 1
• Option 2

Type: string

Type: null

gid

Gid

Default: null

Group ID for device permissions inside the container.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 0 and lesser or equal to 90000000

Type: null

uid

Uid

Default: null

User ID for device permissions inside the container.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 0 and lesser or equal to 90000000

Type: null

mode

Mode

Default: null

Permission mode for device access (e.g., '660').

Any of

• Option 1
• Option 2

Type: string

Type: null

mdev

Mdev

Default: null

Mediated device identifier for GPU virtualization.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

mig_uuid

Mig Uuid

Default: null

Multi-Instance GPU UUID for NVIDIA GPU partitioning.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

pci

Pci

Default: null

PCI address of the GPU device on the host system.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

productid

Productid

Default: null

Product identifier for GPU device matching.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

vendorid

Vendorid

Default: null

Vendor identifier for GPU device matching.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

Proxy

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for network port forwarding.

Must be one of:

• "PROXY"

Specific value: "PROXY"

source_proto Required

Source Proto

Type: enum (of string)

Network protocol (TCP or UDP) for the source connection.

Must be one of:

• "UDP"
• "TCP"

source_port Required

Source Port

Type: integer

Source port number on the host system to forward from.

Value must be greater or equal to 1 and lesser or equal to 65535

dest_proto Required

Dest Proto

Type: enum (of string)

Network protocol (TCP or UDP) for the destination connection.

Must be one of:

• "UDP"
• "TCP"

dest_port Required

Dest Port

Type: integer

Destination port number inside the virtualized instance.

Value must be greater or equal to 1 and lesser or equal to 65535

TPM

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for Trusted Platform Module devices.

Must be one of:

• "TPM"

Specific value: "TPM"

path

Path

Default: null

Path to the TPM device on the host system.

Any of

• Option 1
• Option 2

Type: string

Type: null

pathrm

Pathrm

Default: null

Resource manager path for TPM device access.

Any of

• Option 1
• Option 2

Type: string

Type: null

USB

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for USB devices.

Must be one of:

• "USB"

Specific value: "USB"

bus

Bus

Default: null

USB bus number on the host system.

Any of

• Option 1
• Option 2

Type: integer

Type: null

dev

Dev

Default: null

USB device number on the specified bus.

Any of

• Option 1
• Option 2

Type: integer

Type: null

product_id

Product Id

Default: null

USB product identifier for device matching.

Any of

• Option 1
• Option 2

Type: string

Type: null

vendor_id

Vendor Id

Default: null

USB vendor identifier for device matching.

Any of

• Option 1
• Option 2

Type: string

Type: null

NIC

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for network interface cards.

Must be one of:

• "NIC"

Specific value: "NIC"

network

Network

Default: null

Name of the network to connect this NIC to.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

nic_type

Nic Type

Default: null

Type of network interface (bridged or macvlan).

Any of

• Option 1
• Option 2

Type: enum (of string)

Must be one of:

• "BRIDGED"
• "MACVLAN"

Type: null

parent

Parent

Default: null

Parent network interface on the host system.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

mac

Mac

Default: null

MAC address for the virtual network interface. null for auto-generated.

Any of

• Option 1
• Option 2

Type: string

Type: null

PCI

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for PCI device passthrough.

Must be one of:

• "PCI"

Specific value: "PCI"

address Required

Address

Type: string

PCI bus address of the device to pass through to the virtualized instance.

Must be at least 1 characters long

CDROM

Type: object
No Additional Properties

name

Name

Default: null

Optional human-readable name for the virtualization device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

description

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Any of

• Option 1
• Option 2

Type: string

Must be at least 1 characters long

Type: null

readonly

Readonly

Type: boolean Default: false

Whether the device should be mounted in read-only mode.

dev_type Required

Dev Type

Type: const

Device type identifier for CD-ROM/DVD optical drives.

Must be one of:

• "CDROM"

Specific value: "CDROM"

source Required

Source

Type: string

Path to the ISO image file or physical optical drive to mount.

Must be at least 1 characters long

boot_priority

Boot Priority

Default: null

Boot priority for this optical device. Lower numbers boot first. null means non-bootable.

Any of

• Option 1
• Option 2

Type: integer

Value must be greater or equal to 0

Type: null

Return value

Result

Type: const

Returns true when the device is successfully added.

Must be one of:

• true

Specific value: true

Required roles: VIRT_INSTANCE_WRITE