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 整数	总 r/w 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 字符串	控制是否将 discard/trim 请求传递到基础存储。 选择 "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；对于 Unused：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 整数	每秒最大总读/写 I/O 操作数。 您可以指定总限制或每个操作的限制（与 iops_rd 和 iops_wr 互斥）。
iops_max 整数	每秒最大无限制总读/写 I/O 池操作数。
iops_max_length 整数	总 r/w 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 布尔值	是否为此驱动器使用 iothread（仅适用于 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 浮点数	每秒最大总读/写速度，单位为兆字节。 可以使用小数，但请谨慎使用 - 官方不支持小于 1 的小数。 您可以指定总限制或每个操作的限制（与 mbps_rd 和 mbps_wr 互斥）。
mbps_max 浮点数	每秒最大无限制总读/写池速度，单位为兆字节。
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	支持: 无	在 diff 模式下，将返回有关已更改内容（或在 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 字符串	关于模块所做操作的简短消息。 返回： 始终 示例： "Disk scsi3 created in VM 101"
vmid 整数	虚拟机的 vmid。 返回： 成功 示例： 101

作者

• Castor Sky (@castorsky)

集合链接

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