> ## Documentation Index > Fetch the complete documentation index at: https://docs.siderolabs.com/llms.txt > Use this file to discover all available pages before exploring further. > VirtualMachineConfig is a virtual machine configuration document. VirtualMachineConfig declares a virtual machine run by Talos. This document is the skeleton of the virtual machine: the rest of the machine's shape (firmware, disks, network interfaces, guest seeding, consoles) is added to it over time, and every addition is a new field rather than a change to an existing one. Status is reported via `VirtualMachineStatus`. # VirtualMachineConfig ```yaml theme={null} apiVersion: v1alpha1 kind: VirtualMachineConfig name: vm1 # Name of the virtual machine. powerState: running # Power state the virtual machine is driven towards. # Processor settings for the virtual machine. cpu: count: 4 # Number of virtual CPUs presented to the guest. limit: 3000m # Host CPU ceiling in millicores for the whole virtual machine, vCPUs and emulator threads # Optional guest CPU geometry and host CPU pinning. topology: sockets: 1 # Number of guest sockets. If any geometry dimension is set, all three must be cores: 2 # Number of guest cores per socket, not host CPU IDs. threads: 2 # Number of guest threads per core, not host CPU IDs. # Host CPUs the guest's threads are pinned to; independent of guest geometry and `cpu.limit`. pinning: # Per-vCPU pins. vcpus: - vcpu: 0 # Guest vCPU index, starting at 0 and below `cpu.count`. cpus: "8" # Host CPUs the vCPU is pinned to, as a Linux CPU list, e.g. `8` or `9-10`. - vcpu: 1 # Guest vCPU index, starting at 0 and below `cpu.count`. cpus: 9-10 # Host CPUs the vCPU is pinned to, as a Linux CPU list, e.g. `8` or `9-10`. emulator: 0-1 # Host CPUs the emulator threads (everything of the virtual machine that is not a vCPU) # Memory settings for the virtual machine. memory: size: 4GiB # Memory allocated to the guest at boot. # Memory ballooning settings. ballooning: enabled: true # Attach a virtio-balloon device, letting the host reclaim memory the guest is not using. # Host NUMA nodes the guest memory is placed on. numa: mode: strict # How guest memory is bound to the nodes. nodes: "1" # Host NUMA nodes the guest memory is placed on, as a Linux node list, e.g. `1` or `0-1`. # Firmware the virtual machine boots. firmware: type: uefi # Firmware the guest boots. # Secure boot settings. secureBoot: enabled: true # Boot the guest with secure boot. # Disks attached to the virtual machine. disks: - name: system # Name of the disk, unique within the virtual machine. pool: pool1 # Name of the `StoragePool` document this disk's volume lives in. size: 20GiB # Size of the volume. bootOrder: 1 # Position of this disk in the guest's boot order, lowest first. # Where the volume's contents come from. provision: # Create an empty volume, formatted per `format`. blank: {} - name: data # Name of the disk, unique within the virtual machine. pool: pool1 # Name of the `StoragePool` document this disk's volume lives in. size: 100GiB # Size of the volume. # Where the volume's contents come from. provision: # Create an empty volume, formatted per `format`. blank: {} - name: install # Name of the disk, unique within the virtual machine. type: cdrom # Kind of device the disk is presented as. bootOrder: 2 # Position of this disk in the guest's boot order, lowest first. # Where the volume's contents come from. provision: # Attach read-only CD-ROM media from a content library. fromImage: library: images # Name of the `ContentLibraryConfig` document holding the image. file: ubuntu-24.04.iso # Name of the file within that library. # # Integrity check of the library file, verified before the media is attached. # digest: sha256:5f2bc19e8b4b5b4a8b5e9c0d1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c # # Name of the `StoragePool` document this disk's volume lives in. # pool: pool1 # Consoles attached to the virtual machine. console: # Serial console settings. serial: enabled: true # Attach a serial console. # VNC console settings. vnc: enabled: true # Attach a VNC console. # Networking settings for the virtual machine. networking: # Network interfaces presented to the guest. interfaces: - name: net0 # Name of the interface, unique within the virtual machine. link: eth0 # Kernel name (or alias) of the host link the interface is attached to. # # Hardware (MAC) address presented to the guest. # hardwareAddr: 52:54:00:12:34:56 - name: net1 # Name of the interface, unique within the virtual machine. link: eth1 # Kernel name (or alias) of the host link the interface is attached to. # # Hardware (MAC) address presented to the guest. # hardwareAddr: 52:54:00:12:34:56 # Settings which apply inside the guest. guest: # Seed handed to the guest on first boot. cloudInit: library: targetlibrary # Name of the content library where Talos stores the generated NoCloud ISO. metaData: | # Contents of the seed's `meta-data` file, carrying the guest's identity. instance-id: vm1-001 local-hostname: vm1 userData: | # Contents of the seed's `user-data` file, carrying what the operator wants done. #cloud-config users: - name: op ssh_authorized_keys: - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5... # qemu-guest-agent settings. agent: enabled: true # Attach the qemu-guest-agent virtio-serial channel to the domain. ```
Field Type Description Value(s)
`name` string Name of the virtual machine.

Must be between 1 and 63 characters long, and can only contain ASCII letters,
digits and hyphens. It is the ID used to address the virtual machine over the API.
`powerState` PowerState Power state the virtual machine is driven towards. `running`
`stopped`
`suspended`
`cpu` VirtualMachineCPU Processor settings for the virtual machine.
`memory` VirtualMachineMemory Memory settings for the virtual machine.
`firmware` VirtualMachineFirmware Firmware the virtual machine boots.
`disks` VirtualMachineDisk Disks attached to the virtual machine.

Removing a disk detaches it from the virtual machine; the volume backing it stays in
its storage pool and is deleted separately.

A configuration patch merges into this list by disk name: a patch entry naming an
existing disk updates that disk, and any other entry is appended. Removing a disk
requires supplying the document in full.
`console` VirtualMachineConsole Consoles attached to the virtual machine.

Optional; omitting it leaves both consoles detached.
`networking` VirtualMachineNetworking Networking settings for the virtual machine.

Optional; a virtual machine with no interfaces has no network connectivity at all.
`guest` VirtualMachineGuest Settings which apply inside the guest.

Optional; omitting it leaves the guest to boot its image unmodified.
`video` VirtualMachineVideo Video device presented to the guest on amd64 when a VNC console is enabled.
Other architectures use libvirt's defaults; without VNC this block has no effect.
Optional; omitting it uses `vga` with libvirt's default VRAM on amd64.
## cpu VirtualMachineCPU describes the processors presented to the guest and the host time they may consume. There is deliberately no matching memory ceiling. Guest memory is already fixed by `memory.size`, and libvirt advises against a QEMU memory hard limit: the emulator's own footprint over guest RAM is not predictable, and a limit guessed too low has the kernel kill the virtual machine.
Field Type Description Value(s)
`count` uint32 Number of virtual CPUs presented to the guest.

This is the total vCPU count, not a per-socket or per-core figure: how those vCPUs are
laid out into sockets, cores and threads can be configured with `topology`.
`limit` string Host CPU ceiling in millicores for the whole virtual machine, vCPUs and emulator threads
together, mapped onto the domain's global CFS quota.

`1000m` is one host core. The ceiling is independent of `count`: a guest with four
vCPUs and a `2000m` ceiling sees four processors but is scheduled for at most two cores
of host time.

Optional; omitting it leaves the virtual machine bounded only by its vCPU count.
`topology` VirtualMachineCPUTopology Optional guest CPU geometry and host CPU pinning.

Geometry counts describe the guest, not host CPU IDs. When any dimension is set,
all three must be positive and their product must equal `count`.
Pinning may be configured without guest geometry.
### topology VirtualMachineCPUTopology describes guest CPU geometry and independent host CPU pinning.
Field Type Description Value(s)
`sockets` uint32 Number of guest sockets. If any geometry dimension is set, all three must be
positive and sockets \* cores \* threads must equal `cpu.count`.
`cores` uint32 Number of guest cores per socket, not host CPU IDs.
`threads` uint32 Number of guest threads per core, not host CPU IDs.
`pinning` VirtualMachineCPUPinning Host CPUs the guest's threads are pinned to; independent of guest geometry and `cpu.limit`.
Optional; omitting it leaves the virtual machine schedulable on any host CPU.
#### pinning VirtualMachineCPUPinning describes which host CPUs the guest's threads are pinned to. Host CPU IDs are the kernel's logical CPU numbers, SMT threads included. Whether a named CPU exists and is available is only known on the host, when the virtual machine starts.
Field Type Description Value(s)
`vcpus` VirtualMachineVCPUPin Per-vCPU pins.

A vCPU left out of this list is scheduled on any host CPU.

A configuration patch replaces this list as a whole rather than appending to it.
`emulator` string Host CPUs the emulator threads (everything of the virtual machine that is not a vCPU)
are pinned to, as a Linux CPU list, e.g. `0-1,4`.

Optional; omitting it leaves the emulator threads unpinned.
##### vcpus\[] VirtualMachineVCPUPin pins one guest vCPU to a set of host CPUs.
Field Type Description Value(s)
`vcpu` uint32 Guest vCPU index, starting at 0 and below `cpu.count`.
`cpus` string Host CPUs the vCPU is pinned to, as a Linux CPU list, e.g. `8` or `9-10`.
## memory VirtualMachineMemory describes the memory presented to the guest.
Field Type Description Value(s)
`size` ByteSize Memory allocated to the guest at boot.

Size is specified in bytes, but can be expressed in human readable format, e.g. 4GiB.
`ballooning` VirtualMachineBallooning Memory ballooning settings.

Optional; ballooning is disabled when this section is omitted.
`numa` VirtualMachineNUMA Host NUMA nodes the guest memory is placed on.

Optional; omitting it leaves placement to the host.
### ballooning VirtualMachineBallooning describes the virtio-balloon settings for a virtual machine.
Field Type Description Value(s)
`enabled` bool Attach a virtio-balloon device, letting the host reclaim memory the guest is not using.

Ballooning only shrinks the guest below `memory.size`; growing beyond it is memory
hot-add, which is a separate mechanism.

Optional; defaults to disabled.
### numa VirtualMachineNUMA describes where the guest memory is placed on the host.
Field Type Description Value(s)
`mode` VirtualMachineNUMAMode How guest memory is bound to the nodes.

`strict` fails allocations that cannot be served from `nodes`; `preferred` falls back
to other nodes; `interleave` spreads pages across `nodes` round-robin.

Optional; defaults to `strict`.		 `strict`
`preferred`
`interleave`
`nodes` string Host NUMA nodes the guest memory is placed on, as a Linux node list, e.g. `1` or `0-1`.

Whether a named node exists is only known on the host, when the virtual machine starts.
## firmware VirtualMachineFirmware describes the firmware a virtual machine boots.
Field Type Description Value(s)
`type` VirtualMachineFirmwareType Firmware the guest boots.

Required, and unchangeable for the life of the guest: a guest installed under one
firmware will not boot under the other. `uefi` is the only option on arm64, and the only
one secure boot can be used with.		 `uefi`
`bios`
`secureBoot` VirtualMachineFirmwareSecureBoot Secure boot settings.

Optional; secure boot is disabled when this section is omitted.
### secureBoot VirtualMachineFirmwareSecureBoot describes the secure boot settings of a virtual machine.
Field Type Description Value(s)
`enabled` bool Boot the guest with secure boot.

Requires `type: uefi`. Talos keeps a per-virtual-machine variable store alongside the
rest of the machine's identity, seeded from a signed firmware template and preserved for
the life of the guest, as it is where the enrolled keys live.

Optional; defaults to disabled.
## disks\[] VirtualMachineDisk describes a single disk attached to a virtual machine.
Field Type Description Value(s)
`name` string Name of the disk, unique within the virtual machine.

Must be between 1 and 63 characters long, and can only contain ASCII letters,
digits and hyphens. It names the volume created in the storage pool.
`pool` string Name of the `StoragePool` document this disk's volume lives in.

The pool is declared separately and is not provisioned by this document, but it must be
declared: a disk naming a pool no `StoragePool` document declares is a configuration
error.

The volume is named after this virtual machine and this disk, so a volume of that name
already in the pool is adopted with its existing contents. Removing the disk from the
configuration never deletes the volume, so re-declaring the same virtual machine and disk
names in the same pool reattaches the same data.

Required for a `disk`, and not allowed on a `cdrom`, whose image is attached in place
from its content library and never lands in a pool.
`size` ByteSize Size of the volume.

Size is specified in bytes, but can be expressed in human readable format, e.g. 20GiB.

Required for a `disk`, and not allowed on a `cdrom`, whose size is that of its image.
`format` VirtualMachineDiskFormat On-disk format of a blank volume.

Choose `raw` or `qcow2` for a writable disk provisioned with `blank`. The format is not
inferred from a content library image. Writable image-derived disks are not supported.

Optional; defaults to `qcow2`. Not allowed on a `cdrom`, which is used as-is.		 `raw`
`qcow2`
`bus` VirtualMachineDiskBus Controller the disk is attached to.

`virtio` for anything modern; `sata` for guests without virtio drivers at install time.

Optional; defaults to `virtio` on a `disk` and to `sata` on a `cdrom`. A `cdrom` cannot
be attached to `virtio`, which presents no ejectable media.		 `virtio`
`scsi`
`sata`
`type` VirtualMachineDiskType Kind of device the disk is presented as.

A `cdrom` is read-only -- QEMU emulates no CD burner -- so its contents are required and
it has no size and no format of its own.

Optional; defaults to `disk`.		 `disk`
`cdrom`
`bootOrder` uint32 Position of this disk in the guest's boot order, lowest first.

Values must be unique across everything the virtual machine can boot from. Only disks
are bootable today, so that is only the disks; network interfaces will share this
namespace once they are configurable.

Optional; a disk without a boot order is not booted from.
`provision` VirtualMachineDiskProvision Where the volume's contents come from.

Exactly one source must be set.
### provision VirtualMachineDiskProvision describes where a disk's contents come from. Exactly one source must be set.
Field Type Description Value(s)
`blank` VirtualMachineDiskBlank Create an empty volume, formatted per `format`.

Not allowed on a `cdrom`, which has no meaningful empty contents.
`fromImage` VirtualMachineDiskFromImage Attach read-only CD-ROM media from a content library.

Set `type: cdrom` and omit `pool`, `size`, `format`, and `mode`; the library file is
attached in place, not copied into a volume. Writable image-derived disks (copy or
linked) are not supported. Use `provision.blank` for a writable disk and install from
CD-ROM media.
#### blank VirtualMachineDiskBlank provisions an empty volume. #### fromImage VirtualMachineDiskFromImage references media in a content library.
Field Type Description Value(s)
`library` string Name of the `ContentLibraryConfig` document holding the image.
`file` string Name of the file within that library.
`digest` string Integrity check of the library file, verified before the media is attached.

Written as `:`, under either `sha256` or `sha512`.

Optional; the file is used as-is when this is unset.
`mode` VirtualMachineDiskImageMode Mode for deriving a writable disk from an image (not supported yet).

Neither `copy` nor `linked` currently provisions a writable image-derived disk. For a
writable disk, use `provision.blank` instead; for image media, use a read-only `cdrom`.

Omit this field on a `cdrom`: even an explicit `copy` is rejected because its read-only
medium is attached in place. An omitted mode defaults to `copy` for a disk, but that
writable image-derived configuration is not supported.		 `copy`
`linked`
## console VirtualMachineConsole describes the consoles attached to a virtual machine.
Field Type Description Value(s)
`serial` VirtualMachineSerial Serial console settings.
`vnc` VirtualMachineVNC VNC console settings.
### serial VirtualMachineSerial describes the serial console of a virtual machine.
Field Type Description Value(s)
`enabled` bool Attach a serial console.

Optional; defaults to disabled.
### vnc VirtualMachineVNC describes the VNC console of a virtual machine.
Field Type Description Value(s)
`enabled` bool Attach a VNC console.

Optional; defaults to disabled.
## networking VirtualMachineNetworking describes the networking of a virtual machine.
Field Type Description Value(s)
`interfaces` VirtualMachineInterface Network interfaces presented to the guest.

Removing an interface from this list detaches it from the virtual machine.

A configuration patch replaces this list as a whole rather than appending to it.
### interfaces\[] VirtualMachineInterface describes a single network interface of a virtual machine.
Field Type Description Value(s)
`name` string Name of the interface, unique within the virtual machine.

Must be between 1 and 63 characters long, and can only contain ASCII letters,
digits and hyphens. This is how the interface is addressed over the API; it is not the
device name inside the guest, which the guest kernel chooses for itself.
`link` string Kernel name (or alias) of the host link the interface is attached to.

The link must already exist on the host and be an Ethernet link, e.g. a physical
interface, a bond, or a VLAN. It is attached to as is.
`hardwareAddr` HardwareAddr Hardware (MAC) address presented to the guest.

Defaults to an address derived from the virtual machine and interface names, which is
stable for as long as both keep their names. Set it to pin the address a DHCP server
reserves against, or to keep one across a rename.

It must be a unicast address, and is not allowed to be all zeroes.
## guest VirtualMachineGuest describes the settings which apply inside the guest.
Field Type Description Value(s)
`cloudInit` VirtualMachineCloudInit Seed handed to the guest on first boot.
`agent` VirtualMachineAgent qemu-guest-agent settings.

Optional; omitting this section is equivalent to the default `{enabled: true}`.
Set `agent.enabled: false` to omit the channel entirely.
### cloudInit VirtualMachineCloudInit describes the NoCloud seed handed to the guest.
Field Type Description Value(s)
`library` string Name of the content library where Talos stores the generated NoCloud ISO.

Must name a content library with a nonempty identifier of at most 63 ASCII letters,
digits or hyphens. The library is declared separately by a `ContentLibraryConfig`.
`metaData` string Contents of the seed's `meta-data` file, carrying the guest's identity.

`instance-id` is what decides whether a boot is a reboot or a new instance. An unchanged
id means edits to `userData` are inert; a changed id re-runs provisioning, which
regenerates the SSH host keys in most images.

Must be valid YAML.
`userData` string Contents of the seed's `user-data` file, carrying what the operator wants done.

For a distro image this is a cloud-init document, usually starting with `#cloud-config`,
though a script or a MIME archive is equally valid -- it is not parsed here. For a Talos
guest this is the guest's own machine configuration.

Carries SSH keys, passwords and tokens in practice, and is redacted from the
configuration as read back over the API.
`networkConfig` string Contents of the seed's `network-config` file, carrying the guest's network settings.

Needed by guests which cannot configure themselves over DHCP. Unset leaves the guest to
its own defaults.

Must be valid YAML.
### agent VirtualMachineAgent describes the qemu-guest-agent settings for a virtual machine.
Field Type Description Value(s)
`enabled` bool Attach the qemu-guest-agent virtio-serial channel to the domain.

The host does not use the channel yet; this field is the plumbing that lets future
features (such as reporting guest addresses or requesting a graceful shutdown) talk to
a qemu-guest-agent process inside the guest.

Optional; defaults to enabled. Set to `false` to omit the channel entirely.
## video VirtualMachineVideo describes the virtual graphics device.
Field Type Description Value(s)
`model` string Video model: `vga` (default), `virtio`, `bochs`, or `cirrus`.
`vramMiB` uint32 Video RAM in MiB for `vga` and `bochs`. Zero leaves libvirt's default.
Nonzero values must be powers of two: 1–512 MiB for `vga`, 4–256 MiB for `bochs`.
Must be zero for `virtio` and `cirrus`, for which libvirt ignores this setting.
This does not set the guest's resolution or enable 3D acceleration.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.