ansible-proxmox

Ansible Proxmox 集成

使用 community.proxmox collection 实现专业的 Proxmox 自动化，并尽量减少 CLI 使用。

模块选择

优先使用原生模块

有可用的 community.proxmox 模块时，请使用这些模块：

操作	使用模块	不要使用 CLI
创建 VM	community.proxmox.proxmox_kvm	qm create
克隆 VM	community.proxmox.proxmox_kvm	qm clone
管理用户	community.proxmox.proxmox_user	pveum user
管理组	community.proxmox.proxmox_group	pveum group
管理池	community.proxmox.proxmox_pool	pveum pool
管理 ACL	community.proxmox.proxmox_acl	pveum acl
存储	community.proxmox.proxmox_storage	pvesm

必须使用 CLI 的情况

部分操作没有原生模块：

操作	需要 CLI	原因
创建集群	pvecm create	没有对应模块
加入集群	pvecm add	没有对应模块
初始化 CEPH	pveceph init	工作流复杂
创建 CEPH OSD	pveceph osd create	工作流复杂

原生模块示例

从模板创建 VM

- name: Create VM from template
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_host }}"
    api_user: "{{ proxmox_api_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_token_secret }}"
    node: "{{ proxmox_node }}"
    vmid: "{{ vm_id }}"
    name: "{{ vm_name }}"
    clone: "{{ template_name }}"
    full: true
    storage: local-lvm
    memory: "{{ vm_memory | default(4096) }}"
    cores: "{{ vm_cores | default(2) }}"
    state: present
  delegate_to: localhost

管理 Proxmox 用户

- name: Create Terraform user
  community.proxmox.proxmox_user:
    api_host: "{{ proxmox_api_host }}"
    api_user: "root@pam"
    api_password: "{{ proxmox_root_password }}"
    userid: "terraform@pve"
    comment: "Terraform automation user"
    groups:
      - automation
    state: present
  no_log: true
  delegate_to: localhost

配置 ACL

- name: Grant terraform permissions
  community.proxmox.proxmox_acl:
    api_host: "{{ proxmox_api_host }}"
    api_user: "{{ proxmox_api_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_token_secret }}"
    path: "/"
    users:
      - terraform@pve
    roles:
      - Administrator
    state: present
  delegate_to: localhost

使用 CLI 并确保幂等性

必须使用 CLI 时，请添加适当的幂等性控制：

集群组建

- name: Check existing cluster status
  ansible.builtin.command: pvecm status
  register: cluster_status
  failed_when: false
  changed_when: false

- name: Set cluster facts
  ansible.builtin.set_fact:
    is_cluster_member: "{{ cluster_status.rc == 0 }}"
    in_target_cluster: "{{ cluster_name in cluster_status.stdout }}"

- name: Create cluster on primary node
  ansible.builtin.command: pvecm create {{ cluster_name }}
  when:
    - inventory_hostname == groups['proxmox'][0]
    - not in_target_cluster
  register: cluster_create
  changed_when: cluster_create.rc == 0

- name: Join cluster on secondary nodes
  ansible.builtin.command: pvecm add {{ hostvars[groups['proxmox'][0]].ansible_host }}
  when:
    - inventory_hostname != groups['proxmox'][0]
    - not is_cluster_member
  register: cluster_join
  changed_when: cluster_join.rc == 0

创建 API 令牌

- name: Create API token
  ansible.builtin.command: >
    pveum user token add {{ username }}@pam {{ token_name }}
    --privsep 0
  register: token_result
  changed_when: "'already exists' not in token_result.stderr"
  failed_when:
    - token_result.rc != 0
    - "'already exists' not in token_result.stderr"
  no_log: true

身份验证模式

API 令牌（推荐）

# Store token in variables or Infisical
proxmox_api_host: "192.168.1.10"
proxmox_api_user: "terraform@pve"
proxmox_token_id: "automation"
proxmox_token_secret: "{{ lookup('infisical', 'PROXMOX_TOKEN_SECRET') }}"

- name: Create VM
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_host }}"
    api_user: "{{ proxmox_api_user }}"
    api_token_id: "{{ proxmox_token_id }}"
    api_token_secret: "{{ proxmox_token_secret }}"
    # ... rest of config

Root 密码（本地操作）

用于在 Proxmox 节点本身执行操作：

- name: Retrieve root password
  ansible.builtin.include_tasks: tasks/infisical-secret-lookup.yml
  vars:
    secret_name: 'PROXMOX_ROOT_PASSWORD'
    secret_var_name: 'proxmox_root_password'

- name: Configure via API
  community.proxmox.proxmox_user:
    api_host: "{{ inventory_hostname }}"
    api_user: "root@pam"
    api_password: "{{ proxmox_root_password }}"
    # ... config
  no_log: true

集群操作

幂等的集群状态检查

- name: Get cluster status
  ansible.builtin.command: pvecm status
  register: cluster_status
  changed_when: false
  failed_when: false

- name: Get cluster nodes
  ansible.builtin.command: pvecm nodes
  register: cluster_nodes
  changed_when: false
  failed_when: false
  when: cluster_status.rc == 0

- name: Set cluster facts
  ansible.builtin.set_fact:
    cluster_exists: "{{ cluster_status.rc == 0 }}"
    cluster_node_count: "{{ cluster_nodes.stdout_lines | length | default(0) }}"
    is_quorate: "{{ 'Quorate: Yes' in cluster_status.stdout | default('') }}"

验证集群健康状况

- name: Verify cluster quorum
  ansible.builtin.command: pvecm status
  register: cluster_health
  changed_when: false
  failed_when: "'Quorate: Yes' not in cluster_health.stdout"

- name: Verify expected node count
  ansible.builtin.command: pvecm nodes
  register: nodes_check
  changed_when: false
  failed_when: nodes_check.stdout_lines | length != groups['proxmox'] | length

CEPH 集成

初始化 CEPH

- name: Check if CEPH is initialized
  ansible.builtin.command: pveceph status
  register: ceph_status
  changed_when: false
  failed_when: false

- name: Initialize CEPH
  ansible.builtin.command: >
    pveceph init --network {{ ceph_network }}
  when:
    - inventory_hostname == groups['proxmox'][0]
    - ceph_status.rc != 0
  register: ceph_init
  changed_when: ceph_init.rc == 0

创建 OSD

- name: Check if OSD exists on device
  ansible.builtin.command: >
    pveceph osd list
  register: osd_list
  changed_when: false

- name: Create OSD
  ansible.builtin.command: >
    pveceph osd create {{ item }}
  loop: "{{ ceph_osd_devices }}"
  when: item not in osd_list.stdout
  register: osd_create
  changed_when: osd_create.rc == 0

网络配置

使用 community.general.interfaces_file 配置网络：

- name: Configure VLAN-aware bridge
  community.general.interfaces_file:
    iface: vmbr1
    option: bridge-vlan-aware
    value: "yes"
    backup: true
    state: present
  notify: reload network

- name: Set bridge ports
  community.general.interfaces_file:
    iface: vmbr1
    option: bridge-ports
    value: "bond0"
    backup: true
    state: present
  notify: reload network

反模式

模块已存在却使用 CLI

# BAD - Module exists for this
- name: Create user
  ansible.builtin.command: pveum user add terraform@pve

# GOOD
- name: Create user
  community.proxmox.proxmox_user:
    api_host: "{{ proxmox_api_host }}"
    api_user: "root@pam"
    api_password: "{{ password }}"
    userid: "terraform@pve"
    state: present

使用 CLI 时缺少幂等性

# BAD - Will fail on second run
- name: Create cluster
  ansible.builtin.command: pvecm create MyCluster

# GOOD
- name: Check cluster status
  ansible.builtin.command: pvecm status
  register: cluster_check
  changed_when: false
  failed_when: false

- name: Create cluster
  ansible.builtin.command: pvecm create MyCluster
  when: cluster_check.rc != 0

在错误的主机上运行

# BAD - API calls from managed node
- name: Create VM
  community.proxmox.proxmox_kvm:
    api_host: "{{ inventory_hostname }}"  # Calling itself
    # ...

# GOOD - Delegate API calls to localhost
- name: Create VM
  community.proxmox.proxmox_kvm:
    api_host: "{{ proxmox_api_host }}"
    # ...
  delegate_to: localhost

安装 Collection

# Install community.proxmox
uv run ansible-galaxy collection install community.proxmox

# Or via requirements.yml
cd ansible
uv run ansible-galaxy collection install -r requirements.yml

更多资源

如需了解详细的 Proxmox 自动化模式，请参阅：

• references/ceph-automation.md - CEPH 存储部署和 OSD 管理
• references/cluster-automation.md - Proxmox 集群创建和节点加入
• references/network-automation.md - 支持 VLAN 的网桥和网络配置
• references/community-proxmox-plugin-index.md - 完整的 community.proxmox 模块参考

相关技能

• ansible-fundamentals - 核心模块选择模式
• ansible-idempotency - 使 CLI 命令具备幂等性
• ansible-error-handling - 集群操作的错误恢复