Модуль community.general.proxmox_kvm — Управление виртуальными машинами Qemu(KVM) в кластере Proxmox VE
Примечание
Этот модуль является частью коллекции community.general (версия 9.5.0).
Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не включена в ansible-core. Чтобы проверить установку, выполните ansible-galaxy collection list.
Для установки используйте: ansible-galaxy collection install community.general. Для использования этого модуля необходимы дополнительные требования. Подробности см. в разделе Требования.
Для использования в книге задач укажите: community.general.proxmox_kvm.
Описание
- Позволяет создавать/удалять/останавливать виртуальные машины Qemu(KVM) в кластере Proxmox VE.
- Начиная с версии community.general 4.0.0, значения по умолчанию больше не используются, см.
proxmox_default_behavior.
Требования
Ниже перечислены требования к хосту, на котором будет выполняться этот модуль.
- proxmoxer
- requests
Параметры
Параметр | Комментарии |
|---|---|
acpi логическое | Указать, должен ли быть включён/выключен ACPI. Этот параметр не имеет значения по умолчанию, если Варианты:
|
agent строка | Указать, должен ли быть включён/выключен QEMU Guest Agent. Начиная с community.general 5.5.0, это также может быть строка вместо логического значения. Это позволяет указать значения, такие как |
api_host строка / обязательно | Указать целевой хост кластера Proxmox VE. |
api_password строка | Указать пароль для аутентификации. Можно использовать переменную окружения |
api_port целое число добавлен в community.general 9.1.0 | Указать целевой порт кластера Proxmox VE. Использует переменную окружения |
api_token_id строка добавлен в community.general 1.3.0 | Указать идентификатор токена. Требуется |
api_token_secret строка добавлен в community.general 1.3.0 | Указать секрет токена. Требуется |
api_user строка / обязательно | Указать пользователя для аутентификации. |
archive строка добавлен в community.general 6.5.0 | Указать путь к архиву для восстановления (вместо создания или клонирования ВМ). |
args строка | Передать произвольные аргументы в kvm. Этот параметр предназначен только для экспертов! Если |
autostart логическое | Указать, должна ли ВМ автоматически перезапускаться после сбоя (в настоящее время игнорируется в API PVE). Этот параметр не имеет значения по умолчанию, если Варианты:
|
balloon целое число | Указать количество оперативной памяти для ВМ в МБ. Использование нуля отключает драйвер balloon. Этот параметр не имеет значения по умолчанию, если |
bios строка | Указать реализацию BIOS. Варианты:
|
boot строка | Указать порядок загрузки: с дискеты Для более новых версий Proxmox VE используйте порядок загрузки, такой как Можно комбинировать для установки порядка. Этот параметр не имеет значения по умолчанию, если |
bootdisk строка | Включить загрузку с указанного диска. Формат |
cicustom строка добавлен в community.general 1.3.0 | cloud-init: Указать пользовательские файлы для замены автоматически созданных файлов при запуске. |
cipassword строка добавлен в community.general 1.3.0 | cloud-init: пароль пользователя по умолчанию для создания. |
citype строка добавлен в community.general 1.3.0 | cloud-init: Указывает формат конфигурации cloud-init. Значение по умолчанию зависит от настроенного типа операционной системы ( Мы используем формат Варианты:
|
ciuser строка добавлен в community.general 1.3.0 | cloud-init: имя пользователя по умолчанию для создания. |
clone строка |
cores integer | Указать количество ядер на сокет. Этот параметр не имеет значения по умолчанию, если |
cpu string | Указать тип эмулируемого процессора. Этот параметр не имеет значения по умолчанию, если |
cpulimit integer | Указать, будет ли ограничена загрузка процессора. Значение 0 означает отсутствие ограничения. Если компьютер имеет 2 процессора, общее время работы процессора составляет «2». |
cpuunits integer | Указать весовой коэффициент процессора для виртуальной машины. Вы можете отключить конфигурацию fair-scheduler, установив это значение в 0 Этот параметр не имеет значения по умолчанию, если |
delete string | Указать список параметров, которые необходимо удалить. |
description string | Указать описание для виртуальной машины. Используется только в веб-интерфейсе конфигурации. Сохраняется как комментарий в файле конфигурации. |
digest string | Указать, нужно ли предотвратить изменения, если текущий файл конфигурации имеет другой SHA1 дайджест. Это можно использовать для предотвращения одновременных изменений. |
efidisk0 dictionary добавлено в community.general 4.5.0 | Указать хеш/словарь параметров диска EFI. Требуется, чтобы |
|
efitype string |
Варианты:
|
|
format string |
|
|
pre_enrolled_keys boolean |
Если установлено Варианты:
|
|
storage string |
|
force boolean | Разрешить принудительное завершение работы ВМ. Можно использовать с состояниями Этот параметр не имеет значения по умолчанию, если Требуется параметр Варианты:
|
format string | Формат данных файла резервной копии целевого диска. Используется только с клонированием Используйте Обратитесь к руководству администратора Proxmox VE, раздел Proxmox VE Storage (см. https://pve.proxmox.com/pve-docs/chapter-pvesm.html для последней версии, таблицы с 3 по 14), чтобы узнать, какой формат поддерживается предоставленным хранилищем. Этот параметр не имеет значения по умолчанию, если Варианты:
|
freeze boolean | Указать, нужно ли заморозить процессор PVE при запуске (использовать команду монитора «c» для начала выполнения). Варианты:
|
full boolean | Создать полную копию всех дисков. Это всегда делается при клонировании обычной виртуальной машины. Для шаблонов виртуальных машин мы пытаемся создать связанный клон по умолчанию. Используется только с клонированием. Варианты:
|
hookscript string добавлено в community.general 8.1.0 | Скрипт, который будет выполняться на разных этапах жизненного цикла контейнеров. |
hostpci dictionary | Укажите хэш/словарь сопоставления устройств хоста pci с гостевыми. Допустимые ключи - Допустимые значения - Параметр
/!\ Этот параметр позволяет прямой доступ к оборудованию хоста. Таким образом, миграция таких машин больше невозможна - используйте с осторожностью. |
hotplug string | Выборочно включить функции горячей замены. Это список функций горячей замены, разделенных запятыми Значение 0 полностью отключает горячую замену, а значение 1 является псевдонимом для значения по умолчанию |
hugepages string | Включить/отключить память hugepages. Варианты:
|
ide dictionary | Хэш/словарь томов, используемых в качестве жесткого диска IDE или CD-ROM. Допустимые ключи - Допустимые значения -
|
ipconfig dictionary добавлено в community.general 1.3.0 | cloud-init: Настройка IP-конфигурации. Хэш/словарь IP-конфигураций сети. Допустимые ключи - Допустимые значения - cloud-init: Укажите IP-адреса и шлюзы для соответствующего интерфейса. IP-адреса используют нотацию CIDR, шлюзы необязательны, но должны находиться в той же подсети, что и указанный IP-адрес. Специальная строка «dhcp» может использоваться для IP-адресов для использования DHCP, в этом случае явно указывать шлюз не следует. Для IPv6 специальная строка «auto» может использоваться для использования бесстатной автоматической конфигурации. Если cloud-init включен и не указан ни IPv4, ни IPv6 адрес, по умолчанию используется dhcp для IPv4. |
keyboard string | Устанавливает раскладку клавиатуры для VNC-сервера. |
kvm boolean | Включить/отключить аппаратную виртуализацию KVM. Этот параметр не имеет значения по умолчанию, если только Варианты:
|
localtime boolean | Устанавливает часы реального времени на локальное время. Включено по умолчанию, если ostype указывает на операционную систему Microsoft. Варианты:
|
lock string | Блокировать/разблокировать ВМ. Варианты:
|
machine string | Указывает тип машины Qemu. Тип => |
memory integer | Размер памяти в МБ для экземпляра. Этот параметр не имеет значения по умолчанию, если только |
migrate boolean добавлено в community.general 7.0.0 | |
migrate_downtime integer | Устанавливает максимально допустимое время простоя (в секундах) для миграций. |
migrate_speed integer | Устанавливает максимальную скорость (в МБ/с) для миграций. Значение 0 означает отсутствие ограничения. |
name string | Указывает имя ВМ. Имя может быть не уникальным в кластере. Требуется только для С |
nameservers list / elements=string добавлено в community.general 1.3.0 | cloud-init: IP-адрес(а) DNS-сервера. Если не указано, используются настройки хоста PVE. |
net dictionary | Хэш/словарь сетевых интерфейсов для виртуальной машины. Допустимые ключи - Допустимые значения - Модель - одна из
Параметр Параметр Если мост не указан, мы создаем сетевое устройство kvm «user» (NATed), которое предоставляет службы DHCP и DNS. |
newid integer | VMID для клона. Используется только с клонированием. Если newid не задан, следующий доступный идентификатор VM будет получен из ProxmoxAPI. |
node string | Узел Proxmox VE, на котором нужно выполнить операцию. Требуется только для Для всех остальных состояний он будет автоматически обнаружен. |
numa dictionary | Хэш/словари топологии NUMA. Допустимые ключи - Допустимые значения -
|
numa_enabled boolean | Включает NUMA. Варианты:
|
onboot boolean | Указывает, будет ли виртуальная машина запущена во время загрузки системы. Этот параметр не имеет значения по умолчанию, если только Варианты:
|
ostype string | Указывает гостевую операционную систему. Это используется для включения специальной оптимизации/функций для конкретных операционных систем. l26 - это ядро Linux 2.6/3.X. Этот параметр не имеет значения по умолчанию, если только Варианты:
|
parallel dictionary | Хэш/словарь отображения параллельных устройств хоста. Допустимые ключи - (parallel[n]), где 0 ≤ n ≤ 2. Допустимые значения - |
pool string | Добавить новую виртуальную машину в указанный пул. |
protection boolean | Включить/отключить флаг защиты виртуальной машины. Это включит/отключит операции удаления виртуальной машины и удаления дисков. Варианты:
|
proxmox_default_behavior string добавлено в community.general 1.3.0 | Начиная с community.general 4.0.0, различные параметры больше не имеют значений по умолчанию. Эти значения по умолчанию вызывали проблемы, когда пользователи ожидали другого поведения от Proxmox по умолчанию или заполняли параметры, которые вызывали проблемы при установке. - Значение Варианты:
|
reboot boolean | Разрешить перезагрузку. Если установлено в Варианты:
|
revert string | Отменить ожидающее изменение. |
sata dictionary | Хэш/словарь томов, используемых в качестве жесткого диска SATA или CD-ROM. Допустимые ключи - Допустимые значения -
|
scsi dictionary | Хэш/словарь томов, используемых в качестве SCSI-жесткого диска или CD-ROM. Допустимые ключи - Допустимые значения -
|
scsihw string | Указывает модель контроллера SCSI. Варианты:
|
searchdomains list / elements=string добавлено в community.general 1.3.0 | cloud-init: Устанавливает домен(ы) поиска DNS. Если не задано, используются настройки хоста PVE. |
serial dictionary | Хэш/словарь последовательных устройств для создания внутри виртуальной машины. Допустимые ключи - serial[n](str; требуется), где 0 ≤ n ≤ 3. Допустимые значения - /!\ Если вы передаете последовательное устройство хоста, миграция таких машин становится невозможной - используйте с осторожностью. |
integer | Устанавливает количество долей памяти для автоматического баллонинга (0 - 50000). Чем больше число, тем больше памяти получает эта виртуальная машина. Число относительно весов всех других запущенных виртуальных машин. Использование 0 отключает автоматический баллонинг, это означает отсутствие ограничения. |
skiplock boolean | Игнорировать блокировки Только root может использовать этот параметр. Варианты:
|
smbios string | Указывает поля SMBIOS типа 1. Разделенные запятыми, закодированные в Base64 (необязательно) свойства SMBIOS:
|
snapname string | Имя снимка. Используется только с клонированием. |
sockets integer | Задает количество сокетов CPU (1 - N). Этот параметр не имеет значения по умолчанию, если |
sshkeys string добавлено в community.general 1.3.0 | cloud-init: SSH-ключ для назначения пользователю по умолчанию. НЕ ТЕСТИРОВАНО с несколькими ключами, но многострочное значение должно работать. |
startdate string | Устанавливает начальную дату часов реального времени. Допустимый формат даты: |
startup string | Поведение при запуске и выключении. Порядок - неотрицательное число, определяющее общий порядок запуска. Выключение выполняется в обратном порядке. |
state string | Указывает желаемое состояние экземпляра. Если
Варианты:
|
storage string | Целевое хранилище для полного клонирования. |
tablet boolean | Включает/отключает устройство USB-планшета. Этот параметр не имеет значения по умолчанию, если Варианты:
|
tags list / elements=string добавлено в community.general 2.3.0 | Список тегов для применения к экземпляру виртуальной машины. Теги должны начинаться с Теги доступны только в Proxmox 6+. |
target string | Целевой узел. Допускается только в случае, если исходная виртуальная машина находится на общем хранилище. Используется только с клонированием |
tdf boolean | Включает/отключает исправление сдвига времени. Варианты:
|
template boolean | Включает/выключает шаблон. Этот параметр не имеет значения по умолчанию, если Варианты:
|
timeout integer | Таймаут для операций. При использовании с Значение по умолчанию: |
tpmstate0 dictionary добавлен в community.general 7.1.0 | Хэш/словарь параметров для диска Модуля защищенной платформы. Диск состояния TPM необходим для установки Windows 11. |
|
storage string / обязательно |
|
|
version string |
Версия TPM для использования. Варианты:
|
update boolean | Если Из-за работы API и соображений безопасности обновление следующих параметров отключено: Обновление Варианты:
|
update_unsafe boolean добавлен в community.general 8.4.0 | Если Варианты:
|
usb dictionary добавлен в community.general 9.0.0 | Хэш/словарь USB-устройств для виртуальной машины. Разрешенные ключи — Разрешенные значения — host — это Параметр Параметр |
validate_certs boolean | Если Это следует использовать только на контролируемых вами сайтах, использующих самозаверяющие сертификаты. Варианты:
|
vcpus integer | Устанавливает количество подключаемых vCPU. |
vga string | Выбор типа VGA. Если вы хотите использовать режимы высокого разрешения (≥ 1280x1024x16), используйте параметр ‘std’ или ‘vmware’. Этот параметр не имеет значения по умолчанию, если Варианты:
|
virtio dictionary | Хэш/словарь тома, используемого в качестве жесткого диска VIRTIO. Разрешенные ключи — Разрешенные значения —
|
vmid integer | Указывает идентификатор экземпляра. Если не задано, следующий доступный идентификатор будет получен из ProxmoxAPI. |
watchdog string | Создаёт виртуальное устройство сигнализации. |
Атрибуты
Атрибут | Поддержка | Описание |
|---|---|---|
action_group | Группа действий: community.general.proxmox добавлено в community.general 9.0.0 | Используйте |
check_mode | Поддержка: отсутствует | Может работать в режиме |
diff_mode | Поддержка: отсутствует | В режиме сравнения вернёт подробную информацию о внесённых изменениях (или, возможно, изменениях, которые необходимо внести в |
См. также
См. также
- community.general.proxmox_vm_info
-
Получение информации об одной или нескольких виртуальных машинах Proxmox VE.
Примеры
- name: Create new VM with minimal options
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
- name: Create a VM from archive (backup)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
archive: backup-storage:backup/vm/140/2023-03-08T06:41:23Z
name: spynal
- name: Create new VM with minimal options and given vmid
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
vmid: 100
- name: Create new VM with two network interface options
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
net:
net0: 'virtio,bridge=vmbr1,rate=200'
net1: 'e1000,bridge=vmbr2'
- name: Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
net:
net0: 'virtio,bridge=vmbr1,rate=200'
virtio:
virtio0: 'VMs_LVM:10'
virtio1: 'VMs:2,format=qcow2'
virtio2: 'VMs:5,format=raw'
cores: 4
vcpus: 2
- name: Create VM with 1 10GB SATA disk and an EFI disk, with Secure Boot disabled by default
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
sata:
sata0: 'VMs_LVM:10,format=raw'
bios: ovmf
efidisk0:
storage: VMs_LVM_thin
format: raw
efitype: 4m
pre_enrolled_keys: false
- name: Create VM with 1 10GB SATA disk and an EFI disk, with Secure Boot enabled by default
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
sata:
sata0: 'VMs_LVM:10,format=raw'
bios: ovmf
efidisk0:
storage: VMs_LVM
format: raw
efitype: 4m
pre_enrolled_keys: 1
- name: >
Clone VM with only source VM name.
The VM source is spynal.
The target VM name is zavala
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
clone: spynal
name: zavala
node: sabrewulf
storage: VMs
format: qcow2
timeout: 500
- name: >
Create linked clone VM with only source VM name.
The VM source is spynal.
The target VM name is zavala
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
clone: spynal
name: zavala
node: sabrewulf
storage: VMs
full: false
format: unspecified
timeout: 500
- name: Clone VM with source vmid and target newid and raw format
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
clone: arbitrary_name
vmid: 108
newid: 152
name: zavala
node: sabrewulf
storage: LVM_STO
format: raw
timeout: 300
- name: Create new VM and lock it for snapshot
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
lock: snapshot
- name: Create new VM and set protection to disable the remove VM and remove disk operations
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
protection: true
- name: Create new VM using cloud-init with a username and password
community.general.proxmox_kvm:
node: sabrewulf
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
ide:
ide2: 'local:cloudinit,format=qcow2'
ciuser: mylinuxuser
cipassword: supersecret
searchdomains: 'mydomain.internal'
nameservers: 1.1.1.1
net:
net0: 'virtio,bridge=vmbr1,tag=77'
ipconfig:
ipconfig0: 'ip=192.168.1.1/24,gw=192.168.1.1'
- name: Create new VM using Cloud-Init with an ssh key
community.general.proxmox_kvm:
node: sabrewulf
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
ide:
ide2: 'local:cloudinit,format=qcow2'
sshkeys: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+'
searchdomains: 'mydomain.internal'
nameservers:
- '1.1.1.1'
- '8.8.8.8'
net:
net0: 'virtio,bridge=vmbr1,tag=77'
ipconfig:
ipconfig0: 'ip=192.168.1.1/24'
- name: Start VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: started
- name: Stop VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: stopped
- name: Stop VM with force
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: stopped
force: true
- name: Restart VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: restarted
- name: Convert VM to template
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: template
- name: Convert VM to template (stop VM if running)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: template
force: true
- name: Remove VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: absent
- name: Get VM current state
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: current
- name: Update VM configuration
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
cores: 8
memory: 16384
update: true
- name: Update VM configuration (incl. unsafe options)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
cores: 8
memory: 16384
net:
net0: virtio,bridge=vmbr1
update: true
update_unsafe: true
- name: Delete QEMU parameters
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
delete: 'args,template,cpulimit'
- name: Revert a pending change
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
revert: 'template,cpulimit'
- name: Migrate VM on second node
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf-2
migrate: true
- name: Add hookscript to existing VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
vmid: 999
node: sabrewulf
hookscript: local:snippets/hookscript.pl
update: true
Возвращаемые значения
Общие возвращаемые значения документированы здесь, следующие поля уникальны для данного модуля:
Ключ | Описание |
|---|---|
msg строка | Краткое сообщение Возвращается: всегда Пример: |
status строка | Текущее состояние виртуальной машины. Возвращается: успех, не клон, не отсутствует, не обновление Пример: |
vmid целое число | vmid ВМ. Возвращается: успех Пример: |
Ссылки на коллекцию
© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_kvm_module.html