mirrors/terraform-provider-proxmox
0
0
Fork 0
mirror of https://github.com/bpg/terraform-provider-proxmox.git synced 2025-06-30 02:31:10 +00:00
Code
3119194292
terraform-provider-proxmox/docs/resources/virtual_environment_vm.md
Pavel Boldyrev 3119194292
feat(vm): add RNG device support (#1774) 
* feat(vm): add RNG device  support

This commit adds support for configuring the Random Number Generator (RNG) device for virtual machines in both the VM resource and datasource. The implementation includes:

- New schema and model for RNG configuration
- Support for setting RNG source, max_bytes, and period
- Updated documentation for RNG configuration
- Test cases for RNG configuration
- Integration with VM creation, update, and read operations

---------

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
2025-02-16 23:53:40 -05:00

753 lines
36 KiB
Markdown
Executable File
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
layout: page
title: proxmox_virtual_environment_vm
parent: Resources
subcategory: Virtual Environment
---
# Resource: proxmox_virtual_environment_vm
Manages a virtual machine.
> This resource uses SSH access to the node. You might need to configure the [`ssh` option in the `provider` section](../index.md#node-ip-address-used-for-ssh-connection).
## Example Usage
```hcl
resource "proxmox_virtual_environment_vm" "ubuntu_vm" {
name = "terraform-provider-proxmox-ubuntu-vm"
description = "Managed by Terraform"
tags = ["terraform", "ubuntu"]
node_name = "first-node"
vm_id = 4321
agent {
# read 'Qemu guest agent' section, change to true only when ready
enabled = false
}
# if agent is not enabled, the VM may not be able to shutdown properly, and may need to be forced off
stop_on_destroy = true
startup {
order = "3"
up_delay = "60"
down_delay = "60"
}
cpu {
cores = 2
type = "x86-64-v2-AES" # recommended for modern CPUs
}
memory {
dedicated = 2048
floating = 2048 # set equal to dedicated to enable ballooning
}
disk {
datastore_id = "local-lvm"
file_id = proxmox_virtual_environment_download_file.latest_ubuntu_22_jammy_qcow2_img.id
interface = "scsi0"
}
initialization {
ip_config {
ipv4 {
address = "dhcp"
}
}
user_account {
keys = [trimspace(tls_private_key.ubuntu_vm_key.public_key_openssh)]
password = random_password.ubuntu_vm_password.result
username = "ubuntu"
}
user_data_file_id = proxmox_virtual_environment_file.cloud_config.id
}
network_device {
bridge = "vmbr0"
}
operating_system {
type = "l26"
}
tpm_state {
version = "v2.0"
}
serial_device {}
}
resource "proxmox_virtual_environment_download_file" "latest_ubuntu_22_jammy_qcow2_img" {
content_type = "iso"
datastore_id = "local"
node_name = "pve"
url = "https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img"
}
resource "random_password" "ubuntu_vm_password" {
length = 16
override_special = "_%@"
special = true
}
resource "tls_private_key" "ubuntu_vm_key" {
algorithm = "RSA"
rsa_bits = 2048
}
output "ubuntu_vm_password" {
value = random_password.ubuntu_vm_password.result
sensitive = true
}
output "ubuntu_vm_private_key" {
value = tls_private_key.ubuntu_vm_key.private_key_pem
sensitive = true
}
output "ubuntu_vm_public_key" {
value = tls_private_key.ubuntu_vm_key.public_key_openssh
}
```
## Argument Reference
- `acpi` - (Optional) Whether to enable ACPI (defaults to `true`).
- `agent` - (Optional) The QEMU agent configuration.
- `enabled` - (Optional) Whether to enable the QEMU agent (defaults
to `false`).
- `timeout` - (Optional) The maximum amount of time to wait for data from
the QEMU agent to become available ( defaults to `15m`).
- `trim` - (Optional) Whether to enable the FSTRIM feature in the QEMU agent
(defaults to `false`).
- `type` - (Optional) The QEMU agent interface type (defaults to `virtio`).
- `isa` - ISA Serial Port.
- `virtio` - VirtIO (paravirtualized).
- `audio_device` - (Optional) An audio device.
- `device` - (Optional) The device (defaults to `intel-hda`).
- `AC97` - Intel 82801AA AC97 Audio.
- `ich9-intel-hda` - Intel HD Audio Controller (ich9).
- `intel-hda` - Intel HD Audio.
- `driver` - (Optional) The driver (defaults to `spice`).
- `spice` - Spice.
- `enabled` - (Optional) Whether to enable the audio device (defaults
to `true`).
- `bios` - (Optional) The BIOS implementation (defaults to `seabios`).
- `ovmf` - OVMF (UEFI).
- `seabios` - SeaBIOS.
- `boot_order` - (Optional) Specify a list of devices to boot from in the order
they appear in the list (defaults to `[]`).
- `cdrom` - (Optional) The CD-ROM configuration.
- `enabled` - (Optional) Whether to enable the CD-ROM drive (defaults
to `false`). *Deprecated*. The attribute will be removed in the next version of the provider.
Set `file_id` to `none` to leave the CD-ROM drive empty.
- `file_id` - (Optional) A file ID for an ISO file (defaults to `cdrom` as
in the physical drive). Use `none` to leave the CD-ROM drive empty.
- `interface` - (Optional) A hardware interface to connect CD-ROM drive to,
must be `ideN` (defaults to `ide3`). Note that `q35` machine type only
supports `ide0` and `ide2`.
- `clone` - (Optional) The cloning configuration.
- `datastore_id` - (Optional) The identifier for the target datastore.
- `node_name` - (Optional) The name of the source node (leave blank, if
equal to the `node_name` argument).
- `retries` - (Optional) Number of retries in Proxmox for clone vm.
Sometimes Proxmox errors with timeout when creating multiple clones at
once.
- `vm_id` - (Required) The identifier for the source VM.
- `full` - (Optional) Full or linked clone (defaults to `true`).
- `cpu` - (Optional) The CPU configuration.
- `architecture` - (Optional) The CPU architecture (defaults to `x86_64`).
- `aarch64` - ARM (64 bit).
- `x86_64` - x86 (64-bit).
- `cores` - (Optional) The number of CPU cores (defaults to `1`).
- `flags` - (Optional) The CPU flags.
- `+aes`/`-aes` - Activate AES instruction set for HW acceleration.
- `+amd-no-ssb`/`-amd-no-ssb` - Notifies guest OS that host is not
vulnerable for Spectre on AMD CPUs.
- `+amd-ssbd`/`-amd-ssbd` - Improves Spectre mitigation performance with
AMD CPUs, best used with "virt-ssbd".
- `+hv-evmcs`/`-hv-evmcs` - Improve performance for nested
virtualization (only supported on Intel CPUs).
- `+hv-tlbflush`/`-hv-tlbflush` - Improve performance in overcommitted
Windows guests (may lead to guest BSOD on old CPUs).
- `+ibpb`/`-ibpb` - Allows improved Spectre mitigation on AMD CPUs.
- `+md-clear`/`-md-clear` - Required to let the guest OS know if MDS is
mitigated correctly.
- `+pcid`/`-pcid` - Meltdown fix cost reduction on Westmere, Sandy- and
Ivy Bridge Intel CPUs.
- `+pdpe1gb`/`-pdpe1gb` - Allows guest OS to use 1 GB size pages, if
host HW supports it.
- `+spec-ctrl`/`-spec-ctrl` - Allows improved Spectre mitigation with
Intel CPUs.
- `+ssbd`/`-ssbd` - Protection for "Speculative Store Bypass" for Intel
models.
- `+virt-ssbd`/`-virt-ssbd` - Basis for "Speculative Store Bypass"
protection for AMD models.
- `hotplugged` - (Optional) The number of hotplugged vCPUs (defaults
to `0`).
- `limit` - (Optional) Limit of CPU usage, `0...128`. (defaults to `0` -- no limit).
- `numa` - (Boolean) Enable/disable NUMA. (default to `false`)
- `sockets` - (Optional) The number of CPU sockets (defaults to `1`).
- `type` - (Optional) The emulated CPU type, it's recommended to
use `x86-64-v2-AES` (defaults to `qemu64`).
- `486` - Intel 486.
- `Broadwell`/`Broadwell-IBRS`/`Broadwell-noTSX`/`Broadwell-noTSX-IBRS` - Intel Core Processor (Broadwell, 2014).
- `Cascadelake-Server`/`Cascadelake-Server-noTSX`/`Cascadelake-Server-v2`/`Cascadelake-Server-v4`/`Cascadelake-Server-v5` - Intel Xeon 32xx/42xx/52xx/62xx/82xx/92xx (2019).
- `Conroe` - Intel Celeron_4x0 (Conroe/Merom Class Core 2, 2006).
- `Cooperlake`/`Cooperlake-v2`
- `EPYC`/`EPYC-IBPB`/`EPYC-Milan`/`EPYC-Rome`/`EPYC-Rome-v2`/`EPYC-v3` / `EPYC-v4` -
AMD EPYC Processor (2017).
- `Haswell`/`Haswell-IBRS`/`Haswell-noTSX`/`Haswell-noTSX-IBRS` - Intel
Core Processor (Haswell, 2013).
- `Icelake-Client`/`Icelake-Client-noTSX`
- `Icelake-Server`/`Icelake-Server-noTSX`/`Icelake-Server-v3`/
`Icelake-Server-v4`/`Icelake-Server-v5`/`Icelake-Server-v6`
- `IvyBridge`/`IvyBridge-IBRS` - Intel Xeon E3-12xx v2 (Ivy Bridge,
2012).
- `KnightsMill` - Intel Xeon Phi 72xx (2017).
- `Nehalem`/`Nehalem-IBRS` - Intel Core i7 9xx (Nehalem Class Core i7,
2008).
- `Opteron_G1` - AMD Opteron 240 (Gen 1 Class Opteron, 2004).
- `Opteron_G2` - AMD Opteron 22xx (Gen 2 Class Opteron, 2006).
- `Opteron_G3` - AMD Opteron 23xx (Gen 3 Class Opteron, 2009).
- `Opteron_G4` - AMD Opteron 62xx class CPU (2011).
- `Opteron_G5` - AMD Opteron 63xx class CPU (2012).
- `Penryn` - Intel Core 2 Duo P9xxx (Penryn Class Core 2, 2007).
- `SandyBridge`/`SandyBridge-IBRS` - Intel Xeon E312xx (Sandy Bridge,
2011).
- `SapphireRapids`
- `Skylake-Client`/`Skylake-Client-IBRS`/`Skylake-Client-noTSX-IBRS`/`Skylake-Client-v4` -
Intel Core Processor (Skylake, 2015).
- `Skylake-Server`/`Skylake-Server-IBRS`/`Skylake-Server-noTSX-IBRS`/`Skylake-Server-v4`/`Skylake-Server-v5` -
Intel Xeon Processor (Skylake, 2016).
- `Westmere`/`Westmere-IBRS` - Intel Westmere E56xx/L56xx/X56xx (
Nehalem-C, 2010).
- `athlon` - AMD Athlon.
- `core2duo` - Intel Core 2 Duo.
- `coreduo` - Intel Core Duo.
- `host` - Host pass-through.
- `kvm32`/`kvm64` - Common KVM processor (32 & 64 bit variants).
- `max` - Maximum amount of features from host CPU.
- `pentium` - Intel Pentium (1993).
- `pentium2` - Intel Pentium 2 (1997-1999).
- `pentium3` - Intel Pentium 3 (1999-2001).
- `phenom` - AMD Phenom (2010).
- `qemu32`/`qemu64` - QEMU Virtual CPU version 2.5+ (32 & 64 bit
variants).
- `x86-64-v2`/`x86-64-v2-AES`/`x86-64-v3`/`x86-64-v4`
See <https://en.wikipedia.org/wiki/X86-64#Microarchitecture_levels>
- `custom-<model>` - Custom CPU model. All `custom-<model>` values
should be defined in `/etc/pve/virtual-guest/cpu-models.conf` file.
- `units` - (Optional) The CPU units (defaults to `1024`).
- `affinity` - (Optional) The CPU cores that are used to run the VM’s vCPU. The
value is a list of CPU IDs, separated by commas. The CPU IDs are zero-based.
For example, `0,1,2,3` (which also can be shortened to `0-3`) means that the VM’s vCPUs are run on the first four
CPU cores. Setting `affinity` is only allowed for `root@pam` authenticated user.
- `description` - (Optional) The description.
- `disk` - (Optional) A disk (multiple blocks supported).
- `aio` - (Optional) The disk AIO mode (defaults to `io_uring`).
- `io_uring` - Use io_uring.
- `native` - Use native AIO. Should be used with to unbuffered, O_DIRECT, raw block storage only,
with the disk `cache` must be set to `none`. Raw block storage types include iSCSI, CEPH/RBD, and NVMe.
- `threads` - Use thread-based AIO.
- `backup` - (Optional) Whether the drive should be included when making backups (defaults to `true`).
- `cache` - (Optional) The cache type (defaults to `none`).
- `none` - No cache.
- `directsync` - Write to the host cache and wait for completion.
- `writethrough` - Write to the host cache, but write through to
the guest.
- `writeback` - Write to the host cache, but write back to the
guest when possible.
- `unsafe` - Write directly to the disk bypassing the host cache.
- `datastore_id` - (Optional) The identifier for the datastore to create
the disk in (defaults to `local-lvm`).
- `path_in_datastore` - (Optional) The in-datastore path to the disk image.
***Experimental.***Use to attach another VM's disks,
or (as root only) host's filesystem paths (`datastore_id` empty string).
See "*Example: Attached disks*".
- `discard` - (Optional) Whether to pass discard/trim requests to the
underlying storage. Supported values are `on`/`ignore` (defaults
to `ignore`).
- `file_format` - (Optional) The file format (defaults to `qcow2`).
- `qcow2` - QEMU Disk Image v2.
- `raw` - Raw Disk Image.
- `vmdk` - VMware Disk Image.
- `file_id` - (Optional) The file ID for a disk image. The ID format is
`<datastore_id>:<content_type>/<file_name>`, for example `local:iso/centos8.img`. Can be also taken from
`proxmox_virtual_environment_download_file` resource.
- `interface` - (Required) The disk interface for Proxmox, currently `scsi`,
`sata` and `virtio` interfaces are supported. Append the disk index at
the end, for example, `virtio0` for the first virtio disk, `virtio1` for
the second, etc.
- `iothread` - (Optional) Whether to use iothreads for this disk (defaults
to `false`).
- `replicate` - (Optional) Whether the drive should be considered for replication jobs (defaults to `true`).
- `serial` - (Optional) The serial number of the disk, up to 20 bytes long.
- `size` - (Optional) The disk size in gigabytes (defaults to `8`).
- `speed` - (Optional) The speed limits.
- `iops_read` - (Optional) The maximum read I/O in operations per second.
- `iops_read_burstable` - (Optional) The maximum unthrottled read I/O pool in operations per second.
- `iops_write` - (Optional) The maximum write I/O in operations per second.
- `iops_write_burstable` - (Optional) The maximum unthrottled write I/O pool in operations per second.
- `read` - (Optional) The maximum read speed in megabytes per second.
- `read_burstable` - (Optional) The maximum burstable read speed in
megabytes per second.
- `write` - (Optional) The maximum write speed in megabytes per second.
- `write_burstable` - (Optional) The maximum burstable write speed in
megabytes per second.
- `ssd` - (Optional) Whether to use an SSD emulation option for this disk (
defaults to `false`). Note that SSD emulation is not supported on VirtIO
Block drives.
- `efi_disk` - (Optional) The efi disk device (required if `bios` is set
to `ovmf`)
- `datastore_id` (Optional) The identifier for the datastore to create
the disk in (defaults to `local-lvm`).
- `file_format` (Optional) The file format (defaults to `raw`).
- `type` (Optional) Size and type of the OVMF EFI disk. `4m` is newer and
recommended, and required for Secure Boot. For backwards compatibility
use `2m`. Ignored for VMs with cpu.architecture=`aarch64` (defaults
to `2m`).
- `pre_enrolled_keys` (Optional) Use am EFI vars template with
distribution-specific and Microsoft Standard keys enrolled, if used with
EFI type=`4m`. Ignored for VMs with cpu.architecture=`aarch64` (defaults
to `false`).
- `tpm_state` - (Optional) The TPM state device.
- `datastore_id` (Optional) The identifier for the datastore to create
the disk in (defaults to `local-lvm`).
- `version` (Optional) TPM state device version. Can be `v1.2` or `v2.0`.
(defaults to `v2.0`).
- `hostpci` - (Optional) A host PCI device mapping (multiple blocks supported).
- `device` - (Required) The PCI device name for Proxmox, in form
of `hostpciX` where `X` is a sequential number from 0 to 15.
- `id` - (Optional) The PCI device ID. This parameter is not compatible
with `api_token` and requires the root `username` and `password`
configured in the proxmox provider. Use either this or `mapping`.
- `mapping` - (Optional) The resource mapping name of the device, for
example gpu. Use either this or `id`.
- `mdev` - (Optional) The mediated device ID to use.
- `pcie` - (Optional) Tells Proxmox to use a PCIe or PCI port. Some
guests/device combination require PCIe rather than PCI. PCIe is only
available for q35 machine types.
- `rombar` - (Optional) Makes the firmware ROM visible for the VM (defaults
to `true`).
- `rom_file` - (Optional) A path to a ROM file for the device to use. This
is a relative path under `/usr/share/kvm/`.
- `xvga` - (Optional) Marks the PCI(e) device as the primary GPU of the VM.
With this enabled the `vga` configuration argument will be ignored.
- `usb` - (Optional) A host USB device mapping (multiple blocks supported).
- `host` - (Optional) The Host USB device or port or the value `spice`. Use either this or `mapping`.
- `mapping` - (Optional) The cluster-wide resource mapping name of the device, for example "usbdevice". Use either this or `host`.
- `usb3` - (Optional) Makes the USB device a USB3 device for the VM
(defaults to `false`).
- `initialization` - (Optional) The cloud-init configuration.
- `datastore_id` - (Optional) The identifier for the datastore to create the
cloud-init disk in (defaults to `local-lvm`).
- `interface` - (Optional) The hardware interface to connect the cloud-init
image to. Must be one of `ide0..3`, `sata0..5`, `scsi0..30`. Will be
detected if the setting is missing but a cloud-init image is present,
otherwise defaults to `ide2`.
- `dns` - (Optional) The DNS configuration.
- `domain` - (Optional) The DNS search domain.
- `server` - (Optional) The DNS server. The `server` attribute is
deprecated and will be removed in a future release. Please use the
`servers` attribute instead.
- `servers` - (Optional) The list of DNS servers.
- `ip_config` - (Optional) The IP configuration (one block per network
device).
- `ipv4` - (Optional) The IPv4 configuration.
- `address` - (Optional) The IPv4 address in CIDR notation
(e.g. 192.168.2.2/24). Alternatively, set this to `dhcp` for
autodiscovery.
- `gateway` - (Optional) The IPv4 gateway (must be omitted
when `dhcp` is used as the address).
- `ipv6` - (Optional) The IPv6 configuration.
- `address` - (Optional) The IPv6 address in CIDR notation
(e.g. fd1c:000:0000::0000:000:7334/64). Alternatively, set this
to `dhcp` for autodiscovery.
- `gateway` - (Optional) The IPv6 gateway (must be omitted
when `dhcp` is used as the address).
- `user_account` - (Optional) The user account configuration (conflicts
with `user_data_file_id`).
- `keys` - (Optional) The SSH keys.
- `password` - (Optional) The SSH password.
- `username` - (Optional) The SSH username.
- `network_data_file_id` - (Optional) The identifier for a file containing
network configuration data passed to the VM via cloud-init (conflicts
with `ip_config`).
- `user_data_file_id` - (Optional) The identifier for a file containing
custom user data (conflicts with `user_account`).
- `vendor_data_file_id` - (Optional) The identifier for a file containing
all vendor data passed to the VM via cloud-init.
- `meta_data_file_id` - (Optional) The identifier for a file containing
all meta data passed to the VM via cloud-init.
- `keyboard_layout` - (Optional) The keyboard layout (defaults to `en-us`).
- `da` - Danish.
- `de` - German.
- `de-ch` - Swiss German.
- `en-gb` - British English.
- `en-us` - American English.
- `es` - Spanish.
- `fi` - Finnish.
- `fr` - French.
- `fr-be` - Belgian French.
- `fr-ca` - French Canadian.
- `fr-ch` - Swish French.
- `hu` - Hungarian.
- `is` - Icelandic.
- `it` - Italian.
- `ja` - Japanese.
- `lt` - Lithuanian.
- `mk` - Macedonian.
- `nl` - Dutch.
- `no` - Norwegian.
- `pl` - Polish.
- `pt` - Portuguese.
- `pt-br` - Brazilian Portuguese.
- `sl` - Slovenian.
- `sv` - Swedish.
- `tr` - Turkish.
- `kvm_arguments` - (Optional) Arbitrary arguments passed to kvm.
- `machine` - (Optional) The VM machine type (defaults to `pc`).
- `pc` - Standard PC (i440FX + PIIX, 1996).
- `q35` - Standard PC (Q35 + ICH9, 2009).
- `memory` - (Optional) The memory configuration.
- `dedicated` - (Optional) The dedicated memory in megabytes (defaults to `512`).
- `floating` - (Optional) The floating memory in megabytes. The default is `0`, which disables "ballooning device" for the VM.
Please note that Proxmox has ballooning enabled by default. To enable it, set `floating` to the same value as `dedicated`.
See [Proxmox documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_memory) section 10.2.6 for more information.
- `shared` - (Optional) The shared memory in megabytes (defaults to `0`).
- `hugepages` - (Optional) Enable/disable hugepages memory (defaults to disable).
- `2` - 2MB hugepages.
- `1024` - 1GB hugepages.
- `any` - Any hugepages.
- `keep_hugepages` - (Optional) Keep hugepages memory after the VM is stopped (defaults to `false`).
Settings `hugepages` and `keep_hugepages` are only allowed for `root@pam` authenticated user.
And required `cpu.numa` to be enabled.
- `numa` - (Optional) The NUMA configuration.
- `device` - (Required) The NUMA device name for Proxmox, in form
of `numaX` where `X` is a sequential number from 0 to 7.
- `cpus` - (Required) The CPU cores to assign to the NUMA node (format is `0-7;16-31`).
- `memory` - (Required) The memory in megabytes to assign to the NUMA node.
- `hostnodes` - (Optional) The NUMA host nodes.
- `policy` - (Optional) The NUMA policy (defaults to `preferred`).
- `interleave` - Interleave memory across nodes.
- `preferred` - Prefer the specified node.
- `bind` - Only use the specified node.
- `migrate` - (Optional) Migrate the VM on node change instead of re-creating
it (defaults to `false`).
- `name` - (Optional) The virtual machine name.
- `network_device` - (Optional) A network device (multiple blocks supported).
- `bridge` - (Optional) The name of the network bridge (defaults to `vmbr0`).
- `disconnected` - (Optional) Whether to disconnect the network device from the network (defaults to `false`).
- `enabled` - (Optional) Whether to enable the network device (defaults to `true`).
- `firewall` - (Optional) Whether this interface's firewall rules should be used (defaults to `false`).
- `mac_address` - (Optional) The MAC address.
- `model` - (Optional) The network device model (defaults to `virtio`).
- `e1000` - Intel E1000.
- `e1000e` - Intel E1000E.
- `rtl8139` - Realtek RTL8139.
- `virtio` - VirtIO (paravirtualized).
- `vmxnet3` - VMware vmxnet3.
- `mtu` - (Optional) Force MTU, for VirtIO only. Set to 1 to use the bridge MTU. Cannot be larger than the bridge MTU.
- `queues` - (Optional) The number of queues for VirtIO (1..64).
- `rate_limit` - (Optional) The rate limit in megabytes per second.
- `vlan_id` - (Optional) The VLAN identifier.
- `trunks` - (Optional) String containing a `;` separated list of VLAN trunks
("10;20;30"). Note that the VLAN-aware feature need to be enabled on the PVE
Linux Bridge to use trunks.
- `node_name` - (Required) The name of the node to assign the virtual machine
to.
- `on_boot` - (Optional) Specifies whether a VM will be started during system
boot. (defaults to `true`)
- `operating_system` - (Optional) The Operating System configuration.
- `type` - (Optional) The type (defaults to `other`).
- `l24` - Linux Kernel 2.4.
- `l26` - Linux Kernel 2.6 - 5.X.
- `other` - Unspecified OS.
- `solaris` - OpenIndiania, OpenSolaris og Solaris Kernel.
- `w2k` - Windows 2000.
- `w2k3` - Windows 2003.
- `w2k8` - Windows 2008.
- `win7` - Windows 7.
- `win8` - Windows 8, 2012 or 2012 R2.
- `win10` - Windows 10 or 2016.
- `win11` - Windows 11
- `wvista` - Windows Vista.
- `wxp` - Windows XP.
- `pool_id` - (Optional) The identifier for a pool to assign the virtual machine to.
- `protection` - (Optional) Sets the protection flag of the VM. This will disable the remove VM and remove disk operations (defaults to `false`).
- `reboot` - (Optional) Reboot the VM after initial creation. (defaults to `false`)
- `rng` - (Optional) The random number generator configuration. Can only be set by `root@pam.`
- `source` - The file on the host to gather entropy from. In most cases, `/dev/urandom` should be preferred over `/dev/random` to avoid entropy-starvation issues on the host.
- `max_bytes` - (Optional) Maximum bytes of entropy allowed to get injected into the guest every `period` milliseconds (defaults to `1024`). Prefer a lower value when using `/dev/random` as source.
- `period` - (Optional) Every `period` milliseconds the entropy-injection quota is reset, allowing the guest to retrieve another `max_bytes` of entropy (defaults to `1000`).
- `serial_device` - (Optional) A serial device (multiple blocks supported).
- `device` - (Optional) The device (defaults to `socket`).
- `/dev/*` - A host serial device.
- `socket` - A unix socket.
- `scsi_hardware` - (Optional) The SCSI hardware type (defaults to
`virtio-scsi-pci`).
- `lsi` - LSI Logic SAS1068E.
- `lsi53c810` - LSI Logic 53C810.
- `virtio-scsi-pci` - VirtIO SCSI.
- `virtio-scsi-single` - VirtIO SCSI (single queue).
- `megasas` - LSI Logic MegaRAID SAS.
- `pvscsi` - VMware Paravirtual SCSI.
- `smbios` - (Optional) The SMBIOS (type1) settings for the VM.
- `family`- (Optional) The family string.
- `manufacturer` - (Optional) The manufacturer.
- `product` - (Optional) The product ID.
- `serial` - (Optional) The serial number.
- `sku` - (Optional) The SKU number.
- `uuid` - (Optional) The UUID (defaults to randomly generated UUID).
- `version` - (Optional) The version.
- `started` - (Optional) Whether to start the virtual machine (defaults
to `true`).
- `startup` - (Optional) Defines startup and shutdown behavior of the VM.
- `order` - (Required) A non-negative number defining the general startup
order.
- `up_delay` - (Optional) A non-negative number defining the delay in
seconds before the next VM is started.
- `down_delay` - (Optional) A non-negative number defining the delay in
seconds before the next VM is shut down.
- `tablet_device` - (Optional) Whether to enable the USB tablet device (defaults
to `true`).
- `tags` - (Optional) A list of tags of the VM. This is only meta information (
defaults to `[]`). Note: Proxmox always sorts the VM tags. If the list in
template is not sorted, then Proxmox will always report a difference on the
resource. You may use the `ignore_changes` lifecycle meta-argument to ignore
changes to this attribute.
- `template` - (Optional) Whether to create a template (defaults to `false`).
- `stop_on_destroy` - (Optional) Whether to stop rather than shutdown on VM destroy (defaults to `false`)
- `timeout_clone` - (Optional) Timeout for cloning a VM in seconds (defaults to
1800).
- `timeout_create` - (Optional) Timeout for creating a VM in seconds (defaults to
1800).
- `timeout_migrate` - (Optional) Timeout for migrating the VM (defaults to
1800).
- `timeout_reboot` - (Optional) Timeout for rebooting a VM in seconds (defaults
to 1800).
- `timeout_shutdown_vm` - (Optional) Timeout for shutting down a VM in seconds (
defaults to 1800).
- `timeout_start_vm` - (Optional) Timeout for starting a VM in seconds (defaults
to 1800).
- `timeout_stop_vm` - (Optional) Timeout for stopping a VM in seconds (defaults
to 300).
- `vga` - (Optional) The VGA configuration.
- `memory` - (Optional) The VGA memory in megabytes (defaults to `16`).
- `type` - (Optional) The VGA type (defaults to `std`).
- `cirrus` - Cirrus (deprecated since QEMU 2.2).
- `none` - No VGA device.
- `qxl` - SPICE.
- `qxl2` - SPICE Dual Monitor.
- `qxl3` - SPICE Triple Monitor.
- `qxl4` - SPICE Quad Monitor.
- `serial0` - Serial Terminal 0.
- `serial1` - Serial Terminal 1.
- `serial2` - Serial Terminal 2.
- `serial3` - Serial Terminal 3.
- `std` - Standard VGA.
- `virtio` - VirtIO-GPU.
- `virtio-gl` - VirtIO-GPU with 3D acceleration (VirGL). VirGL support needs some extra libraries that aren’t installed by default. See the [Proxmox documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_virtual_machines_settings) section 10.2.8 for more information.
- `vmware` - VMware Compatible.
- `clipboard` - (Optional) Enable VNC clipboard by setting to `vnc`. See the [Proxmox documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_virtual_machines_settings) section 10.2.8 for more information.
- `vm_id` - (Optional) The VM identifier.
- `hook_script_file_id` - (Optional) The identifier for a file containing a hook script (needs to be executable, e.g. by using the `proxmox_virtual_environment_file.file_mode` attribute).
- `watchdog` - (Optional) The watchdog configuration. Once enabled (by a guest action), the watchdog must be periodically polled by an agent inside the guest or else the watchdog will reset the guest (or execute the respective action specified).
- `enabled` - (Optional) Whether the watchdog is enabled (defaults to `false`).
- `model` - (Optional) The watchdog type to emulate (defaults to `i6300esb`).
- `i6300esb` - Intel 6300ESB.
- `ib700` - iBase IB700.
- `action` - (Optional) The action to perform if after activation the guest fails to poll the watchdog in time (defaults to `none`).
- `debug`
- `none`
- `pause`
- `poweroff`
- `reset`
- `shutdown`
## Attribute Reference
- `ipv4_addresses` - The IPv4 addresses per network interface published by the
QEMU agent (empty list when `agent.enabled` is `false`)
- `ipv6_addresses` - The IPv6 addresses per network interface published by the
QEMU agent (empty list when `agent.enabled` is `false`)
- `mac_addresses` - The MAC addresses published by the QEMU agent with fallback
to the network device configuration, if the agent is disabled
- `network_interface_names` - The network interface names published by the QEMU
agent (empty list when `agent.enabled` is `false`)
## Qemu guest agent
Qemu-guest-agent is an application which can be installed inside guest VM, see
[Proxmox Wiki](https://pve.proxmox.com/wiki/Qemu-guest-agent) and [Proxmox
Documentation](https://pve.proxmox.com/pve-docs/pve-admin-guide.html#qm_qemu_agent)
For VM with `agent.enabled = false`, Proxmox uses ACPI for `Shutdown` and
`Reboot`, and `qemu-guest-agent` is not needed inside the VM. For some VMs,
the shutdown process may not work, causing the VM to be stuck on destroying.
Add `stop_on_destroy = true` to the VM configuration to stop the VM instead of
shutting it down.
Setting `agent.enabled = true` informs Proxmox that the guest agent is expected
to be *running* inside the VM. Proxmox then uses `qemu-guest-agent` instead of
ACPI to control the VM. If the agent is not running, Proxmox operations
`Shutdown` and `Reboot` time out and fail. The failing operation gets a lock on
the VM, and until the operation times out, other operations like `Stop` and
`Reboot` cannot be used.
Do **not** run VM with `agent.enabled = true`, unless the VM is configured to
automatically **start** `qemu-guest-agent` at some point.
"Monitor" tab in Proxmox GUI can be used to send low-level commands to `qemu`.
See the [documentation](https://www.qemu.org/docs/master/system/monitor.html).
Commands `system_powerdown` and `quit` have proven useful in shutting down VMs
with `agent.enabled = true` and no agent running.
Cloud images usually do not have `qemu-guest-agent` installed. It is possible to
install and *start* it using cloud-init, e.g. using custom `user_data_file_id`
file.
This provider requires `agent.enabled = true` to populate `ipv4_addresses`,
`ipv6_addresses` and `network_interface_names` output attributes.
Setting `agent.enabled = true` without running `qemu-guest-agent` in the VM will
also result in long timeouts when using the provider, both when creating VMs,
and when refreshing resources. The provider has no way to distinguish between
"qemu-guest-agent not installed" and "very long boot due to a disk check", it
trusts the user to set `agent.enabled` correctly and waits for
`qemu-guest-agent` to start.
## Important Notes
When cloning an existing virtual machine, whether it's a template or not, the
resource will only detect changes to the arguments which are not set to their
default values.
Furthermore, when cloning from one node to a different one, the behavior changes
depening on the datastores of the source VM. If at least one non-shared
datastore is used, the VM is first cloned to the source node before being
migrated to the target node. This circumvents a limitation in the Proxmox clone
API.
**Note:** Because the migration step after the clone tries to preserve the used
datastores by their name, it may fail if a datastore used in the source VM is
not available on the target node (e.g. `local-lvm` is used on the source node in
the VM but no `local-lvm` datastore is available on the target node). In this
case, it is recommended to set the `datastore_id` argument in the `clone` block
to force the migration step to migrate all disks to a specific datastore on the
target node. If you need certain disks to be on specific datastores, set
the `datastore_id` argument of the disks in the `disks` block to move the disks
to the correct datastore after the cloning and migrating succeeded.
## Example: Attached disks
In this example VM `data_vm` holds two data disks, and is not used as an actual VM,
but only as a container for the disks.
It does not have any OS installation, it is never started.
VM `data_user_vm` attaches those disks as `scsi1` and `scsi2`.
**VM `data_user_vm` can be *re-created/replaced* without losing data stored on disks
owned by `data_vm`.**
~> **Experimental** Please test your configuration first in an environment where you can tolerate the potential data loss.
~> Do *not* simultaneously run more than one VM using same disk. For most filesystems,
attaching one disk to multiple VM will cause errors or even data corruption.
~> Do *not* move or resize `data_vm` disks.
(Resource `data_user_vm` should reject attempts to move or resize non-owned disks.)
```hcl
resource "proxmox_virtual_environment_vm" "data_vm" {
node_name = "first-node"
started = false
on_boot = false
disk {
datastore_id = "local-zfs"
file_format = "raw"
interface = "scsi0"
size = 1
}
disk {
datastore_id = "local-zfs"
file_format = "raw"
interface = "scsi1"
size = 4
}
}
resource "proxmox_virtual_environment_vm" "data_user_vm" {
# boot disk
disk {
datastore_id = "local-zfs"
file_format = "raw"
interface = "scsi0"
size = 8
}
# attached disks from data_vm
dynamic "disk" {
for_each = { for idx, val in proxmox_virtual_environment_vm.data_vm.disk : idx => val }
iterator = data_disk
content {
datastore_id = data_disk.value["datastore_id"]
path_in_datastore = data_disk.value["path_in_datastore"]
file_format = data_disk.value["file_format"]
size = data_disk.value["size"]
# assign from scsi1 and up
interface = "scsi${data_disk.key + 1}"
}
}
# remainder of VM configuration
...
}
````
## Example: Disk pass-through
You can attach another physical disk from the PVE host to a VM.
This is done by setting the `path_in_datastore` to the path of the block device on the host.
~> **Experimental** Please test your configuration first in an environment where you can tolerate the potential data loss.
~> Do *not* attach the same disk to more than one VM as it may cause data corruption.
```hcl
resource "proxmox_virtual_environment_vm" "test_vm" {
...
# boot disk
disk {
...
}
# attached disk
disk {
datastore_id = ""
path_in_datastore = "/dev/path/to/block/device"
file_format = "raw"
}
...
}
```
## Import
Instances can be imported using the `node_name` and the `vm_id`, e.g.,
```bash
terraform import proxmox_virtual_environment_vm.ubuntu_vm first-node/4321
```
View Git Blame Copy Permalink