VirtualMachineConfig

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.

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 <algorithm>:<hex>, 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.