用 Ansible 管理 PVE

Terraform 管"有哪些机器"，Ansible 管"机器里装什么、配成什么样"，两者互补。这篇讲怎么用社区维护的 Ansible 集合操作 PVE 本身（建客户机、查状态），以及怎么把 PVE 里的客户机自动纳入 Ansible 的管理清单。

模块不是 Proxmox 官方维护

和 Terraform 一样，这里用到的模块是社区项目，参数名、行为以对应集合的官方文档为准，不确定就先在测试客户机上跑一遍。

为什么需要它

批量给一堆已存在的客户机做同样的配置（装软件包、改配置文件、加用户），比手动 SSH 一台台改更可靠、可重复。
配合 Terraform 的典型流程：Terraform 创建/销毁机器 → 把新机器的地址喂给 Ansible（动态清单或 Terraform 的输出）→ Ansible 配置机器内部。
也能直接操作 PVE 本身（创建客户机、查状态），适合不想为此再学一门 Terraform 的场景。

开始之前

一台装了 ansible-core 的控制机（可以是你自己的电脑，也可以是 PVE 节点本身）。
安装对应集合和它依赖的 Python 库：

# 本地电脑或任意做 Ansible 控制端的机器
ansible-galaxy collection install community.proxmox
pip install "proxmoxer>=2.3" requests

一个专门给自动化用的 API Token，用 Ansible Vault 或其他保密方式存放 Secret，不要明文写进 playbook。

模块曾经在 community.general 里

如果查到的教程写的是 community.general.proxmox_kvm 这类名字，那是旧位置。这些模块已经整体移到独立的 community.proxmox 集合，旧名字目前只是一个已弃用的重定向，未来会从 community.general 里彻底移除。新项目直接用 community.proxmox.*。

集合提供了什么

community.proxmox 覆盖客户机、存储、用户、集群/HA 等多个方面，下面是一份不完整的摘录，完整清单以集合官方文档为准：

类别	举例
虚拟机	`proxmox_kvm`（创建/管理/克隆 QEMU 虚拟机）
容器	`proxmox`（创建/管理 LXC 容器）
磁盘	`proxmox_disk`
存储	`proxmox_storage`
用户与认证	`proxmox_user`、`proxmox_group`、`proxmox_domain`
集群与 HA	`proxmox_cluster`、`proxmox_cluster_ha_groups`、`proxmox_cluster_ha_rules`
动态清单	`community.proxmox.proxmox` inventory 插件

用动态清单自动发现客户机

不用手动维护一份主机列表，让 Ansible 直接从 PVE 集群拉：

yaml

# inventory/pve.proxmox.yml —— 文件名必须以 .proxmox.yml 或 .proxmox.yaml 结尾
plugin: community.proxmox.proxmox
url: https://<pve-host>:8006
user: automation@pve
token_id: ansible
token_secret: "<token-secret>" # 占位符，不要提交进仓库
validate_certs: false          # 自签证书环境下临时使用，正式环境建议改成 true 并配好证书
want_facts: true

# 本地电脑或控制端执行，验证清单能读到东西
ansible-inventory -i inventory/pve.proxmox.yml --list

一个最小 playbook 示例

yaml

- hosts: localhost
  gather_facts: false
  tasks:
    - name: 从模板克隆一台测试虚拟机
      community.proxmox.proxmox_kvm:
        api_host: "<pve-host>"
        api_user: "automation@pve"
        api_token_id: "ansible"
        api_token_secret: "<token-secret>" # 占位符
        node: "<pve-node>"
        name: "ansible-test"
        clone: "<模板名或vmid>"
        full: true
        state: present

参数名以你安装的集合版本为准

community.proxmox 独立出来后经历过参数调整（2.0.0 相对旧版有变化），照抄网上找到的旧 playbook 之前，先对照当前安装版本的模块文档确认参数名还存在。

检查结果

ansible-inventory --list 输出里能看到预期的客户机。
跑 playbook 前先加 --check --diff 看一遍差异（注意：部分 Proxmox 模块在 check 模式下不能完全模拟真实 API 调用，不能百分百依赖它替代真实验证）。
执行后去 Web UI 确认客户机状态和 playbook 描述的一致。

常见问题

报 ModuleNotFoundError: proxmoxer。 控制机上没装依赖库，执行 pip install proxmoxer requests。

找不到模块，提示 community.proxmox.proxmox_kvm 不存在。 集合没装（ansible-galaxy collection install community.proxmox），或者装在了 Ansible 搜索不到的路径。

认证失败。 检查 api_token_id、api_user 里的 @认证域 和 !TokenID 有没有拼对，Token 是否还在有效期内、有没有被撤销。

克隆报 vmid 冲突或存储不存在。 目标 VMID 已被占用（不填则由 PVE 自动分配，但并发跑多个 playbook 时仍可能撞车），或者目标节点没有和源客户机同名的存储。

破坏性操作要格外小心

state: absent 会直接销毁客户机

容器/虚拟机模块的 state: absent（部分模块还有单独的停止/销毁状态）会直接关闭并删除客户机及其磁盘。和 Terraform 的 plan 不同，Ansible 默认不会先给你看一遍将要做什么。

影响范围：playbook 里目标为 absent（或等效销毁状态）的所有客户机及其磁盘。

前置条件：

先对测试 VMID 或专用资源池跑一遍，--check --diff 只能作为参考，不能完全替代真实验证。
批量任务先用 --limit 只对一小部分目标试跑，确认行为符合预期再放开范围。
确认目标客户机没有需要保留的数据，或已经完成备份。

如何回退：客户机一旦被删除，磁盘数据本身无法通过 Ansible 找回，只能靠备份与恢复里的方式还原；playbook 本身可以改回 state: present 重新创建一台同名的空机器，但不等于恢复原有数据。

用 Ansible 管理 PVE ​

为什么需要它 ​

开始之前 ​

集合提供了什么 ​

用动态清单自动发现客户机 ​

一个最小 playbook 示例 ​

检查结果 ​

常见问题 ​

破坏性操作要格外小心 ​

参考资料 ​