virt.instance.create

Create a new virtualized instance.

Type: object

Type: array
No Additional Items

Tuple Validation

Parameter 1: virt_instance_create

virt_instance_create

Type: object

VirtInstanceCreateArgs parameters.

 No Additional Properties

Name

Type: string

Name for the new virtual instance.

Must be at least 1 characters long

Must be at most 200 characters long

Source Type

Type: const Default: "IMAGE"

Source type for instance creation.

Must be one of:
  • "IMAGE"
Specific value: "IMAGE"

Storage Pool

Default: null

Storage pool under which to allocate root filesystem. Must be one of the pools listed in virt.global.config output under "storage_pools". If None (default) then the pool specified in the global configuration will be used.

Type: string

Must be at least 1 characters long

Type: null

Image

Type: string

Image identifier to use for creating the instance.

Must be at least 1 characters long

Must be at most 200 characters long

Root Disk Size

Type: integer Default: 10

This can be specified when creating VMs so the root device's size can be configured. Root device for VMs is a sparse zvol and the field specifies space in GBs and defaults to 10 GBs.

Value must be greater or equal to 5

Root Disk Io Bus

Type: enum (of string) Default: "NVME"

I/O bus type for the root disk (defaults to NVME for best performance).

Must be one of:
  • "NVME"
  • "VIRTIO-BLK"
  • "VIRTIO-SCSI"

Remote

Type: const Default: "LINUX_CONTAINERS"

Remote image source to use.

Must be one of:
  • "LINUX_CONTAINERS"
Specific value: "LINUX_CONTAINERS"

Instance Type

Type: const Default: "CONTAINER"

Type of instance to create.

Must be one of:
  • "CONTAINER"
Specific value: "CONTAINER"

Environment

Default: null

Environment variables to set inside the instance.

Type: object

Each additional property must conform to the following schema

Type: string
Type: null

Autostart

Default: true

Whether the instance should automatically start when the host boots.

Type: boolean
Type: null

Cpu

Default: null

CPU allocation specification or null for automatic allocation.

Type: string
Type: null

Devices

Default: null

Array of devices to attach to the instance.

Type: array
No Additional Items
Each item of this array must be:

Disk

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for virtual disk devices.

Must be one of:
  • "DISK"
Specific value: "DISK"

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.

Type: string

Must be at least 1 characters long

Type: null

Destination

Default: null

Target path where the disk appears inside the virtualized instance.

Type: string
Type: null

Boot Priority

Default: null

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

Type: integer

Value must be greater or equal to 0

Type: null

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

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.

Type: string

Must be at least 1 characters long

Type: null

GPU

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for graphics processing units.

Must be one of:
  • "GPU"
Specific value: "GPU"

Gpu Type

Type: enum (of string)

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

Must be one of:
  • "PHYSICAL"
  • "MDEV"
  • "MIG"
  • "SRIOV"

Id

Default: null

Unique identifier for the GPU device.

Type: string
Type: null

Gid

Default: null

Group ID for device permissions inside the container.

Type: integer

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

Type: null

Uid

Default: null

User ID for device permissions inside the container.

Type: integer

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

Type: null

Mode

Default: null

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

Type: string
Type: null

Mdev

Default: null

Mediated device identifier for GPU virtualization.

Type: string

Must be at least 1 characters long

Type: null

Mig Uuid

Default: null

Multi-Instance GPU UUID for NVIDIA GPU partitioning.

Type: string

Must be at least 1 characters long

Type: null

Pci

Default: null

PCI address of the GPU device on the host system.

Type: string

Must be at least 1 characters long

Type: null

Productid

Default: null

Product identifier for GPU device matching.

Type: string

Must be at least 1 characters long

Type: null

Vendorid

Default: null

Vendor identifier for GPU device matching.

Type: string

Must be at least 1 characters long

Type: null

Proxy

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for network port forwarding.

Must be one of:
  • "PROXY"
Specific value: "PROXY"

Source Proto

Type: enum (of string)

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

Must be one of:
  • "UDP"
  • "TCP"

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

Type: enum (of string)

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

Must be one of:
  • "UDP"
  • "TCP"

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

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for Trusted Platform Module devices.

Must be one of:
  • "TPM"
Specific value: "TPM"

Path

Default: null

Path to the TPM device on the host system.

Type: string
Type: null

Pathrm

Default: null

Resource manager path for TPM device access.

Type: string
Type: null

USB

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for USB devices.

Must be one of:
  • "USB"
Specific value: "USB"

Bus

Default: null

USB bus number on the host system.

Type: integer
Type: null

Dev

Default: null

USB device number on the specified bus.

Type: integer
Type: null

Product Id

Default: null

USB product identifier for device matching.

Type: string
Type: null

Vendor Id

Default: null

USB vendor identifier for device matching.

Type: string
Type: null

NIC

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for network interface cards.

Must be one of:
  • "NIC"
Specific value: "NIC"

Network

Default: null

Name of the network to connect this NIC to.

Type: string

Must be at least 1 characters long

Type: null

Nic Type

Default: null

Type of network interface (bridged or macvlan).

Type: enum (of string)
Must be one of:
  • "BRIDGED"
  • "MACVLAN"
Type: null

Parent

Default: null

Parent network interface on the host system.

Type: string

Must be at least 1 characters long

Type: null

Mac

Default: null

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

Type: string
Type: null

PCI

Type: object
No Additional Properties

Name

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

Device type identifier for PCI device passthrough.

Must be one of:
  • "PCI"
Specific value: "PCI"

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

Default: null

Optional human-readable name for the virtualization device.

Type: string

Must be at least 1 characters long

Type: null

Description

Default: null

Optional description explaining the purpose or configuration of this device.

Type: string

Must be at least 1 characters long

Type: null

Readonly

Type: boolean Default: false

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

Dev Type

Type: const

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

Must be one of:
  • "CDROM"
Specific value: "CDROM"

Source

Type: string

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

Must be at least 1 characters long

Boot Priority

Default: null

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

Type: integer

Value must be greater or equal to 0

Type: null
Type: null

Memory

Default: null

Memory allocation in bytes or null for automatic allocation.

Type: integer
Type: null

Privileged Mode

Type: boolean Default: false

This is only valid for containers and should only be set when container instance which is to be deployed is to run in a privileged mode.

VirtInstanceEntry

Type: object

The created virtual instance configuration.

 No Additional Properties

Id

Type: string

Unique identifier for the virtual instance.

Name

Type: string

Human-readable name for the virtual instance.

Must be at least 1 characters long

Must be at most 200 characters long

Type

Type: enum (of string) Default: "CONTAINER"

Type of virtual instance.

Must be one of:
  • "CONTAINER"
  • "VM"

Status

Type: enum (of string)

Current operational status of the virtual instance.

Must be one of:
  • "RUNNING"
  • "STOPPED"
  • "UNKNOWN"
  • "ERROR"
  • "FROZEN"
  • "STARTING"
  • "STOPPING"
  • "FREEZING"
  • "THAWED"
  • "ABORTING"

Cpu


CPU configuration string or null for default allocation.

Type: string
Type: null

Memory


Memory allocation in bytes or null for default allocation.

Type: integer
Type: null

Autostart

Type: boolean

Whether the instance automatically starts when the host boots.

Environment

Type: object

Environment variables to set inside the instance.

Each additional property must conform to the following schema

Type: string

Aliases

Type: array of object

Array of IP aliases configured for the instance.

 No Additional Items
Each item of this array must be:

VirtInstanceAlias

Type: object
No Additional Properties

Type

Type: enum (of string)

Type of IP address (INET for IPv4, INET6 for IPv6).

Must be one of:
  • "INET"
  • "INET6"

Address

Type: string

IP address for the virtual instance.

Must be at least 1 characters long

Netmask


Network mask in CIDR notation.

Type: integer
Type: null

Image

Type: object

Image information used to create this instance.

 No Additional Properties

Architecture


Hardware architecture of the image (e.g., amd64, arm64).

Type: string
Type: null

Description


Human-readable description of the image.

Type: string
Type: null

Os


Operating system family of the image.

Type: string
Type: null

Release


Version or release name of the operating system.

Type: string
Type: null

Serial


Unique serial identifier for the image.

Type: string
Type: null

Type


Type of image (container, virtual-machine, etc.).

Type: string
Type: null

Variant


Image variant (default, cloud, minimal, etc.).

Type: string
Type: null

Secureboot


Whether the image supports UEFI Secure Boot.

Type: boolean
Type: null


User namespace ID mapping configuration for privilege isolation.

UserNsIdmap

Type: object
No Additional Properties


User ID mapping configuration for user namespace isolation.

IdmapUserNsEntry

Type: object
No Additional Properties

Hostid

Type: integer

Starting host ID for the mapping range.

Maprange

Type: integer

Number of IDs to map in this range.

Nsid

Type: integer

Starting namespace ID for the mapping range.
Type: null


Group ID mapping configuration for user namespace isolation.

IdmapUserNsEntry

Type: object
No Additional Properties

Hostid

Type: integer

Starting host ID for the mapping range.

Maprange

Type: integer

Number of IDs to map in this range.

Nsid

Type: integer

Starting namespace ID for the mapping range.
Type: null
Type: null

Raw


Raw low-level configuration options (advanced use only).

Type: object
Type: null

Vnc Enabled

Type: boolean

Whether VNC remote access is enabled for the instance.

Vnc Port


TCP port number for VNC connections or null if VNC is disabled.

Type: integer
Type: null

Vnc Password


Password for VNC access or null if no password is set.

Type: string

Must be at least 1 characters long

Type: null

Secure Boot


Whether UEFI Secure Boot is enabled (VMs only) or null for containers.

Type: boolean
Type: null

Privileged Mode


Whether the container runs in privileged mode or null for VMs.

Type: boolean
Type: null

Root Disk Size


Size of the root disk in GB or null for default size.

Type: integer
Type: null

Root Disk Io Bus

Type: enum (of null or string)

I/O bus type for the root disk or null for default.

Must be one of:
  • "NVME"
  • "VIRTIO-BLK"
  • "VIRTIO-SCSI"
  • null

Storage Pool

Type: string

Storage pool in which the root of the instance is located.

Must be at least 1 characters long



Required roles: VIRT_INSTANCE_WRITE