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

注意

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

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

要安装它，请使用：ansible-galaxy collection install community.general。您需要进一步的要求才能使用此模块，请参阅 要求 以了解详细信息。

要在剧本中使用它，请指定：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 容器化（PVE 版本 >= 4）的 Proxmox 集群。
clone_type 字符串 在 community.general 4.3.0 中添加	创建的克隆的类型。 full 创建完整克隆，并且必须指定 storage。 linked 创建链接克隆，并且克隆的容器必须是模板容器。 opportunistic 如果克隆的容器是模板容器，则创建链接克隆，否则创建完整克隆。可以指定 storage，如果未指定，则将回退到默认值。 选择 "full" "linked" "opportunistic" ← (默认)
cores 整数	指定每个插槽的内核数。
cpus 整数	为实例分配的 CPU 数量
cpuunits 整数	VM 的 CPU 权重
description 字符串 在 community.general 0.2.0 中添加	指定容器的描述。仅在配置 Web 界面上使用。 这作为注释保存在配置文件中。
disk 字符串	此选项以前描述为“实例的硬盘大小（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 互斥。
options 字典	disk_volume.options 是额外的选项字典。 任何给定选项的值必须是字符串，例如 "1"。
size 整数	disk_volume.size 是要使用的存储大小。 大小以 GB 为单位给出。 仅当定义了 disk_volume.storage 时才需要，并且与 disk_volume.host_path 互斥。
storage 字符串	disk_volume.storage 是要用于 rootfs 的存储标识符。 与 disk_volume.host_path 互斥。
volume 字符串	disk_volume.volume 是现有卷的名称。 如果未定义，模块将检查是否存在。如果不存在，将创建一个新卷。 如果已定义，则该卷必须以该名称存在。 仅当定义了 disk_volume.storage 时才需要，并且与 disk_volume.host_path 互斥。
features 列表 / 元素=字符串 在 community.general 2.0.0 中添加	指定要启用的功能列表。有关有效选项，请参见 https://pve.proxmox.com/wiki/Linux_Container#pct_options。 某些功能需要使用特权容器。
force 布尔值	强制执行操作。 只能与状态 present、stopped、restarted 一起使用。 使用 state=present，force 选项允许覆盖现有容器。 使用状态 stopped、restarted 允许强制停止实例。 选择 false ← (默认) true
hookscript 字符串 在 community.general 0.2.0 中添加	在容器生命周期的各个步骤中执行的脚本。
hostname 字符串	实例主机名 仅当 state=present 时才需要 如果未传递 vmid，则必须是唯一的
ip_address 字符串	指定将分配给容器的地址
memory 整数	实例的内存大小（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]。
mountpoint 路径 / 必需	mount_volumes[].mountpoint 是卷的挂载点。
options 字典	mount_volumes[].options 是额外的选项字典。 任何给定选项的值必须是字符串，例如 "1"。
size 整数	mount_volumes[].size 是要使用的存储大小。 大小以 GB 为单位给出。 仅当定义了 mount_volumes[].storage 时才需要，并且与 mount_volumes[].host_path 互斥。
storage 字符串	mount_volumes[].storage 是要使用的存储的存储标识符。 与 mount_volumes[].host_path 互斥。
volume 字符串	mount_volumes[].volume 是现有卷的名称。 如果未定义，模块将检查是否存在。如果不存在，将创建一个新卷。 如果已定义，则该卷必须以该名称存在。 仅当定义了 mount_volumes[].storage 时才需要，并且与 mount_volumes[].host_path 互斥。
mounts 字典	为容器指定额外的挂载点（单独的磁盘）。作为定义挂载点的哈希/字典，以字符串形式表示。 此选项与 mount_volumes 互斥。
nameserver 字符串	为容器设置 DNS 服务器 IP 地址
netif 字典	为容器指定网络接口。作为定义接口的哈希/字典。
node 字符串	要在其上操作的 Proxmox VE 节点。 仅当 state=present 时才需要。 对于其他所有状态，它将被自动发现。
onboot 布尔值	指定 VM 是否在系统启动期间启动 选择 false true
ostemplate 字符串	用于创建 VM 的模板 仅当 state=present 时才需要
ostype 字符串 在 community.general 8.1.0 中添加	指定 LXC 容器的 ostype。 如果设置为 auto，则在实例创建时不会提供 ostype。 选择 "auto" ← (默认) "debian" "devuan" "ubuntu" "centos" "fedora" "opensuse" "archlinux" "alpine" "gentoo" "nixos" "unmanaged"
password 字符串	实例的 root 密码
pool 字符串	将新的 VM 添加到指定的池中。
pubkey 字符串	要添加到 /root/.ssh/authorized_keys 的公钥。这是在 Proxmox 4.2 上添加的，对于早期版本将被忽略
purge 布尔值 在 community.general 2.3.0 中添加	从所有相关配置中删除容器。 例如，备份作业、复制作业或 HA。 相关的 ACL 和防火墙条目将始终被删除。 与 state=absent 一起使用。 选择 false ← (默认) true
searchdomain 字符串	为容器设置 DNS 搜索域
startup 列表 / 元素=字符串 在 community.general 8.5.0 中添加	指定容器的启动顺序。 使用 order=#，其中 # 是一个非负数，用于定义常规启动顺序。关闭操作以相反的顺序进行。 使用 up=#，其中 # 是秒数，用于指定在启动下一个 VM 之前要等待的延迟。 使用 down=#，其中 # 是秒数，用于指定在停止下一个 VM 之前要等待的延迟。
state 字符串	指示实例的所需状态 template 在 community.general 8.1.0 中添加。 选择 "present" ← (默认) "started" "absent" "stopped" "restarted" "template"
storage 字符串	目标存储。 此选项与 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 ← (默认) true
validate_certs 布尔值	如果为 false，则不会验证 SSL 证书。 这应该只在个人控制的站点上使用自签名证书时使用。 选择 false ← (默认) true
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	支持：无	在 diff 模式下运行时，将返回已更改（或可能需要在 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)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 请求帮助
• 提交错误报告
• 请求功能
• 通信