Ansible 平时可以默认的那个前提

你用过的几乎每一个 Ansible 模块都是这样工作的:Ansible 连到清单里写的那台主机,把一个小 Python 程序拷过去,运行,再把结果读回来。主机既是被修改的对象,也是干活的那一方。

创建虚拟机用最根本的方式打破了这一点。**你要构建的那台主机还不存在。**它没有 IP,没有 SSH 守护进程,没有 Python,也没有操作系统。根本没有东西可连。

所以 community.proxmox 不是配置代理。它是一个 API 客户端,只不过碰巧以 Ansible 集合的形式发布。因此,本文的一切都从这一个事实推出来:任务在哪里运行,凭据怎么传进去,为什么重跑不会做你以为的事,以及为什么 --check 没有对你说实话。

这里的例子是从一个根据 NetBox 记录构建 Fisher-Price OS (Windows) 和 Linux 虚拟机的 playbook 里删减出来的:proxmox-create-vms.yml。为了好读,我把节点、存储和网桥的名字改成了通用的,真东西在那个仓库里。

下面我对模块行为的每一个说法,都对照 community.proxmox 1.6.0 核实过,这是我装的版本:

$ ansible-galaxy collection list community.proxmox
# /home/damien/.ansible/collections/ansible_collections
Collection        Version
----------------- -------
community.proxmox 1.6.0

首先:这个集合搬家了

如果你在看较老的 playbook 或较老的回答,那时这些模块叫 community.general.proxmox_kvm。它们现在住在一个专门的集合里,开发也在那里进行。1.6.0 版本带了 47 个模块,覆盖 Ceph、SDN、防火墙、HA 规则和加入集群,这些在 community.general 时代都没有。

ansible-galaxy collection install community.proxmox
pip install 'proxmoxer>=2.0' requests

Python 依赖不是可选的,也没有打包进去:集合声明了 requirements: ["proxmoxer >= 2.0", "requests"],这些需要装在模块实际执行的地方,而下一节会解释,那不是 Proxmox 节点。

如果你想固定版本,用 requirements.yml:

---
collections:
  - name: community.proxmox
    version: ">=1.6.0"

该集合针对 ansible-core 2.17 到 2.20 做了测试。把你的 community.general.proxmox_* 任务改名为 community.proxmox.proxmox_*,迁移就完成了大半。

每个 Proxmox 任务都在 localhost 上运行

play 顶部的两行承担了主要工作,而这两行看上去都像在关掉什么有用的东西:

- name: Create Proxmox virtual machines
  hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"
  gather_facts: false
  serial: 1

gather_facts: false 不是优化。收集 facts 要连到清单主机,而清单主机是一台还没建好的虚拟机。不关掉的话,play 在第一个任务之前就失败了。

然后每一个 Proxmox 任务都带着 delegate_to: localhost:

- name: Create Proxmox VM
  delegate_to: localhost
  register: created_vm
  community.proxmox.proxmox_kvm:
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    api_host: "{{ proxmox_api_ip }}"
    name: "{{ inventory_hostname }}"
    node: "{{ proxmox_api_host }}"
    ...

清单主机现在只是一个名字加一袋变量。inventory_hostname 成了虚拟机的名字;它的变量描述你想要的机器。没有任何东西连到它。任务在控制节点上运行,控制节点打开一个到 api_host 的 HTTPS 会话,提交一份虚拟机定义。

你还会看到这写成 local_action:,那是同一件事的旧语法。那个仓库里的拆除 playbook 通篇用的都是它。两者等价。delegate_to 是现在的写法。

逃生舱口指向节点

有些事确实必须在 Proxmox 主机上做,这些任务就委派到完全不同的地方去:

- name: Fail if no ISO file exists for the OS
  delegate_to: "{{ proxmox_api_host }}"
  ansible.builtin.stat:
    path: "{{ iso | replace('isos:', '/mnt/pve/isos/template/') }}"
  register: iso_file
  failed_when: not iso_file.stat.exists

这是一个真实的 SSH 连接,连到一个真实的节点,检查共享存储上的一个真实路径,因为 API 会很乐意接受一个解析不到任何文件的 ISO 引用,而你宁可现在发现,也不要等到开机时才发现。注意那段字符串手术,把 PVE 存储引用(isos:iso/debian.iso)翻译成文件系统路径。stat 用不了存储抽象层。

所以一个 play 里的任务在三个不同的地方执行,把它们搞混是这类 playbook 失败的最常见方式:

Proxmox 构建 playbook 里每个任务实际在哪里执行Ansible 控制节点delegate_to: localhostproxmox_kvmproxmox_vm_infoproxmox_diskproxmox_access_acl它们每一个都是HTTPS 客户端,不是代理proxmoxer ≥ 2.0 + requests装在这里,不在节点上gather_facts: falseProxmox 节点:pve1pvedaemon, REST API监听 8006 端口qm、/etc/pve、存储虚拟机定义落在这里你正在创建的虚拟机没有 IP · 没有 SSH · 没有 Python没有操作系统在清单里它只是一个名字和一堆变量APISSHqm setstat无处可连要等到后面的 play
一个 play 里的三种执行上下文。Proxmox 模块从不碰节点或客户机,它们是跑在 playbook 旁边的 HTTPS 客户端。qm 逃生舱口是唯一需要 SSH 到虚拟化主机的部分。

凭据,以及一个即将改变的默认值

认证选项通过一个文档片段被集合里的每个模块共享,所以到哪儿都一样:api_host、api_user,然后是 api_password,或者 api_token_id / api_token_secret 这一对。它们全都会回退到环境变量:PROXMOX_HOST、PROXMOX_USER、PROXMOX_PASSWORD、PROXMOX_TOKEN_ID、PROXMOX_TOKEN_SECRET、PROXMOX_VALIDATE_CERTS,这是把机密完全挡在 play 之外最干净的办法。

API 令牌是更好的默认选择。它有范围限制,吊销它不用改某个人的密码,而且可以只给它 playbook 需要的权限,而不是某个人碰巧拥有的那些:

- name: Create Proxmox VM
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    validate_certs: true
    ca_path: /etc/ssl/certs/pve-cluster-ca.pem

**今天就显式设置 validate_certs。**集合自己的文档说得很明白:

Currently defaults to false and changes default to true with community.proxmox 2.0.0.

这意味着一个从没提到它的 playbook 现在并没有校验 TLS,而一旦有人运行 --upgrade,它就会开始校验,于是也就开始在每个全新 Proxmox 安装自带的自签名证书上失败。与其让这个决定在一次构建进行到一半时砸下来,不如有意识地自己做决定。如果你保留自签名证书,就写 validate_certs: false,接受这条审计发现;如果你有一条像样的证书链,就把 ca_path 指向它。不管哪种,都写下来了。

最小可用的创建

把生产任务精简到真正定义一台机器的那些东西,就读得懂了:

- name: Create Proxmox VM
  delegate_to: localhost
  register: created_vm
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    validate_certs: true

    node: pve1
    name: "{{ inventory_hostname }}"
    cores: "{{ vcpus | int }}"
    memory: "{{ memory }}"
    machine: q35
    bios: ovmf
    ostype: l26
    scsihw: virtio-scsi-single
    scsi:
      scsi0: "vmdata:32,format=qcow2,discard=on,ssd=1"
    sata:
      sata0: "isos:iso/debian-13-netinst.iso,media=cdrom"
    net:
      net0: "virtio,bridge=vmbr0"
    efidisk0:
      storage: vmdata
      format: raw
      efitype: 4m
      pre_enrolled_keys: true
    boot: "order=scsi0;sata0"
    agent: "enabled=1,fstrim_cloned_disks=1"
    onboot: true
    tags:
      - production

写你自己的之前,这个形状里有几点值得知道。

设备选项是写在 YAML 里的 PVE 语法。scsi、sata、net、virtio、ide 的类型都是 dict,键是 scsi0、net0 之类,而值是直接从 man qm 里搬来的逗号分隔选项字符串:磁盘是 <storage>:<size>,option=value,网卡是 [model=]<enum>,option=value。模块不对它们建模;它只是转发。被拒绝的时候,答案在 PVE 选项参考里,不在 Ansible 文档里。

你还会看到这些写成 JSON 字符串而不是 YAML 映射:

    net: '{"net0":"virtio,bridge={{ vlan_bridge }}"}'

两种都行。对 dict 类型的参数,Ansible 会转换字符串。JSON 形式之所以存在,是因为用一个 Jinja 表达式模板化整个结构更容易。映射形式在六个月后更好读。

**boot 有两代语法。**模块接受老式字母写法,boot: "cdn" 的意思是“先试磁盘,再试光驱,再试网络”。现在的 PVE 要的是一个显式的有序列表,boot: "order=scsi0;sata0;net0",哪块盘说得清清楚楚。老写法仍然能用。新工作里你要的是显式写法。模块文档里埋着一个真正的坑:自 PVE 8.3.5 起,网络启动需要设置 rng0。

numa 和 numa_enabled 是两个不同的参数。numa_enabled 是打开 NUMA 的布尔值。numa 是一个描述拓扑的 dict(cpus、hostnodes、memory、policy)。设置 numa: true 是类型错误,很容易就白丢一个小时。如果你想知道这些为什么要紧,Proxmox 上的 NUMA 对齐讲了底层的问题。

machine: q35 和 bios: ovmf 是正确的默认值,不是装饰,完整的论证在这里。

**省略 vmid 意味着模块会向 API 要下一个空闲 ID。**方便,也直接引出了下一件事。

为什么要 serial: 1

“取下一个可用 ID,再用它创建一台虚拟机”是两次 API 调用,中间有个空档。两个 worker 同时这么做,可能读到同一个空闲 ID,输的那个会得到一个错误,或者更糟,一个意外。

serial: 1 让创建阶段一次只处理一台主机。不快,也不需要快。构建虚拟机最费时的部分发生在这个 playbook 交接之后。对应的那个启动已建好虚拟机的 play 用的是 serial: 5,因为启动没有共享计数器可抢。

如果你想要并行,就从你的真实数据源自己分配 VMID,显式传进去。这样就没有读-改-写,也就没有竞争。

幂等性不是你以为的那样

这一节要读两遍,因为 proxmox_kvm 的行为不像 ansible.builtin.package。

name 不是身份标识。虚拟机名字在一个 Proxmox 集群里并不唯一,模块自己也这么说。在 state: present 且没有 vmid 的情况下,如果同名虚拟机已经存在,模块以 changed=false 退出,带着 msg: "VM with name <x> already exists",什么都不做。它不把你的参数和现实对比。它不收敛。它拒绝。

**update 默认是 false。**所以在 playbook 里改 memory: 再重跑,什么都不会发生。虚拟机保持构建时的内存,任务报告成功,哪儿都没有任何东西告诉你两者已经分道扬镳。

**update: true 仍然拒绝那些要紧的参数。**模块文档原话:

Because of the operations of the API and security reasons, I have disabled the update of the following parameters net, virtio, ide, sata, scsi. Per example updating net update the MAC address and virtio create always new disk…

update_unsafe: true 解除这个限制,而那条警告不是摆样子的:

Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated).

所以你以为在扩容的那块盘,可能被换成一块新的空盘。别去碰这个,被拒绝的那些参数有它们自己的模块,那就是下一节。

**而 --check 对这些一概不管。**集合按模块声明 check 模式支持,而它恰恰在最糟的方向上不一致:

模块check_modediff_mode
proxmox_kvm无无
proxmox_disk无无
proxmox_template无无
proxmox_snap完整无
proxmox_nic完整无
proxmox_pool完整无

分界线不是“只读模块可以,写模块不行”,proxmox_nic 会创建和删除网卡,check 模式照样支持得好好的。分界线是,处理存储和虚拟机生命周期的那三个模块不支持。对构建 playbook 跑一次 --check,会悄无声息地跳过虚拟机创建,然后对一个虚拟机从没被创建的世界做报告,于是后面每一个任务推理的都是错误的状态。在构建 playbook 上,--check 不是安全网,把它当安全网比不跑还糟。

proxmox_kvm 第二次运行实际做了什么第二次运行:state: present,且同名虚拟机已存在模块从不把你的参数和运行中的虚拟机比较update: false默认changed = false“VM with name <x>already exists”在 play 里改内存,再运行一次,没有任何地方告诉你update: true大部分能收敛核心数、内存、标签、agent、onboot 生效net, virtio, ide, sata,scsi, efidisk0, tpmstate0按设计拒绝这些改用 proxmox_disk和 proxmox_nicupdate_unsafe: true全部收敛被拒绝的参数也会应用一个磁盘参数可能重建磁盘永久丢失数据是文档写明的风险--check什么都不告诉你check_mode: none任务被跳过之后的每个任务都在一个虚拟机从未被创建的世界里推理四种里只有两种会收敛,而覆盖磁盘的那一种正是能毁掉磁盘的那一种。所以自己以是否存在为条件,把创建当作一次性事件。
第二次运行实际做了什么。四条路径里只有两条会收敛任何东西,而唯一涉及磁盘的那条,恰恰能毁掉磁盘。

所以让“是否存在”当闸门

考虑到这一切,可行的模式是别再指望模块幂等,由你自己决定要不要构建。生产 playbook 是这么做的:

- name: Check if VM is present or manually built
  delegate_to: localhost
  community.proxmox.proxmox_vm_info:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    config: current
  register: existing_vm
  ignore_errors: true
  failed_when: (existing_vm.proxmox_vms | length) == 0

- name: Configure Proxmox VM
  when: existing_vm is failed
  block:
    - name: Create Proxmox VM
      ...

带 config: current 的 proxmox_vm_info 返回虚拟机及其当前配置,或者一个空列表。failed_when 把“空列表”变成失败,ignore_errors: true 让这个失败不终止 play,而 when: existing_vm is failed 就成了“虚拟机不在,去建”。

用一个故意失败的任务当布尔值,读起来很别扭,我不打算假装不是。替代写法是 when: (existing_vm.proxmox_vms | default([]) | length) == 0,它老老实实地就是一个长度检查,也不需要 ignore_errors。两种都行。上面那个版本是生产里在用的,它唯一真正的优势是,注册下来的结果带着现有配置,供后面的任务读取。

重要的是形状,不是写法:**先检查,再分支,把创建当作一次性事件。**虚拟机的持续配置和虚拟机是否存在是两个不同的问题,而这个模块只擅长后一个。

磁盘和网卡有自己的模块

这是我上面一笔带过的事,而它改变了整个局面:proxmox_kvm 拒绝更新的那些参数,并不是集合的缺口。它们是被委派出去了。community.proxmox.proxmox_disk 和 community.proxmox.proxmox_nic 负责添加、修改和删除的,正是创建模块不肯碰的那些东西,用的键也正是你构建虚拟机时用的 scsi0 和 net0。

两者都比 proxmox_kvm 规矩,其中一个还是这个工作流里唯一能演练(dry-run)的模块。

proxmox_nic:添加、改标签或删除网卡

- name: Move the VM's primary NIC to a new bridge and VLAN
  delegate_to: localhost
  community.proxmox.proxmox_nic:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    interface: net0
    bridge: vmbr1
    tag: 120
    model: virtio
    mtu: 1
    queues: 4
    firewall: true
    state: present

除了认证之外,interface 是唯一必填的选项,net[n],n 从 0 到 31;state: present 或 absent 给你添加和删除。model 默认是 virtio,除非客户机应付不了,这就是正确答案。

**这个模块存在的理由是 MAC 地址。**回想一下 proxmox_kvm 为什么拒绝更新 net:“updating net update the MAC address”。proxmox_nic 明确解决了这个问题:

When not specified this module will keep the MAC address the same when changing an existing interface.

所以你可以改 VLAN 标签、换网桥、改 MTU 或打开防火墙,而客户机网卡的身份不会在它脚下变掉。这比听起来要紧:新的 MAC 会让 DHCP 预留失效,弄坏任何绑定在网卡上的授权,还会让创建 playbook 精心写下的那条 NetBox 接口记录对不上。有了这个模块,第二天的网络变更才能平淡无奇。

几个最好在需要之前就知道的选项:

  • rate 的单位是 MBps,即每秒兆字节,不是比特。文档写得很明确,而差八倍的错误非常容易犯。
  • link_down: true 断开网卡,文档描述为“like pulling the plug”。想隔离一台可疑的虚拟机,又不想停机或碰客户机,这是个干净的办法。
  • trunks 接受一个要透传的 VLAN ID 列表,给自己打标签的客户机用。
  • mtu: 1 不是笔误,也不是 1 字节的 MTU,它的意思是“继承网桥的 MTU”,而且只适用于 virtio。
  • queues 设置多队列,0 到 16。凡是跑真实流量的,都值得把它设成和 vCPU 数一致。

**而且它完整支持 check 模式。**对 proxmox_nic 任务跑 --check 会告诉你真话,这让它成为这个工作流里你唯一能安全彩排的部分。它的消息也是真正幂等的。没变的网卡报告 Nic net0 unchanged on VM with vmid 103,而不是谎称有了变化。

proxmox_disk:磁盘的整个生命周期

proxmox_disk 是三个里最大的模块,它的 state 身兼五职:

state发生什么可逆吗?
present创建磁盘,或更新现有磁盘的选项不适用
resized扩容,PVE 不能缩容,文档说要手动做否
detached变成 unused[n];卷和里面的数据都还在是
moved换后端存储,或把磁盘交给另一台虚拟机原盘保留,除非设了 delete_moved
absent从后端存储删除否

detached 和 absent 之间的差别,就是 proxmox_kvm 从来不给你的那张安全网。卸下是改配置;删除是毁数据。两个不同的词,两种不同的后果。

给一台已经存在的虚拟机加第二块盘:

- name: Add a data disk
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    storage: vmdata
    size: 200
    format: qcow2
    iothread: true
    aio: io_uring
    discard: "on"
    ssd: true
    backup: true
    state: present

**create 是 proxmox_kvm 本该有的那个旋钮。**它控制 state: present 被允许做什么:

  • regular(默认):磁盘不存在就创建,否则更新它的选项。
  • disabled:只更新选项,永远不创建。当你要改一块必须已经存在的磁盘上的 cache 或 iothread 时,就该用它。它不会因为某个键拼错了就凭空变出一个新卷来吓你一跳。
  • forced:总是创建。已有的磁盘会被卸下并留作 unused,而不是删除。

最后这个行为是关键细节。create: forced 看起来是那个有破坏性的选项,可它仍然什么都不毁:旧卷作为 unusedN 保留下来,你可以重新挂回去。拿它和 proxmox_kvm 加 update_unsafe 比一比,后者文档里写明的故障模式就是磁盘被重建。大致相同的操作,波及范围好得多。

给磁盘扩容:

- name: Grow the data disk by 100 GiB
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    size: "+100G"
    state: resized

**注意单位,因为 size 的含义会随 state 变化。**在 state: present 下,它是一个不带单位的数字,单位是 GiB(size: 200)。在 state: resized 下,它要带后缀:+100G 表示在当前大小上增加,500G 表示一个绝对目标。一个参数,两种约定,猜错了也不会报错。

把磁盘移到另一个存储上,也就是单个卷的在线迁移:

- name: Move the disk to NVMe storage
  delegate_to: localhost
  community.proxmox.proxmox_disk:
    api_host: "{{ proxmox_api_ip }}"
    api_user: ansible@pve
    api_token_id: automation
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: "{{ created_vm.vmid }}"
    disk: scsi1
    target_storage: nvme-pool
    bwlimit: 200000
    delete_moved: true
    timeout: 3600
    state: moved

target_storage 在同一台虚拟机内移动;target_vmid 把磁盘交给另一台虚拟机,并要求两边是同一个存储。两者互斥。delete_moved 默认是 false,所以默认情况下你最后会有两份拷贝,原盘作为 unused 留在那里。这很安全,但如果你再也不回来清理,也是填满一个存储池的好办法。

**这里 timeout 默认是 600,而 proxmox_kvm 里是 30。**看起来一样的参数,相差二十倍,因为这些操作要拷贝数据。镜像大或者存储慢,就把它调高,文档对 moved 和 import_from 都是这么说的。

这就引出了让这个模块成为 V2V 和云镜像通道的那个选项:

    import_from: "vmdata:9000/base-debian13.qcow2"

import_from 从一个已有的卷构建磁盘,而不是分配一块空盘:格式是 <STORAGE>:<VMID>/<NAME>,在 PVE 9.x 及以后也可以用存储的 import 目录写成 <STORAGE>:import/<NAME>。它和 size 互斥,而且只有 root 能用文件系统的绝对路径。

参数列表里剩下的部分,正是用这个模块挂磁盘、而不是在创建调用里内联写的理由:cache、aio、iothread、discard、ssd、backup、detect_zeroes,还有整套限速参数:iops、iops_rd、iops_wr,它们的 _max 和 _max_length 变体,以及 bps_*_max_length 突发控制。创建之后,这些没有一个能通过 proxmox_kvm 改到。

有两点要注意,都出自这个模块自己的文档:

  • 有些选项的修改需要重启。“Some updates on options (like cache) are not being applied instantly and require VM restart.” 任务显示绿色,意思是配置写进去了,不代表正在运行的虚拟机行为已经变了。
  • 它不支持 check 模式。check_mode: none,和 proxmox_kvm 一样。所以这个集合从中间劈成两半:网卡的修改可以用 --check 彩排,磁盘的修改不行。

分工

要做这件事用这个
创建虚拟机proxmox_kvm,只调用一次,以是否存在为条件
改核心数、内存、标签、agent、onbootproxmox_kvm 加 update: true
添加、改标签、断开或删除网卡proxmox_nic
添加、扩容、移动、卸下或删除磁盘proxmox_disk
快照proxmox_snap(同样完整支持 check 模式)
它们都不暴露的任何东西通过 SSH 执行 qm set
通过 proxmox_kvm 改磁盘或网卡不要这么做。update_unsafe 就是干这个的,这也正是你不该用它的原因

用一个最精简的 proxmox_kvm 调用构建虚拟机,然后用各自的模块挂上磁盘和网卡。任务多一些,但这个版本里,第二天的变更有一条路可走,而不必去用一个文档写明风险是丢盘的选项。

模块到此为止的地方

proxmox_kvm 的参数列表很长,但仍然覆盖不了 qm 能做的全部事情。生产 playbook 没有干等,而是在节点上直接退回到命令行:

- name: Set RNG source and better SPICE quality
  delegate_to: "{{ proxmox_api_host }}"
  become: true
  ansible.builtin.command:
    cmd: >-
      /usr/sbin/qm set {{ created_vm.vmid }}
      --rng0 source=/dev/urandom
      --spice_enhancements videostreaming=all

这没什么不对。它谈不上什么像样的幂等性,qm set 是一次写操作,每次运行都会报告 changed,但它明确、好读,而且不装模作样。以后模块要是加上了这个参数,你把这个任务删掉就行。

还有一些东西需要让模块带着 update: true 再跑一遍,因为它们不能在创建虚拟机的同一个调用里设置:

- name: Add SPICE-compatible USB device
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    node: "{{ proxmox_api_host }}"
    vmid: "{{ created_vm.vmid }}"
    usb:
      usb0: "spice,usb3=1"
    update: true
  when: spice_usb | default(false)

注意它传的是 vmid,不是 name。一旦拿到了 ID,就用 ID。它是 API 唯一当作唯一标识的东西。

至于 QEMU 能做、PVE 却没有对应选项的事情,还有 args,它会原样传到 QEMU 命令行上:

    args: >-
      -global scsi-hd.physical_block_size=4k
      -global scsi-hd.logical_block_size=4096

这一条让虚拟磁盘以 4Kn 而不是 512e 的形式呈现,这比听起来重要得多,见 块大小、4Kn 与 512e。模块把 args 标注为“for experts only”,原因是 PVE 不校验它,一个错误的参数会让虚拟机起不来,报错还是 QEMU 给的,而不是 Proxmox 给的。

集群不是瞬间一致的

- name: Let registration complete on cluster
  ansible.builtin.pause:
    seconds: 5
  when: created_vm.changed

playbook 里出现 pause 通常是个坏味道,但这一个是承重的。创建调用在 API 接受定义时就返回了,这和每个节点都认可这台虚拟机已经存在不是一回事,而紧接着的下一个任务就要在 /vms/<vmid> 上设置 ACL。五秒钟的耐心,比围着一个只在高负载下才出现的错误写重试循环便宜。

拆除 playbook 出于同样的原因也是同样的形状:停机,等待,再删除。

读回你构建出来的东西

proxmox_kvm 文档里写了三个返回值:vmid、status 和 msg。实际上你会需要第四个,而它不在文档里。

- name: Get MAC address of VM
  ansible.builtin.set_fact:
    primary_mac_addr: "{{ created_vm.mac.net0 }}"

created_vm.mac 是真实存在的,模块在 get_vminfo() 里构造它,再把它展开进结果里,但它不在文档的 RETURN 块中,这意味着没有任何承诺保证它会一直能用。值得弄清楚它到底怎么表现,因为里面有两个坑:

  1. 只有模块真正创建了虚拟机,它才会出现。mac 只在创建并部署的路径上组装。走了“已经存在”的分支,结果里只有 vmid 和 msg,别的什么都没有。
  2. **它只包含你传进去的那些网卡。**代码遍历的是你提供的参数,挑出匹配 net[0-9] 的那些,再从 API 读回每一个存储的配置。没有 net 参数,就没有 mac 键。

这就是为什么生产 playbook 两半都要,而第二半很难看:

- name: Get MAC address of VM
  ansible.builtin.set_fact:
    primary_mac_addr: >-
      {{ created_vm.mac.net0 if created_vm is defined and created_vm.changed
         else ((existing_vm.proxmox_vms[0].config.net0 | split(','))[0] | split('='))[1] }}

虚拟机已经存在时没有 mac,所以 MAC 只能从原始配置字符串里挖出来。net0 从 API 返回的样子是 virtio=AE:AE:5C:A8:89:85,bridge=vmbr0,所以:按逗号拆分,取第一段,再按 = 拆分,取后半段。这是对 API 响应做字符串手术,也是一个返回结构取决于走了哪个分支的模块的真实代价。

如果两种情况下你都需要可靠地拿到 MAC,那就无条件地从 proxmox_vm_info 取,只解析一种结构,而不是两种。

用唯一可信源来驱动

再看一眼开启这个 play 的那一行:

hosts: "{{ target_hosts | default('cluster_pve:&status_planned') }}"

这才是真正的架构,值得直说:要构建的虚拟机不是变量文件里的一张列表。它们是清单里那些记录状态表明应该存在、但还不存在的主机。

这里的清单是 NetBox。申请一台虚拟机,就是创建一条状态为 planned 的 NetBox 记录,带上它的 CPU、内存、磁盘、VLAN、负责人和平台。playbook 选出 planned 的机器,构建它们,分配 IP,写 DNS,然后把记录设为 staged。这时这台主机就不再匹配 play 的主机模式了,一个 handler 会刷新清单,让下一个 play 看到新状态:

handlers:
  - name: Refresh inventory
    ansible.builtin.meta: refresh_inventory

状态字段是一个状态机,playbook 是其中的一次状态转换,整个东西可以重复运行,因为已经往前走了的主机不会再被选中。这个性质比模块层面的任何幂等性都好得多,也是创建任务可以只跑一次的原因。

community.proxmox 也自带一个清单插件,它从集群构建清单。当 Proxmox 是唯一可信源时,那是正确的选择。这里正好反过来:NetBox 是权威,Proxmox 是把它的意图变成现实的地方。这本身就够写一整篇,我会另外写。

再把它拿掉

只有创建没有拆除,生命周期只走了一半,而删除这条路有它自己的坑:你不能删除一台正在运行的虚拟机:

- name: Force stop the VM if it is running
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    state: stopped
    force: true
    timeout: 10

- name: Allow the cluster to stop the VM before removing it
  ansible.builtin.pause:
    seconds: 10

- name: Remove the VM from the cluster
  delegate_to: localhost
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_ip }}"
    api_user: "{{ proxmox_user }}"
    api_password: "{{ proxmox_password }}"
    name: "{{ inventory_hostname }}"
    state: absent
    force: true
    timeout: 10

state: stopped 是正常关机,它和 timeout 之间的配合有文档说明,值得记住:如果达到超时且 force: true,虚拟机会被强制断电;如果 force: false,任务就会失败。十秒钟的正常关机窗口,然后拔插头,对一台正在被拆除的机器来说是合理的策略,对其他任何机器来说都很糟糕。

完整的拆除流程(proxmox-remove-vms.yml)接着把记录的其余部分逐一撤掉:DNS、分配的 IP、NetBox 接口、NetBox 虚拟机,以及 known_hosts 里的过期条目。它把这一块包在 ignore_errors: true 里,在拆除流程里这说得过去。你要删的东西可能已经不在了,而一台删了一半的机器比一份吵闹的日志更糟。

如果从头构建,我会改什么

读过模块的源代码而不只是它的文档之后,有五件:

  • 用 API 令牌,而不是 api_user 加 api_password。权限有范围,可以吊销,而且从来不属于某个人。
  • 显式设置 validate_certs,赶在 2.0.0 替你改掉它之前。
  • **自己从唯一可信源分配 VMID。**这消除了读取、修改、写回之间的竞争,让你可以去掉 serial: 1,也给之后每个任务一个稳定的标识,而不是一个不唯一的名字。
  • **先创建一台光秃秃的虚拟机,再用 proxmox_disk 和 proxmox_nic 挂上磁盘和网卡。**任务多一些,但每块磁盘、每块网卡以后都有一个能改它的模块,包括只改选项的 create: disabled,以及用 state: detached 代替删除,而不是一份只能通过 update_unsafe 修改的配置。
  • 在一个地方从 proxmox_vm_info 取 MAC,这样只需解析一种结构,而不是在一个有文档的返回值和一个没文档的返回值之间写条件判断。

还有,别对构建 playbook 用 --check。最关键的那个模块不支持它。

一个永远说“可以”的演练,比没有演练更糟,因为你会相信它。

参考资料