Модуль community.proxmox.proxmox — управление экземплярами в кластере Proxmox VE

Примечание

Этот модуль входит в коллекцию community.proxmox (версия 1.6.0).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Для установки используйте: ansible-galaxy collection install community.proxmox. Для использования этого модуля необходимы дополнительные требования. Подробнее см. в разделе Требования.

Чтобы использовать его в плейбуке, укажите: community.proxmox.proxmox.

Краткое описание
Требования
Параметры
Атрибуты
См. также
Примеры

Краткое описание

Позволяет создавать, удалять и останавливать экземпляры в кластере Proxmox VE.
Модуль автоматически определяет тип контейнеризации (lxc для PVE 4, openvz для более ранних версий).

Требования

Следующие требования необходимы на узле, на котором выполняется этот модуль.

proxmoxer >= 2.0
requests

Параметры

Параметр	Комментарии
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` не указана, используется её значение.
ca_path path	Путь к локальному сертификату, который будет использоваться для проверки TLS-соединений. Игнорируется, если `validate_certs=false`.
clone integer	Идентификатор клонируемого контейнера. Если не указаны, из клонированного контейнера будут скопированы `description`, `hostname` и `pool`. Тип создаваемого клона определяется параметром `clone_type`. Эта операция поддерживается только в кластерах Proxmox, использующих контейнеризацию LXC (версия PVE >= 4).
clone_type string	Тип создаваемого клона. `full` создаёт полный клон, необходимо указать `storage`. `linked` создаёт связанный клон; клонируемый контейнер должен быть шаблоном. `opportunistic` создаёт связанный клон, если клонируемый контейнер является шаблоном, и полный клон в противном случае. Можно указать `storage`; если он не указан, будет использовано значение по умолчанию. Варианты: `"full"` `"linked"` `"opportunistic"` ← (по умолчанию)
cores integer	Укажите количество ядер на сокет.
cpus integer	Количество процессоров, выделенных для экземпляра.
cpuunits integer	Вес ЦП для виртуальной машины.
delete list / elements=string	Список параметров, которые требуется удалить.
description string	Укажите описание контейнера. Используется только в веб-интерфейсе конфигурации. Сохраняется в виде комментария в файле конфигурации.
disk string	Ранее этот параметр описывался как «размер жёсткого диска экземпляра в ГиБ», однако допускается несколько форматов описания точки монтирования LXC. В старых версиях Proxmox для указания размера можно использовать числовое значение с параметром `storage`, чтобы автоматически выбрать хранилище для выделения ресурсов; в новых версиях требуется синтаксис `<STORAGE>:<SIZE>`. Дополнительные параметры можно задать, используя комбинацию следующих пар ключ-значение в виде списка, разделённого запятыми: `[volume=]<volume> [,acl=<1\|0>] [,mountoptions=<opt[;opt...] [,quota=<1\|0>] [,replicate=<1\|0>] [,ro=<1\|0>] [,shared=<1\|0>] [,size=<DiskSize>]`. Полное описание см. на странице https://pve.proxmox.com/wiki/Linux_Container. Этот параметр несовместим с `disk_volume`.
disk_volume dictionary	Укажите хеш/словарь диска `rootfs`. Полное описание см. на странице https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points. Этот параметр несовместим с `storage` и `disk`.
host_path path	`disk_volume.host_path` задаёт путь к bind-монтированию или устройству на хосте PVE, используемый для `rootfs`. Несовместим с `disk_volume.storage`, `disk_volume.volume` и `disk_volume.size`.
options dictionary	`disk_volume.options` — словарь дополнительных параметров. Значение любого параметра должно быть строкой, например `"1"`.
size integer	`disk_volume.size` — размер используемого хранилища. Размер указывается в ГиБ. Требуется только при наличии `disk_volume.storage` и несовместим с `disk_volume.host_path`.
storage string	`disk_volume.storage` — идентификатор хранилища, используемого для `rootfs`. Несовместим с `disk_volume.host_path`.
volume string	`disk_volume.volume` — имя существующего тома. Если параметр не задан, модуль проверит, существует ли том. Если нет, будет создан новый том. Если параметр задан, том должен существовать под этим именем. Требуется только при наличии `disk_volume.storage` и несовместим с `disk_volume.host_path`.
features list / elements=string	Задаёт список функций, которые необходимо включить. Допустимые параметры см. на странице https://pve.proxmox.com/wiki/Linux_Container#pct_options. Для некоторых функций требуется привилегированный контейнер.
force boolean	Принудительное выполнение операций. Можно использовать только со следующими состояниями: `absent`, `present`, `stopped` и `restarted`. Для `state=present` параметр force позволяет перезаписать существующий контейнер. Для `state=absent` параметр force принудительно остановит контейнер перед удалением. Для состояний `stopped`, `restarted` позволяет принудительно остановить экземпляр. При указании `force` параметр `update` указывать нельзя. Варианты: `false` ← (по умолчанию) `true`
hookscript string	Скрипт, который будет выполняться на различных этапах жизненного цикла контейнера.
hostname string	Имя хоста экземпляра. Требуется только для `state=present`. Должно быть уникальным, если vmid не указан.
ip_address string	Задаёт адрес, который будет назначен контейнеру.
memory integer	Объём памяти экземпляра в МБ.
mount_volumes list / elements=dictionary	Укажите дополнительные точки монтирования (отдельные диски) для контейнера в виде хеша/словаря, определяющего точки монтирования. Полное описание см. на странице https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points. Этот параметр несовместим с `mounts`.
host_path path	`mount_volumes[].host_path` задаёт путь к bind-монтированию или устройству на хосте PVE, используемый для `rootfs`. Несовместим с `mount_volumes[].storage`, `mount_volumes[].volume` и `mount_volumes[].size`.
id string / обязательный	`mount_volumes[].id` — идентификатор точки монтирования, записываемый в формате `mp[n]`.
mountpoint path / обязательный	`mount_volumes[].mountpoint` — точка монтирования тома.
options dictionary	`mount_volumes[].options` — словарь дополнительных параметров. Значение любого параметра должно быть строкой, например `"1"`.
size integer	`mount_volumes[].size` — размер используемого хранилища. Размер указывается в ГиБ. Требуется только при наличии `mount_volumes[].storage` и несовместим с `mount_volumes[].host_path`.
storage string	`mount_volumes[].storage` — идентификатор используемого хранилища. Несовместим с `mount_volumes[].host_path`.
volume string	`mount_volumes[].volume` — имя существующего тома. Если параметр не задан, модуль проверит, существует ли том. Если нет, будет создан новый том. Если параметр задан, том должен существовать под этим именем. Требуется только при наличии `mount_volumes[].storage` и несовместим с `mount_volumes[].host_path`.
mounts dictionary	Задаёт дополнительные точки монтирования (отдельные диски) для контейнера в виде хеша/словаря, определяющего точки монтирования в виде строк. Этот параметр несовместим с `mount_volumes`.
nameserver string	Задаёт IP-адрес DNS-сервера для контейнера.
netif dictionary	Задаёт сетевые интерфейсы контейнера в виде хеша/словаря, определяющего интерфейсы.
node string	Узел Proxmox VE, на котором выполняются операции. Требуется только для `state=present`. Для всех остальных состояний узел будет определён автоматически.
onboot boolean	Указывает, будет ли виртуальная машина запускаться при загрузке системы. Варианты: `false` `true`
ostemplate string	Шаблон для создания виртуальной машины. Требуется только для `state=present`.
ostype string	Задаёт `ostype` контейнера LXC. Если установлено значение `auto`, при создании экземпляра `ostype` предоставляться не будет. Варианты: `"auto"` ← (по умолчанию) `"debian"` `"devuan"` `"ubuntu"` `"centos"` `"fedora"` `"opensuse"` `"archlinux"` `"alpine"` `"gentoo"` `"nixos"` `"unmanaged"`
password string	Пароль root экземпляра.
pool string	Добавить новую виртуальную машину в указанный пул.
pubkey string	Открытый ключ для добавления в /root/.ssh/authorized_keys. Эта возможность появилась в Proxmox 4.2; в более ранних версиях она игнорируется.
purge boolean	Удалить контейнер из всех связанных конфигураций. Например, из заданий резервного копирования, заданий репликации или конфигурации HA. Связанные записи ACL и брандмауэра удаляются всегда. Используется с `state=absent`. Варианты: `false` ← (по умолчанию) `true`
searchdomain string	Задаёт домен поиска DNS для контейнера.
startup list / elements=string	Задаёт порядок запуска контейнеров. Используйте `order=#`, где `#` — неотрицательное число, чтобы задать общий порядок запуска. Завершение работы выполняется в обратном порядке. Используйте `up=#`, где `#` задаётся в секундах, чтобы указать задержку перед запуском следующей виртуальной машины. Используйте `down=#`, где `#` задаётся в секундах, чтобы указать задержку перед остановкой следующей виртуальной машины.
state string	Укажите требуемое состояние экземпляра. Варианты: `"present"` ← (по умолчанию) `"started"` `"absent"` `"stopped"` `"restarted"` `"template"`
storage string	Целевое хранилище. Этот параметр несовместим с `disk_volume` и `mount_volumes`. По умолчанию: `"local"`
swap integer	Размер swap-памяти экземпляра в МБ.
tags list / elements=string	Список тегов, назначаемых контейнеру. Теги должны начинаться с `[a-z0-9_]`, за которым может следовать ноль или более символов из следующего набора: `[a-z0-9_-+.]`. Теги доступны только в Proxmox 7 и более поздних версиях.
timeout integer	Время ожидания операций. По умолчанию: `30`

timezone string	Часовой пояс контейнера; принимаются такие значения, как `Europe/Paris`. Специальное значение `host` задаёт тот же часовой пояс, что используется на узле Proxmox.
unprivileged boolean	Указывает, должен ли контейнер быть непривилегированным. Варианты: `false` `true` ← (по умолчанию)
update boolean	Если `true`, контейнер будет обновлён с новыми значениями. Это происходит только в том случае, если не указаны `state=present`, `force=false` и `clone`. Если `false`, обновление выполнено не будет. Значение по умолчанию изменилось с `false` на `true` в community.proxmox 1.0.0. Варианты: `false` `true` ← (по умолчанию)
validate_certs boolean	Проверять сертификаты TLS, используемые для подключения к API Proxmox VE. В настоящее время значение по умолчанию — `false`; в community.proxmox 2.0.0 оно изменится на `true`. Если параметр не указан, используется переменная окружения `PROXMOX_VALIDATE_CERTS`. Варианты: `false` `true`
vmid integer	Задаёт идентификатор экземпляра. Если параметр не задан, из ProxmoxAPI будет получен следующий доступный идентификатор.

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группа действий: community.proxmox.proxmox	Используйте `group/community.proxmox.proxmox` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: нет	Может работать в режиме `check_mode` и возвращать прогноз изменения статуса без изменения целевого объекта.
diff_mode	Поддержка: нет	В режиме diff возвращает сведения об изменениях (или о возможных изменениях в `check_mode`).

См. также

community.proxmox.proxmox_vm_info: Получение информации об одной или нескольких виртуальных машинах Proxmox VE.

Примеры

- name: Create new container with minimal options
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

- name: Create new container with minimal options specifying disk storage location and size
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    disk: 'local-lvm:20'

- name: Create new container with minimal options specifying disk storage location and size via disk_volume
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    disk_volume:
      storage: local
      size: 20

- name: Create new container with hookscript and description
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    hookscript: 'local:snippets/vm_hook.sh'
    description: created with ansible

- name: Create new container automatically selecting the next available vmid.
  community.proxmox.proxmox:
    node: 'uk-mc02'
    api_user: 'root@pam'
    api_password: '1q2w3e'
    api_host: 'node1'
    password: '123456'
    hostname: 'example.org'
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

- name: Create new container with minimal options with force(it will rewrite existing container)
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    force: true

- name: Create new container with minimal options use environment PROXMOX_PASSWORD variable(you should export it before)
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

- name: Create new container with minimal options defining network interface with dhcp
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    netif:
      net0: "name=eth0,ip=dhcp,ip6=dhcp,bridge=vmbr0"

- name: Create new container with minimal options defining network interface with static ip
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    netif:
      net0: "name=eth0,gw=192.168.0.1,ip=192.168.0.2/24,bridge=vmbr0"

- name: Create new container with more options defining network interface with static ip4 and ip6 with vlan-tag and mtu
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    netif:
      net0: "name=eth0,gw=192.168.0.1,ip=192.168.0.2/24,ip6=fe80::1227/64,gw6=fe80::1,bridge=vmbr0,firewall=1,tag=934,mtu=1500"

- name: Create new container with minimal options defining a mount with 8GiB
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    mounts:
      mp0: "local:8,mp=/mnt/test/"

- name: Create new container with minimal options defining a mount with 8GiB using mount_volumes
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    mount_volumes:
      - id: mp0
        storage: local
        size: 8
        mountpoint: /mnt/test

- name: Create new container with minimal options defining a cpu core limit
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    cores: 2

- name: Create new container with minimal options and same timezone as proxmox host
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    timezone: host

- name: Create a new container with nesting enabled and allows the use of CIFS/NFS inside the container.
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    features:
      - nesting=1
      - mount=cifs,nfs

- name: >
    Create a linked clone of the template container with id 100. The newly created container with be a
    linked clone, because no storage parameter is defined
  community.proxmox.proxmox:
    vmid: 201
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    clone: 100
    hostname: clone.example.org

- name: Create a full clone of the container with id 100
  community.proxmox.proxmox:
    vmid: 201
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    clone: 100
    hostname: clone.example.org
    storage: local

- name: Update container configuration
  community.proxmox.proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    netif:
      net0: "name=eth0,gw=192.168.0.1,ip=192.168.0.3/24,bridge=vmbr0"
    update: true

- name: Start container
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started

- name: >
    Start container with mount. You should enter a 90-second timeout because servers
    with additional disks take longer to boot
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started
    timeout: 90

- name: Stop container
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: stopped

- name: Stop container with force
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    force: true
    state: stopped

- name: Restart container(stopped or mounted container you can't restart)
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: restarted

- name: Convert container to template
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: template

- name: Convert container to template (stop container if running)
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: template
    force: true

- name: Remove container
  community.proxmox.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: absent

- name: >-
    Create a new container automatically selecting the next available vmid
    using a non-root API token
  community.proxmox.proxmox:
    node: 'uk-mc02'
    api_token_id: 'svc-tkn'
    api_token_secret: '81c09a2a-0359-4ba1-8153-8cb3cd02509b'
    api_user: 'remoteapiuser@pam'
    api_host: 'node1'
    password: '123456'
    hostname: 'example.org'
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

- name: >-
    Create a new container automatically selecting the next available vmid
    and providing a public key for the root account the Ansible host can use
    to connect to the new container
  community.proxmox.proxmox:
    node: 'uk-mc02'
    api_user: 'root@pam'
    api_password: '1q2w3e'
    api_host: 'node1'
    password: '123456'
    hostname: 'example.org'
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    pubkey: 'ssh-ed25519 AAAAC3NzaC1...hBWA ansibleuser@ansiblehost'

Авторы

Sergei Antipov (@UnderGreen)

Ссылки на коллекцию

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/proxmox/proxmox_module.html