Модуль community.proxmox.proxmox_kvm — управление виртуальными машинами Qemu(KVM) в кластере Proxmox VE

acpi

boolean

Укажите, следует ли включить или отключить ACPI.

Варианты:

• false
• true

agent

string

Укажите, следует ли включить или отключить QEMU Guest Agent.

api_host

string / обязательный

Укажите целевой хост кластера Proxmox VE.

Если значение не указано, используется переменная окружения PROXMOX_HOST.

api_password

string

Укажите пароль для аутентификации.

Если значение не указано, используется переменная окружения PROXMOX_PASSWORD.

api_port

integer

Укажите целевой порт кластера Proxmox VE.

Если значение не указано, используется переменная окружения PROXMOX_PORT.

api_timeout

integer

Ограничение времени для запросов к API Proxmox VE.

По умолчанию: 5

api_token_id

string

Укажите идентификатор токена.

Если значение не указано, используется переменная окружения PROXMOX_TOKEN_ID.

api_token_secret

string

Укажите секретный ключ токена.

Если значение не указано, используется переменная окружения PROXMOX_TOKEN_SECRET.

api_user

string / обязательный

Укажите пользователя для аутентификации.

Если значение не указано, используется переменная окружения PROXMOX_USER.

archive

string

Укажите путь к архиву для восстановления (вместо создания или клонирования виртуальной машины).

args

string

Передайте произвольные аргументы KVM.

Эта опция предназначена только для опытных пользователей!

audio

dictionary

Хеш/словарь аудиоустройств для виртуальной машины. audio={"key":"value", "key":"value"}.

Допустимые ключи: audio[n], где 0 ≤ n ≤ N.

Допустимые значения: device="ich9-intel-hda|intel-hda|AC97",driver="none|spice".

device — это либо ich9-intel-hda, либо intel-hda, либо AC97.

Параметр driver — это none или spice.

autostart

boolean

Укажите, следует ли автоматически перезапускать виртуальную машину после сбоя (в настоящее время игнорируется API PVE).

Варианты:

• false
• true

balloon

integer

Укажите объем оперативной памяти виртуальной машины в МБ.

Нулевое значение отключает драйвер balloon.

bios

string

Укажите реализацию BIOS.

Варианты:

• "seabios"
• "ovmf"

boot

string

Укажите порядок загрузки: с дискеты a, жесткого диска c, CD-ROM d или по сети n.

В новых версиях Proxmox VE укажите порядок загрузки, например order=scsi0;net0;hostpci0.

Можно объединить значения, чтобы задать порядок.

Для сетевой загрузки с PVE 8.3.5 необходимо установить rng0.

bootdisk

string

Включите загрузку с указанного диска. Формат (ide|sata|scsi|virtio)\d+.

ca_path

path

Путь к локальному сертификату, который будет использоваться для проверки TLS-соединений.

Игнорируется, если validate_certs=false.

cicustom

string

Cloud-init: укажите пользовательские файлы, которыми при запуске будут заменены автоматически созданные файлы.

cipassword

string

Cloud-init: пароль создаваемого пользователя по умолчанию.

citype

string

Cloud-init: указывает формат конфигурации cloud-init.

Значение по умолчанию зависит от настроенного типа операционной системы (ostype).

Для Linux используется формат nocloud, а для Windows — configdrive2.

Варианты:

• "nocloud"
• "configdrive2"

ciupgrade

boolean

Cloud-init: автоматически обновить пакеты после первой загрузки.

Варианты:

• false
• true

ciuser

string

Cloud-init: имя создаваемого пользователя по умолчанию.

clone

string

Имя виртуальной машины для клонирования. Если задано vmid, параметр clone может принимать произвольное значение, но он необходим для запуска клонирования.

cores

integer

Укажите количество ядер на сокет.

cpu

string

Укажите эмулируемый тип процессора.

cpulimit

integer

Укажите, будет ли ограничено использование процессора. Значение 0 означает отсутствие ограничения CPU.

Если в компьютере 2 процессора, общее время CPU равно «2».

cpuunits

integer

Укажите вес CPU для виртуальной машины.

Можно отключить настройку планировщика fair-scheduler, задав значение 0.

delete

string

Укажите список параметров, которые требуется удалить.

description

string

Укажите описание виртуальной машины. Используется только в веб-интерфейсе конфигурации.

Сохраняется в конфигурационном файле в виде комментария.

digest

string

Укажите, следует ли предотвращать изменения, если текущий конфигурационный файл имеет другой дайджест SHA1.

Это можно использовать для предотвращения параллельного изменения конфигурации.

efidisk0

dictionary

Укажите хеш/словарь параметров диска EFI.

Для использования необходимо задать bios=ovmf.

efitype

string

efitype указывает размер диска EFI.

2m позволяет создать диск EFI размером 2 МБ, которого достаточно для сохранения порядка загрузки и новых записей загрузки.

4m позволяет создать диск EFI размером 4 МБ, на котором также можно хранить ключи EFI для включения безопасной загрузки.

Варианты:

• "2m"
• "4m"

format

string

format — это формат данных файла-основы диска. Сведения о форматах, поддерживаемых используемым серверным хранилищем, см. в руководстве администратора Proxmox VE, в разделе «Хранилище Proxmox VE» (последняя версия доступна по адресу https://pve.proxmox.com/pve-docs/chapter-pvesm.html, таблицы 3–14).

pre_enrolled_keys

boolean

pre_enrolled_keys указывает, следует ли предварительно зарегистрировать ключи EFI для безопасной загрузки 1 в прошивке виртуальной машины при ее создании или нет (0).

Если задано значение 1, безопасная загрузка также будет включена по умолчанию при создании виртуальной машины.

Варианты:

• false
• true

storage

string

storage — это идентификатор хранилища, в котором следует создать диск.

force

boolean

Если задано значение true, разрешает принудительное управление питанием (остановку, сброс).

При использовании с state=stopped выполняется попытка корректного выключения; если виртуальная машина продолжает работать после timeout, питание будет принудительно отключено.

При использовании с state=restarted выполняется сброс (выключение и включение питания), а не корректная перезагрузка.

Варианты:

• false
• true

format

string

Формат данных файла-основы целевого диска.

Используется только при клонировании.

Для связанного клона используйте format=unspecified и full=false.

Сведения о форматах, поддерживаемых используемым серверным хранилищем, см. в руководстве администратора Proxmox VE, в разделе «Хранилище Proxmox VE» (последняя версия доступна по адресу https://pve.proxmox.com/pve-docs/chapter-pvesm.html, таблицы 3–14).

Если этот параметр не указан, это эквивалентно заданию значения unspecified.

Варианты:

• "cloop"
• "cow"
• "qcow"
• "qcow2"
• "qed"
• "raw"
• "vmdk"
• "unspecified"

freeze

boolean

Укажите, следует ли заморозить CPU при запуске PVE (для начала выполнения используйте команду монитора «c»).

Варианты:

• false
• true

full

boolean

Создать полную копию всех дисков. Это всегда выполняется при клонировании обычной виртуальной машины.

Для шаблонов виртуальных машин по умолчанию создается связанный клон.

Используется только при клонировании.

Варианты:

• false
• true ← (по умолчанию)

hookscript

string

Сценарий, который будет выполняться на различных этапах жизненного цикла контейнера.

hostpci

dictionary

Укажите хеш/словарь для сопоставления устройств PCI хоста с устройствами гостевой системы. hostpci='{"key":"value", "key":"value"}'.

Допустимые ключи: hostpci[n], где 0 ≤ n ≤ N.

Допустимые значения: "host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0"".

Параметр host отвечает за прямое подключение устройства PCI хоста. Синтаксис HOSTPCIID: bus:dev.func (шестнадцатеричные числа).

pcie=boolean default=0 Выберите шину PCI Express (требуется модель машины q35).

rombar=boolean default=1 Укажите, будет ли ПЗУ устройства отображаться в карте памяти гостевой системы.

x-vga=boolean default=0 Включите поддержку устройства vfio-vga.

/!\ Эта опция предоставляет прямой доступ к оборудованию хоста. Поэтому перенос таких машин становится невозможным — используйте ее с особой осторожностью.

hotplug

string

Выборочное включение функций горячего подключения.

Это список функций горячего подключения, разделенных запятыми: network, disk, cpu, memory и usb.

Значение 0 полностью отключает горячее подключение, а значение 1 является псевдонимом значения по умолчанию network,disk,usb.

hugepages

string

Включите или отключите память на основе hugepages.

Варианты:

• "any"
• "2"
• "1024"

ide

dictionary

Хеш/словарь томов, используемых в качестве жесткого диска IDE или CD-ROM.

Ключи должны иметь формат ide[n], где 0 ≤ n ≤ 3.

Значения — строки с параметрами, разделенными запятыми, в формате <storage>:<size>[,option=value]...

Примеры: "<storage>:10,format=qcow2" для диска или "<storage>:iso/debian.iso,media=cdrom" для CD-ROM.

Полный список доступных параметров см. в документации Proxmox VE (найдите «ide[n]:») по адресу https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options.

ipconfig

dictionary

Cloud-init: задайте конфигурацию IP.

Хеш/словарь конфигураций сетевых IP-адресов. ipconfig='{"key":"value", "key":"value"}'.

Допустимые ключи: ipconfig[n], где 0 ≤ n ≤ количество сетевых интерфейсов.

Допустимые значения: "[gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]".

Cloud-init: укажите IP-адреса и шлюзы для соответствующего интерфейса.

Для IP-адресов используется запись CIDR. Шлюзы необязательны, но должны находиться в той же подсети, что и указанный IP-адрес.

Для автоматического получения IP-адресов по DHCP можно использовать специальную строку dhcp; в этом случае шлюз явно указывать не следует.

Для IPv6 можно использовать специальную строку auto, чтобы включить автоматическую настройку без сохранения состояния.

Если cloud-init включен, но не указан ни IPv4-, ни IPv6-адрес, по умолчанию для IPv4 используется DHCP.

keyboard

string

Задает раскладку клавиатуры для VNC-сервера.

kvm

boolean

Включите или отключите аппаратную виртуализацию KVM.

Варианты:

• false
• true

localtime

boolean

Устанавливает местное время для часов реального времени.

По умолчанию параметр включен, если ostype указывает на ОС Microsoft.

Варианты:

• false
• true

lock

string

Заблокировать или разблокировать виртуальную машину.

Варианты:

• "migrate"
• "backup"
• "snapshot"
• "rollback"

machine

string

Указывает тип машины QEMU.

Тип => (pc|pc(-i440fx)?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?).

Позволяет задать параметры [[type=]<тип машины>] [,enable-s3=<1|0>] [,enable-s4=<1|0>] [,viommu=<intel|virtio>].

memory

integer

Объем памяти экземпляра в МБ.

migrate

boolean

Перенести ВМ на node, если она находится на другом узле.

Варианты:

• false ← (по умолчанию)
• true

migrate_downtime

integer

Задает максимально допустимое время простоя (в секундах) при миграции.

migrate_speed

integer

Задает максимальную скорость (в МБ/с) при миграции.

Значение 0 означает отсутствие ограничения.

name

string

Задает имя ВМ. Имя может быть неуникальным в пределах кластера.

Требуется только для state=present.

При state=present, если vmid не указан и в кластере существует ВМ с таким именем, изменения внесены не будут.

nameservers

list / elements=string

Cloud-init: IP-адреса DNS-серверов.

Если параметр не задан, используются настройки узла PVE.

net

dictionary

Словарь сетевых интерфейсов ВМ.

Ключи должны иметь вид net[n], где 0 ≤ n ≤ N.

Значения — строки с параметрами, разделенными запятыми, в формате [model=]<enum>[,option=value]...

Примеры: "virtio,bridge=vmbr0" для базового интерфейса или "virtio,bridge=vmbr0,firewall=1,rate=200,tag=10" для интерфейса VLAN с ограничением скорости и включенным межсетевым экраном.

macaddr=XX:XX:XX:XX:XX:XX должен быть уникальным MAC-адресом. Если он не указан, уникальный MAC-адрес генерируется автоматически.

Полный список доступных параметров см. в документации Proxmox VE (найдите «net[n]:») по адресу https://pve.proxmox.com/pve-docs/chapter-qm.html\#qm_options.

newid

integer

VMID клона. Используется только с clone.

Если newid не задан, следующий доступный идентификатор ВМ будет получен из ProxmoxAPI.

node

string

Узел Proxmox VE, на котором выполняется операция.

Требуется только для state=present.

Для всех остальных состояний значение определяется автоматически.

numa

dictionary

Словарь топологии NUMA. numa='{"key":"value", "key":"value"}'.

Допустимые ключи: numa[n], где 0 ≤ n ≤ N.

Допустимые значения: "cpu="<id[-id];...>",hostnodes="<id[-id];...>",memory="number",policy="(bind|interleave|preferred“”).

cpus процессоры, обращающиеся к этому узлу NUMA.

hostnodes узлы NUMA хоста, которые следует использовать.

memory объем памяти, предоставляемой этим узлом NUMA.

policy политика выделения NUMA.

numa_enabled

boolean

Включает NUMA.

Варианты:

• false
• true

onboot

boolean

Указывает, следует ли запускать ВМ при загрузке системы.

Варианты:

• false
• true

ostype

string

Задает гостевую операционную систему. Этот параметр используется для включения специальных оптимизаций и функций для конкретных операционных систем.

l26 — ядро Linux 2.6/3.X.

Варианты:

• "other"
• "wxp"
• "w2k"
• "w2k3"
• "w2k8"
• "wvista"
• "win7"
• "win8"
• "win10"
• "win11"
• "l24"
• "l26"
• "solaris"

parallel

dictionary

Словарь сопоставлений параллельных устройств хоста. parallel='{"key":"value", "key":"value"}'.

Допустимые ключи: parallel[n], где 0 ≤ n ≤ 2.

Допустимые значения: "/dev/parport\d+|/dev/usb/lp\d+".

pool

string

Добавить новую ВМ в указанный пул.

protection

boolean

Включить или отключить флаг защиты ВМ. Это разрешит или запретит удаление ВМ и дисков.

Варианты:

• false
• true

purge

boolean

Удалить VMID из конфигураций, например заданий резервного копирования и репликации, а также HA.

Используется с состоянием absent.

Варианты:

• false ← (по умолчанию)
• true

reboot

boolean

Разрешить перезагрузку. Если установлено значение true, ВМ завершает работу при перезагрузке.

Варианты:

• false
• true

revert

string

Отменить ожидающее изменение.

rng0

string

добавлено в community.proxmox 1.0.0

Источник случайных данных для устройства RNG, например /dev/urandom.

sata

dictionary

Словарь томов, используемых в качестве жесткого диска SATA или CD-ROM.

Ключи должны иметь вид sata[n], где 0 ≤ n ≤ 5.

Значения — строки с параметрами, разделенными запятыми, в формате <storage>:<size>[,option=value]...

Примеры: "<storage>:10,format=qcow2" для диска или "<storage>:iso/debian.iso,media=cdrom" для CD-ROM.

Полный список доступных параметров см. в документации Proxmox VE (найдите «sata[n]:») по адресу https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options.

scsi

dictionary

Словарь томов, используемых в качестве жесткого диска SCSI или CD-ROM.

Ключи должны иметь вид scsi[n], где 0 ≤ n ≤ 30.

Значения — строки с параметрами, разделенными запятыми, в формате <storage>:<size>[,option=value]...

Примеры: "<storage>:10,format=qcow2" для диска или "<storage>:iso/debian.iso,media=cdrom" для CD-ROM.

Полный список доступных параметров см. в документации Proxmox VE (найдите «scsi[n]:») по адресу https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options.

scsihw

string

Задает модель контроллера SCSI.

Варианты:

• "lsi"
• "lsi53c810"
• "virtio-scsi-pci"
• "virtio-scsi-single"
• "megasas"
• "pvscsi"

searchdomains

list / elements=string

Cloud-init: задает домены поиска DNS.

Если параметр не задан, используются настройки узла PVE.

serial

dictionary

Словарь последовательных устройств, создаваемых в ВМ. '{"key":"value", "key":"value"}'.

Допустимые ключи: serial[n](str; required), где 0 ≤ n ≤ 3.

Допустимые значения: (/dev/.+|socket).

/!\ При перенаправлении последовательного устройства хоста миграция таких машин становится невозможной — используйте этот параметр с особой осторожностью.

shares

integer

Задает объем общих ресурсов памяти для автоматического управления памятью (auto-ballooning). (0–50000).

Чем больше число, тем больше памяти получает эта ВМ.

Число рассчитывается относительно весовых коэффициентов всех остальных работающих ВМ.

Значение 0 отключает автоматическое управление памятью, то есть снимает ограничения.

skiplock

boolean

Игнорировать блокировки.

Использовать этот параметр может только root.

Варианты:

• false
• true

smbios

string

Задает поля SMBIOS типа 1.

Свойства SMBIOS, разделенные запятыми и при необходимости закодированные в Base64:

[base64=<1|0>] [,family=<Base64 encoded string>].

[,manufacturer=<Base64 encoded string>].

[,product=<Base64 encoded string>].

[,serial=<Base64 encoded string>].

[,sku=<Base64 encoded string>].

[,uuid=<UUID>].

[,version=<Base64 encoded string>].

snapname

string

Имя снимка. Используется только с clone.

sockets

integer

Задает количество сокетов ЦП (1–N).

sshkeys

string

Cloud-init: открытые ключи SSH, назначаемые пользователю по умолчанию.

Поддерживаются несколько ключей SSH, указанных в многострочном значении.

Каждый ключ должен располагаться на отдельной строке в формате ssh-key-type key-data [comment].

Чтобы указать несколько ключей, по одному на строку, используйте буквальный блочный скаляр YAML (|).

startdate

string

Задает начальную дату часов реального времени.

Допустимые форматы даты: 'now', '2016-09-25T16:01:21' или '2016-09-25'.

startup

string

Поведение при запуске и выключении. [[order=]\d+] [,up=\d+] [,down=\d+].

Order — неотрицательное число, задающее общий порядок запуска.

Выключение выполняется в обратном порядке.

state

string

Указывает желаемое состояние экземпляра.

Если задано current, будет получено текущее состояние ВМ. Его можно получить с помощью results.status.

stopped обеспечивает выключение ВМ с помощью штатного завершения работы.

Варианты:

• "present" ← (по умолчанию)
• "started"
• "absent"
• "stopped"
• "restarted"
• "current"
• "template"
• "paused"
• "hibernated"

storage

string

Целевое хранилище для полного клонирования.

При восстановлении из архива — целевое хранилище для всех дисков. Если параметр не указан, будет использоваться расположение хранилища, заданное в архиве.

tablet

boolean

Включает или отключает USB-устройство планшета.

Варианты:

• false
• true

tags

list / elements=string

Список тегов, применяемых к экземпляру ВМ.

Теги должны начинаться с [a-z0-9_], за которым может следовать любое количество символов из набора [a-z0-9_-+.].

Теги доступны только в Proxmox 6 и более поздних версиях.

target

string

Целевой узел. Допускается только в том случае, если исходная ВМ находится в общем хранилище.

Используется только с clone.

tdf

boolean

Включает или отключает коррекцию рассинхронизации времени.

Варианты:

• false
• true

template

boolean

Включает или отключает шаблон.

Варианты:

• false
• true

timeout

integer

Тайм-аут операций в секундах.

Если тайм-аут истекает при state=stopped и force=True, ВМ будет принудительно выключена.

Если тайм-аут истекает при state=stopped и force=False, задача завершится ошибкой.

По умолчанию: 30

tpmstate0

dictionary

Словарь параметров диска Trusted Platform Module.

Для установки Windows 11 требуется диск состояния TPM.

storage

string / обязательный

tpmstate0.storage — идентификатор хранилища, в котором будет создан диск.

version

string

Используемая версия TPM.

Варианты:

• "1.2"
• "2.0" ← (по умолчанию)

update

boolean

Если задано true, ВМ будет обновлена с новым значением.

Из-за особенностей работы API и по соображениям безопасности обновление следующих параметров отключено: net, virtio, ide, sata, scsi. Например, обновление net изменит MAC-адрес, а virtio каждый раз создает новый диск… Эту функцию безопасности можно отключить, задав update_unsafe значение true.

Обновление pool отключено. Для него требуется дополнительная конечная точка API, не поддерживаемая этим модулем.

Варианты:

• false ← (по умолчанию)
• true

update_unsafe

boolean

Если задано true, не применять ограничения к параметрам net, virtio, ide, sata, scsi, efidisk0 и tpmstate0. Используйте этот параметр с осторожностью: неправильная конфигурация может привести к безвозвратной потере данных (например, из-за пересоздания диска).

Варианты:

• false ← (по умолчанию)
• true

usb

dictionary

Словарь USB-устройств ВМ. usb='{"key":"value", "key":"value"}'.

Допустимые ключи: usb[n], где 0 ≤ n ≤ N.

Допустимые значения: host="value|spice",mapping="value",usb3="1|0".

В качестве хоста можно указать spice или идентификатор/порт USB.

Параметр mapping задает имя сопоставленного USB-устройства.

Параметр usb3 включает поддержку USB 3.

validate_certs

boolean

Проверять сертификаты TLS, используемые для подключения к API Proxmox VE.

В настоящее время значение по умолчанию — false; в community.proxmox 2.0.0 значение по умолчанию изменится на true.

Если параметр не указан, используется переменная окружения PROXMOX_VALIDATE_CERTS.

Варианты:

• false
• true

vcpus

integer

Задает количество виртуальных ЦП, подключаемых «на горячую».

vga

string

Выберите тип VGA. Для использования режимов высокого разрешения (>= 1280x1024x16) следует использовать параметр std или vmware.

Дополнительную информацию о допустимых значениях см. в руководстве администратора Proxmox VE, раздел «Виртуальные машины QEMU/KVM» (https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options).

virtio

dictionary

Хеш/словарь томов, используемых в качестве жёсткого диска или CD-ROM VIRTIO.

Ключи должны иметь вид virtio[n], где 0 ≤ n ≤ 15.

Значения представляют собой строки с параметрами, разделёнными запятыми, в формате <storage>:<size>[,option=value]...

Примеры: "<storage>:10,format=qcow2" для диска или "<storage>:iso/debian.iso,media=cdrom" для CD-ROM.

Полный список всех доступных параметров см. в документации Proxmox VE (найдите «virtio[n]:») по адресу https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options.

vmid

integer

Задаёт идентификатор экземпляра.

Если параметр не задан, из ProxmoxAPI будет получен следующий доступный идентификатор.

watchdog

string

Создаёт виртуальное аппаратное устройство watchdog.

with_local_disks

boolean

Разрешает перенос локальных дисков на следующий узел.

Варианты:

• false ← (по умолчанию)
• true

action_group

Группа действий: community.proxmox.proxmox

Используйте group/community.proxmox.proxmox в module_defaults, чтобы задать значения по умолчанию для этого модуля.

check_mode

Поддержка: нет

Может работать в режиме check_mode и возвращать прогноз статуса изменений, не изменяя целевой объект.

diff_mode

Поддержка: нет

В режиме diff будут возвращены сведения об изменениях (или о том, что, возможно, необходимо изменить в check_mode).

msg

string

Краткое сообщение.

Возвращается: всегда

Пример: "VM kropta with vmid = 110 is running"

status

string

Текущий статус виртуальной машины.

Возвращается: success, not clone, not absent, not update

Пример: "running"

vmid

integer

Идентификатор VM (vmid).

Возвращается: success

Пример: 115