community.general.proxmox_disk 模块 – 管理 Proxmox VE 集群中 Qemu(KVM) 虚拟机的磁盘

注意

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

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

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

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

community.general 5.7.0 中的新增功能

概要

• 允许您在 Proxmox VE 集群中的 Qemu(KVM) 虚拟机中的磁盘上执行一些受支持的操作。

要求

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

• proxmoxer

• requests

参数

参数	注释
aio 字符串	要使用的 AIO 类型。 选项 "native" "threads" "io_uring"
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 字符串 / 必需	指定用于身份验证的用户。
backup 布尔值	在进行备份时是否应包含该驱动器。 选项 false true
bps_max_length 整数	总读/写 I/O 突发的最大长度（以秒为单位）。
bps_rd_max_length 整数	读取 I/O 突发的最大长度（以秒为单位）。
bps_wr_max_length 整数	写入 I/O 突发的最大长度（以秒为单位）。
bwlimit 整数	覆盖 I/O 带宽限制（以 KB/s 为单位）。 仅当 state=moved 时使用。
cache 字符串	驱动器的缓存模式。 选项 "none" "writethrough" "writeback" "unsafe" "directsync"
create 字符串	使用 create 标志，您可以控制 state=present 的行为。 当 create=disabled 时，它不会创建新磁盘（如果不存在），而是更新现有磁盘中的选项。 当 create=regular 时，它将创建新磁盘（如果不存在）或更新现有磁盘中的选项。 当 create=forced 时，它将始终创建新磁盘（如果磁盘存在，它将被分离并保持未使用状态）。 选项 "disabled" "regular" ← (默认) "forced"
cyls 整数	强制驱动器的物理几何形状具有特定的柱面计数。
delete_moved 布尔值	在成功复制后删除原始磁盘。 默认情况下，原始磁盘将保留为未使用磁盘。 仅当 state=moved 时使用。 选项 false true
detect_zeroes 布尔值	控制是否检测并尝试优化零写入。 选项 false true
discard 字符串	控制是否将丢弃/修剪请求传递给底层存储。 选项 "ignore" "on"
disk 字符串 / 必需	要操作的磁盘键（unused[n]、ide[n]、sata[n]、scsi[n] 或 virtio[n]）。 磁盘总线（IDE、SATA 等）在 Proxmox API 中接受的 n 值具有固定范围。 对于 IDE：0-3；对于 SCSI：0-30；对于 SATA：0-5；对于 VirtIO：0-15；对于未使用：0-255。
format 字符串	驱动器后备文件的数据格式。 选项 "raw" "cow" "qcow" "qed" "qcow2" "vmdk" "cloop"
heads 整数	强制驱动器的物理几何形状具有特定的磁头计数。
import_from 字符串	从此现有卷导入卷。 卷字符串格式 <STORAGE>:<VMID>/<FULL_NAME> 或 <ABSOLUTE_PATH>/<FULL_NAME> 注意！只有 root 用户才能使用绝对路径。 此参数与 size 互斥。 当导入大型磁盘镜像或使用慢速存储时，增加 timeout 参数。
iops 整数	每秒最大总 r/w I/O 操作数。 您可以指定总限制或每个操作的限制（与 iops_rd 和 iops_wr 互斥）。
iops_max 整数	每秒最大无限制的总 r/w I/O 池操作数。
iops_max_length 整数	总读/写 I/O 突发的最大长度（以秒为单位）。
iops_rd 整数	每秒最大读取 I/O 操作数。 您可以指定读取限制或总限制（与 iops 互斥）。
iops_rd_max 整数	每秒最大无限制的读取 I/O 池操作数。
iops_rd_max_length 整数	读取 I/O 突发的最大长度（以秒为单位）。
iops_wr 整数	每秒最大写入 I/O 操作数。 您可以指定写入限制或总限制（与 iops 互斥）。
iops_wr_max 整数	每秒最大无限制的写入 I/O 池操作数。
iops_wr_max_length 整数	写入 I/O 突发的最大长度（以秒为单位）。
iothread 布尔值	是否为此驱动器使用 iothreads（仅适用于 SCSI 和 VirtIO） 选项 false true
iso_image 字符串 在 community.general 8.1.0 中添加	要挂载在 disk 中指定的 CD-ROM 上的 ISO 镜像。 需要指定 media=cdrom 此选项才能生效。 镜像字符串格式 <STORAGE>:iso/<ISO_NAME> 用于挂载 ISO。 cdrom 用于使用物理 CD/DVD 驱动器。 none 用于从现有 CD-ROM 卸载镜像或创建空的 CD-ROM 驱动器。
mbps 浮点数	每秒最大总 r/w 速度，单位为兆字节。 可以是小数，但请谨慎使用 - 官方不支持小于 1 的小数。 您可以指定总限制或每个操作的限制（与 mbps_rd 和 mbps_wr 互斥）。
mbps_max 浮点数	每秒最大无限制的总 r/w 池速度，单位为兆字节。
mbps_rd 浮点数	每秒最大读取速度，单位为兆字节。 您可以指定读取限制或总限制（与 mbps 互斥）。
mbps_rd_max 浮点数	每秒最大无限制的读取池速度，单位为兆字节。
mbps_wr 浮点数	每秒最大写入速度，单位为兆字节。 您可以指定写入限制或总限制（与 mbps 互斥）。
mbps_wr_max 浮点数	每秒最大无限制的写入池速度，单位为兆字节。
media 字符串	驱动器的介质类型。 选项 "cdrom" "disk"
name 字符串	虚拟机的唯一名称。 您可以指定 name 或 vmid，或同时指定两者。
queues 整数	队列数（仅限 SCSI）。
replicate 布尔值	是否应将驱动器视为复制作业。 选项 false true
rerror 字符串	读取错误操作。 选项 "ignore" "report" "stop"
ro 布尔值	驱动器是否为只读。 选项 false true
scsiblock 布尔值	是否使用 scsi-block 来完全直通主机块设备。 与主机上的低内存或高内存碎片结合使用可能会导致 I/O 错误。 选项 false true
secs 整数	强制驱动器的物理几何形状具有特定的扇区计数。
serial 字符串	驱动器报告的序列号，采用 url 编码，最长 20 个字节。
shared 布尔值	将此本地管理的卷标记为在所有节点上可用。 此选项不会自动共享卷，它假定该卷已共享！ 选项 false true
size 字符串	当 state=present 时要分配的所需卷大小，单位为 GB（指定 size 时不带后缀）。 当 state=resized 时，卷的新大小（或附加大小）。 使用 + 符号时，该值将添加到卷的实际大小，而没有 + 符号时，该值将作为绝对值。
snapshot 布尔值	控制 qemu 的快照模式功能。 如果激活，对磁盘所做的更改是临时的，并且在虚拟机关闭时将被丢弃。 选项 false true
ssd 布尔值	是否将此驱动器公开为 SSD，而不是旋转式硬盘。 选项 false true
state 字符串	指示磁盘的所需状态。 state=present 可用于创建、替换磁盘或更新现有磁盘中的选项。它将默认创建缺少的磁盘或更新现有磁盘中的选项。请参阅 create 参数描述，以控制此选项的行为。 某些选项的更新（如 cache）不会立即应用，并且需要重启虚拟机。 使用 state=detached 将现有磁盘从虚拟机分离，但不要完全删除它。当 state=detached 并且磁盘为 unused[n] 时，它将保持在相同的状态（不删除）。 state=moved 可用于更改同一虚拟机范围内磁盘的后备存储，或将磁盘发送到另一个虚拟机（使用相同的后备存储）。 state=resized 用于更改磁盘大小。 从 Proxmox 7.2 开始，您只能增加磁盘大小，因为 PVE API 不支持缩小磁盘，必须手动完成。 要完全从后备存储中移除磁盘，请使用 state=absent。 选项 "present" ← (默认) "resized" "detached" "moved" "absent"
storage 字符串	驱动器的后备存储。 仅当 state 为 present 时使用。
target_disk 字符串	磁盘将移动到的目标虚拟机上的配置键（例如，ide0 或 scsi1）。 默认为源磁盘键。 仅当 state=moved 时使用。
target_storage 字符串	当 state=moved 时，将磁盘移动到此存储。 您只能在单个虚拟机的范围内在存储之间移动。 与 target_vmid 互斥。 如果磁盘映像较大或存储后端速度较慢，请考虑增加 timeout。
target_vmid 整数	当 state=moved 时，磁盘将放置到的虚拟机的（唯一）ID。 只有当使用相同的存储时，您才能在虚拟机之间移动磁盘。 与 target_vmid 互斥。
timeout 整数	等待慢速操作（如导入磁盘或在存储之间移动磁盘）的超时时间（秒）。 仅当 state 为 present 或 moved 时使用。 默认值: 600
trans 字符串	强制磁盘几何结构 BIOS 转换模式。 选项 "auto" "lba" "none"
validate_certs 布尔值	如果为 false，则不会验证 SSL 证书。 这仅应在使用自签名证书的个人控制站点上使用。 选项 false ← (默认) true
vmid 整数	虚拟机的唯一 ID。 您可以指定 vmid 或 name，或两者都指定。
werror 字符串	写入错误操作。 选项 "enospc" "ignore" "report" "stop"
wwn 字符串	驱动器的全球名称，编码为 16 字节十六进制字符串，前缀为 0x。

属性

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

示例

- name: Create new disk in VM (do not rewrite in case it exists already)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    name: vm-name
    disk: scsi3
    backup: true
    cache: none
    storage: local-zfs
    size: 5
    state: present

- name: Create new disk in VM (force rewrite in case it exists already)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: scsi3
    format: qcow2
    storage: local
    size: 16
    create: forced
    state: present

- name: Update existing disk
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: ide0
    backup: false
    ro: true
    aio: native
    state: present

- name: Grow existing disk
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: sata4
    size: +5G
    state: resized

- name: Detach disk (leave it unused)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    name: vm-name
    disk: virtio0
    state: detached

- name: Move disk to another storage
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_password: secret
    vmid: 101
    disk: scsi7
    target_storage: local
    format: qcow2
    state: moved

- name: Move disk from one VM to another
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: scsi7
    target_vmid: 201
    state: moved

- name: Remove disk permanently
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_password: secret
    vmid: 101
    disk: scsi4
    state: absent

- name: Mount ISO image on CD-ROM (create drive if missing)
  community.general.proxmox_disk:
    api_host: node1
    api_user: root@pam
    api_token_id: token1
    api_token_secret: some-token-data
    vmid: 101
    disk: ide2
    media: cdrom
    iso_image: local:iso/favorite_distro_amd64.iso
    state: present

返回值

常见返回值记录在此处，以下是此模块特有的字段

键	描述
msg 字符串	关于模块所做操作的简短消息。 返回: 始终 示例: "在 VM 101 中创建了磁盘 scsi3"
vmid 整数	虚拟机 vmid。 返回: 成功 示例: 101

作者

• Castor Sky (@castorsky)

集合链接

• 问题跟踪器
• 存储库（来源）
• 寻求帮助
• 提交错误报告
• 请求功能
• 交流