community.general.proxmox 模块 – Proxmox VE 集群中实例的管理

注意

此模块是 community.general 集合 (版本 10.1.0) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.general。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。

要在 playbook 中使用它，请指定：community.general.proxmox。

概要

• 允许您在 Proxmox VE 集群中创建/删除/停止实例。

• 该模块会自动检测容器化类型（对于 PVE 4 为 lxc，对于较旧版本为 openvz）。

• 从 community.general 4.0.0 开始，不再有默认值。

要求

执行此模块的主机需要以下要求。

• proxmoxer

• requests

参数

参数	注释
api_host 字符串 / 必需	指定 Proxmox VE 集群的目标主机。
api_password 字符串	指定用于身份验证的密码。 您可以使用 PROXMOX_PASSWORD 环境变量。
api_port 整数 在 community.general 9.1.0 中添加	指定 Proxmox VE 集群的目标端口。 如果未指定，则使用 PROXMOX_PORT 环境变量。
api_token_id 字符串 在 community.general 1.3.0 中添加	指定令牌 ID。 需要 proxmoxer>=1.1.0才能工作。
api_token_secret 字符串 在 community.general 1.3.0 中添加	指定令牌密钥。 需要 proxmoxer>=1.1.0才能工作。
api_user 字符串 / 必需	指定用于身份验证的用户。
clone 整数 在 community.general 4.3.0 中添加	要克隆的容器的 ID。 description、hostname 和 pool 如果未指定，将从克隆的容器中复制。 创建的克隆类型由 clone_type 参数定义。 此操作符仅支持使用 LXC 容器化的 Proxmox 集群 (PVE 版本 >= 4)。
clone_type 字符串 在 community.general 4.3.0 中添加	创建的克隆类型。 full 创建完整克隆，并且必须指定 storage。 linked 创建链接克隆，并且克隆的容器必须是模板容器。 opportunistic 如果克隆的容器是模板容器，则创建链接克隆；如果不是，则创建完整克隆。可以指定 storage，如果没有，它将回退到默认值。 选项 "full" "linked" "opportunistic" ← (默认)
cores 整数	指定每个套接字的核心数。
cpus 整数	为实例分配的 CPU 数量
cpuunits 整数	虚拟机的 CPU 权重
description 字符串 在 community.general 0.2.0 中添加	指定容器的描述。仅在配置 Web 界面上使用。 这将作为注释保存在配置文件中。
磁盘 字符串	此选项以前描述为“实例的硬盘大小（GB）”，但现在允许使用多种格式来描述 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。 此选项与 storage 和 disk_volume 互斥。
disk_volume 字典 在 community.general 9.2.0 中添加	指定 rootfs 磁盘的哈希/字典。 有关完整描述，请参阅 https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points。 此选项与 storage 和 disk 互斥。
host_path 路径	disk_volume.host_path 定义要在 PVE 主机上用于 rootfs 的绑定或设备路径。 与 disk_volume.storage、disk_volume.volume 和 disk_volume.size 互斥。
选项 字典	disk_volume.options 是额外选项的字典。 任何给定选项的值必须是字符串，例如 "1"。
大小 整数	disk_volume.size 是要使用的存储大小。 大小以 GB 为单位。 仅当定义了 disk_volume.storage 且与 disk_volume.host_path 互斥时才需要。
存储 字符串	disk_volume.storage 是要用于 rootfs 的存储标识符。 与 disk_volume.host_path 互斥。
卷 字符串	disk_volume.volume 是现有卷的名称。 如果未定义，模块将检查是否存在卷。如果不存在，则将创建一个新卷。 如果已定义，则该名称下必须存在卷。 仅当定义了 disk_volume.storage 且与 disk_volume.host_path 互斥时才需要。
特性 列表 / 元素=字符串 在 community.general 2.0.0 中添加	指定要启用的特性列表。有关有效选项，请参阅 https://pve.proxmox.com/wiki/Linux_Container#pct_options。 某些特性需要使用特权容器。
强制 布尔值	强制操作。 只能与状态 present、stopped、restarted 一起使用。 使用 state=present 强制选项允许覆盖现有容器。 使用状态 stopped、restarted 允许强制停止实例。 选项 false ← (默认) 真
hookscript 字符串 在 community.general 0.2.0 中添加	将在容器生命周期的各个步骤中执行的脚本。
主机名 字符串	实例主机名 仅对于 state=present 必须。 如果未传递 vmid，则必须唯一。
ip_address 字符串	指定将分配给容器的地址。
内存 整数	实例的内存大小（MB）。
mount_volumes 列表 / 元素=字典 在 community.general 9.2.0 中添加	为容器指定附加挂载点（单独的磁盘）。作为定义挂载点的哈希/字典。 有关完整描述，请参阅 https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points。 此选项与 mounts 互斥。
host_path 路径	mount_volumes[].host_path 定义要在 PVE 主机上用于 rootfs 的绑定或设备路径。 与 mount_volumes[].storage、mount_volumes[].volume 和 mount_volumes[].size 互斥。
ID 字符串 / 必需	mount_volumes[].id 是挂载点的标识符，写为 mp[n]。
挂载点 路径 / 必需	mount_volumes[].mountpoint 是卷的挂载点。
选项 字典	mount_volumes[].options 是额外选项的字典。 任何给定选项的值必须是字符串，例如 "1"。
大小 整数	mount_volumes[].size 是要使用的存储大小。 大小以 GB 为单位。 仅当定义了 mount_volumes[].storage 且与 mount_volumes[].host_path 互斥时才需要。
存储 字符串	mount_volumes[].storage 是要使用的存储标识符。 与 mount_volumes[].host_path 互斥。
卷 字符串	mount_volumes[].volume 是现有卷的名称。 如果未定义，模块将检查是否存在卷。如果不存在，则将创建一个新卷。 如果已定义，则该名称下必须存在卷。 仅当定义了 mount_volumes[].storage 且与 mount_volumes[].host_path 互斥时才需要。
挂载点 字典	为容器指定附加挂载点（单独的磁盘）。作为哈希/字典，以字符串定义挂载点。 此选项与 mount_volumes 互斥。
nameserver 字符串	设置容器的 DNS 服务器 IP 地址。
netif 字典	指定容器的网络接口。作为定义接口的哈希/字典。
节点 字符串	在其上操作的 Proxmox VE 节点。 仅对于 state=present 必须。 对于所有其他状态，它将自动发现。
onboot 布尔值	指定是否在系统启动时启动虚拟机。 选项 false 真
ostemplate 字符串	创建虚拟机的模板。 仅对于 state=present 必须。
ostype 字符串 在 community.general 8.1.0 中添加	指定 LXC 容器的 ostype。 如果设置为 auto，则在实例创建时不会提供 ostype。 选项 "auto" ← (默认) "debian" "devuan" "ubuntu" "centos" "fedora" "opensuse" "archlinux" "alpine" "gentoo" "nixos" "unmanaged"
密码 字符串	实例 root 密码
池 字符串	将新的虚拟机添加到指定的池。
pubkey 字符串	要添加到 /root/.ssh/authorized_keys 的公钥。这是在 Proxmox 4.2 中添加的，在早期版本中会被忽略。
purge 布尔值 在 community.general 2.3.0 中添加。	从所有相关配置中删除容器。 例如备份作业、复制作业或高可用性。 相关的 ACL 和防火墙条目将始终被删除。 与 state=absent 一起使用。 选项 false ← (默认) 真
searchdomain 字符串	设置容器的 DNS 搜索域。
startup 列表 / 元素=字符串 在 community.general 8.5.0 中添加。	指定容器的启动顺序。 使用 order=#，其中 # 是一个非负数，用于定义通用的启动顺序。关机按相反顺序进行。 使用 up=#，其中 # 以秒为单位，指定在启动下一个虚拟机之前要等待的延迟。 使用 down=#，其中 # 以秒为单位，指定在停止下一个虚拟机之前要等待的延迟。
state 字符串	指示实例所需的状态。 template 在 community.general 8.1.0 中添加。 选项 "present" ← (默认) "started" "absent" "stopped" "restarted" "template"
存储 字符串	目标存储。 此选项与 disk 和 disk_volume 互斥。 默认： "local"
swap 整数	实例的交换内存大小（MB）。
tags 列表 / 元素=字符串 在 community.general 6.2.0 中添加。	要应用于容器的标签列表。 标签必须以 [a-z0-9_] 开头，后跟零个或多个以下字符 [a-z0-9_-+.]。 标签仅在 Proxmox 7+ 中可用。
timeout 整数	操作超时。 默认： 30
timezone 字符串 在 community.general 7.1.0 中添加。	容器使用的时区，接受诸如 Europe/Paris 之类的值。 特殊值 host 配置 Proxmox 主机使用的相同时区。
unprivileged 布尔值	指示容器是否应为非特权容器。 在 community.general 7.0.0 中默认值更改为 true。之前是 false。 选项 false true ← (默认)
update 布尔值 在 community.general 8.1.0 中添加	如果为 true，则容器将使用新值更新。 选项 false ← (默认) 真
validate_certs 布尔值	如果为 false，则不会验证 SSL 证书。 这仅应在使用自签名证书的个人控制站点上使用。 选项 false ← (默认) 真
vmid 整数	指定实例 ID。 如果未设置，则将从 ProxmoxAPI 获取下一个可用 ID。

属性

属性	支持	描述
action_group	动作组： community.general.proxmox 在 community.general 9.0.0 中添加。	在 module_defaults 中使用 group/community.general.proxmox 为此模块设置默认值。
check_mode	支持：不支持	可以在 check_mode 下运行，并在不修改目标的情况下返回更改状态预测。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

另请参见

另请参见

community.general.proxmox_vm_info

检索有关一个或多个 Proxmox VE 虚拟机的信息。

示例

- name: Create new container with minimal options
  community.general.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.general.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.general.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.general.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.general.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.general.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.general.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.general.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.general.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.general.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 8GB
  community.general.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 8GB using mount_volumes
  community.general.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.general.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.general.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.general.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.general.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.general.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.general.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.general.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.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started
    timeout: 90

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

- name: Stop container with force
  community.general.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.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: restarted

- name: Convert container to template
  community.general.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.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: template
    force: true

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

作者

• Sergei Antipov (@UnderGreen)

资源链接

• 问题跟踪
• 代码仓库
• 寻求帮助
• 提交错误报告
• 请求功能
• 通信