### Install pre-commit hooks

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Install the pre-commit hooks to enforce basic Ruff checks before each commit. Hooks are not active until installed.

```bash
pre-commit install
```

--------------------------------

### Install community.proxmox Collection and Dependencies

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Installs the Ansible collection and required Python libraries. Includes a sample requirements.yml for collection management.

```bash
ansible-galaxy collection install community.proxmox
```

```bash
pip install "proxmoxer>=2.3" requests
```

```yaml
collections:
  - name: community.proxmox
```

--------------------------------

### Example Playbook Task for Proxmox VM Info

Source: https://github.com/ansible-collections/community.proxmox/blob/main/docs/docsite/rst/guides.rst

This task demonstrates how to query virtual machines on Proxmox VE using API token authentication. Authentication parameters are defined at the play level for reuse.

```yaml
- name: Query VMs on Proxmox VE
  hosts: localhost
  gather_facts: false
  vars:
    api_host: 10.0.0.1
    api_token_id: "{{ vault_proxmox_token_id }}"
    api_token_secret: "{{ vault_proxmox_token_secret }}"
    validate_certs: true
  tasks:
    - name: Get VM inventory
      community.proxmox.proxmox_vm_info:
        api_host: "{{ api_host }}"
        api_token_id: "{{ api_token_id }}"
        api_token_secret: "{{ api_token_secret }}"
        validate_certs: "{{ validate_certs }}"
```

--------------------------------

### Install Collection with Ansible Galaxy

Source: https://github.com/ansible-collections/community.proxmox/blob/main/README.md

Install the community.proxmox collection using the ansible-galaxy command-line tool. This is the standard method for adding collections to your Ansible environment.

```bash
ansible-galaxy collection install community.proxmox
```

--------------------------------

### Proxmox Dynamic Inventory Plugin Configuration

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Configure the Proxmox dynamic inventory plugin to discover and manage Proxmox VE resources. This example shows how to connect to the Proxmox API, authenticate, and define groups based on tags and statuses.

```yaml
plugin: community.proxmox.proxmox
url: https://pve.example.com:8006
user: ansible@pve
password: "{{ lookup('env', 'PROXMOX_PASSWORD') }}"
want_facts: true
want_proxmox_nodes_ansible_host: false
qemu_extended_statuses: true
keyed_groups:
  - key: proxmox_tags_parsed
    separator: ""
    prefix: tag
groups:
  webservers: "'web' in (proxmox_tags_parsed|list)"
  databases: "'db' in (proxmox_tags_parsed|list)"
compose:
  ansible_host: proxmox_ipconfig0.ip | default(proxmox_net0.ip) | ipaddr('address')
filters:
  - proxmox_status == 'running'
```

--------------------------------

### Manage LXC Containers with community.proxmox.proxmox

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Creates, updates, starts, stops, and deletes LXC containers. Supports detailed configuration for networking, disks, and mount points.

```yaml
# Create a container with networking, disk, and resource limits
- name: Create LXC container
  community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ vault_token }}"
    vmid: 100
    node: pve01
    hostname: webserver.example.org
    ostemplate: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst'
    disk_volume:
      storage: local-lvm
      size: 20
    memory: 2048
    cores: 2
    netif:
      net0: "name=eth0,ip=192.168.1.10/24,gw=192.168.1.1,bridge=vmbr0"
    onboot: true
    state: present
```

```yaml
# Start, stop, and delete
- community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    node: pve01
    state: started   # stopped | restarted | absent
```

```yaml
# Container with additional mount point
- community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 101
    node: pve01
    hostname: data.example.org
    ostemplate: 'local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst'
    mount_volumes:
      - id: mp0
        storage: local-lvm
        size: 50
        mountpoint: /data
    state: present
```

--------------------------------

### Manage VM Power State with Proxmox KVM Module

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Control the power state (start, stop, restart, or remove) of a VM using the proxmox_kvm module. Ensure the VM name and node are correctly specified.

```yaml
- community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    name: myvm
    node: pve01
    state: stopped   # started | restarted | absent
```

--------------------------------

### Clone Repository for Local Testing

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Clone the repository into the expected directory structure for `ansible-test` to function correctly. This setup is crucial for running local tests.

```bash
mkdir -p ~/dev/ansible_collections/community
git clone https://github.com/ansible-collections/community.proxmox.git ~/dev/ansible_collections/community/proxmox
```

--------------------------------

### community.proxmox.proxmox — Manage LXC Containers

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Creates, updates, starts, stops, and deletes LXC containers. Automatically detects containerization type and supports rich disk, network, and mount-point configuration via structured parameters.

```APIDOC
## community.proxmox.proxmox — Manage LXC Containers

### Description
Creates, updates, starts, stops, and deletes LXC containers. Automatically detects containerization type. Supports rich disk, network, and mount-point configuration via structured parameters.

### Method
`community.proxmox.proxmox`

### Parameters
#### Common Authentication Parameters
- `api_host` (string) - Required - The Proxmox VE API host.
- `api_user` (string) - Required - The Proxmox VE API user.
- `api_password` (string) - Optional - The Proxmox VE API password. Use `api_token_id` and `api_token_secret` for automation.
- `api_token_id` (string) - Optional - The Proxmox VE API token ID.
- `api_token_secret` (string) - Optional - The Proxmox VE API token secret.
- `validate_certs` (boolean) - Optional - Whether to validate SSL certificates. Defaults to `true`.

#### Container Specific Parameters
- `vmid` (integer) - Required - The virtual machine ID.
- `node` (string) - Required - The Proxmox VE node name.
- `hostname` (string) - Optional - The hostname for the container.
- `ostemplate` (string) - Required for creation - The template to use for creating the container.
- `disk_volume` (dict) - Optional - Configuration for the container's root disk.
  - `storage` (string) - Required - The storage name for the disk.
  - `size` (integer) - Required - The size of the disk in GB.
- `memory` (integer) - Optional - The amount of memory in MB.
- `cores` (integer) - Optional - The number of CPU cores.
- `netif` (dict) - Optional - Network interface configuration.
  - `net0` (string) - Example: "name=eth0,ip=192.168.1.10/24,gw=192.168.1.1,bridge=vmbr0"
- `onboot` (boolean) - Optional - Whether the container should start on boot.
- `state` (string) - Optional - The desired state of the container (`present`, `started`, `stopped`, `restarted`, `absent`). Defaults to `present`.
- `mount_volumes` (list) - Optional - Additional mount points for the container.
  - `id` (string) - The ID of the mount point (e.g., `mp0`).
  - `storage` (string) - The storage name for the mount point.
  - `size` (integer) - The size of the mount point in GB.
  - `mountpoint` (string) - The mount point path inside the container.

### Request Example
```yaml
# Create a container with networking, disk, and resource limits
- name: Create LXC container
  community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ vault_token }}"
    vmid: 100
    node: pve01
    hostname: webserver.example.org
    ostemplate: 'local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst'
    disk_volume:
      storage: local-lvm
      size: 20
    memory: 2048
    cores: 2
    netif:
      net0: "name=eth0,ip=192.168.1.10/24,gw=192.168.1.1,bridge=vmbr0"
    onboot: true
    state: present

# Start, stop, and delete
- community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    node: pve01
    state: started   # stopped | restarted | absent

# Container with additional mount point
- community.proxmox.proxmox:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 101
    node: pve01
    hostname: data.example.org
    ostemplate: 'local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst'
    mount_volumes:
      - id: mp0
        storage: local-lvm
        size: 50
        mountpoint: /data
    state: present
```
```

--------------------------------

### Add Inbound Firewall Rules at VM Level

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Configure inbound firewall rules for a specific virtual machine (VM). This example allows inbound TCP traffic on port 22 from a specified source network. Ensure the `level` is set to `vm` and `vmid` is provided.

```yaml
- community.proxmox.proxmox_firewall:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    level: vm
    vmid: 101
    rules:
      - type: in
        action: ACCEPT
        proto: tcp
        dport: 22
        source: 10.0.0.0/8
        enable: true
```

--------------------------------

### Copy integration config template

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Create a local configuration file for integration tests by copying the template file.

```bash
cp tests/integration/integration_config.yml.template tests/integration/integration_config.yml
```

--------------------------------

### community.proxmox.proxmox_kvm — Manage KVM Virtual Machines

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Provides full lifecycle management of QEMU/KVM virtual machines, including creation, cloning, cloud-init provisioning, EFI disk support, and power state control.

```APIDOC
## community.proxmox.proxmox_kvm — Manage KVM Virtual Machines

### Description
Full lifecycle management of QEMU/KVM virtual machines including creation, cloning, cloud-init provisioning, EFI disk support, and power state control.

### Method
`community.proxmox.proxmox_kvm`

### Parameters
#### Common Authentication Parameters
- `api_host` (string) - Required - The Proxmox VE API host.
- `api_user` (string) - Required - The Proxmox VE API user.
- `api_password` (string) - Optional - The Proxmox VE API password. Use `api_token_id` and `api_token_secret` for automation.
- `api_token_id` (string) - Optional - The Proxmox VE API token ID.
- `api_token_secret` (string) - Optional - The Proxmox VE API token secret.

#### VM Specific Parameters
- `name` (string) - Required - The name of the virtual machine.
- `node` (string) - Required - The Proxmox VE node name.
- `memory` (integer) - Optional - The amount of memory in MB.
- `cores` (integer) - Optional - The number of CPU cores.
- `vcpus` (integer) - Optional - The number of virtual CPUs.
- `net` (dict) - Optional - Network interface configuration.
  - `net0` (string) - Example: "virtio,bridge=vmbr0"
  - `net1` (string) - Example: "e1000,bridge=vmbr1"
- `virtio` (dict) - Optional - VirtIO disk configuration.
  - `virtio0` (string) - Example: "local-lvm:30"
  - `virtio1` (string) - Example: "local-lvm:10,format=raw"
- `boot` (string) - Optional - Boot order configuration. Example: "order=virtio0;net0"
- `state` (string) - Optional - The desired state of the VM (`present`, `started`, `stopped`, `restarted`, `absent`). Defaults to `present`.
- `ide` (dict) - Optional - IDE device configuration.
  - `ide2` (string) - Example: "local:cloudinit,format=qcow2"
- `sata` (dict) - Optional - SATA device configuration.
  - `sata0` (string) - Example: "local-lvm:32,format=raw"
- `ciuser` (string) - Optional - The cloud-init user.
- `cipassword` (string) - Optional - The cloud-init user password.
- `sshkeys` (string) - Optional - The SSH public key for the cloud-init user.
- `ipconfig` (dict) - Optional - IP configuration for cloud-init.
  - `ipconfig0` (string) - Example: "ip=dhcp"

### Request Example
```yaml
# Create a VM with virtio disks and dual NIC
- name: Create KVM VM
  community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    name: myvm
    node: pve01
    memory: 4096
    cores: 4
    vcpus: 4
    net:
      net0: 'virtio,bridge=vmbr0'
      net1: 'e1000,bridge=vmbr1'
    virtio:
      virtio0: 'local-lvm:30'
      virtio1: 'local-lvm:10,format=raw'
    boot: "order=virtio0;net0"
    state: present

# Cloud-init VM
- name: Create cloud-init VM
  community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    name: cloud-vm
    memory: 2048
    cores: 2
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    sata:
      sata0: 'local-lvm:32,format=raw'
    ciuser: ubuntu
    cipassword: supersecret
    sshkeys: "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
    ipconfig:
      ipconfig0: 'ip=dhcp'
```
```

--------------------------------

### Install Specific Collection Version

Source: https://github.com/ansible-collections/community.proxmox/blob/main/README.md

Install a specific version of the community.proxmox collection, such as '0.1.0', using ansible-galaxy. This is useful for maintaining compatibility or rolling back to a known stable version.

```bash
ansible-galaxy collection install community.proxmox:==0.1.0
```

--------------------------------

### community.proxmox.proxmox_access_acl

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Manages Access Control Entries (ACEs) on Proxmox paths. This example shows how to revoke all ACEs on a specific path.

```APIDOC
## community.proxmox.proxmox_access_acl

### Description
Revoke all ACEs on a path.

### Parameters
- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **state** (str) - Required - Whether the ACL should be present or absent. Use 'absent' to revoke all ACEs.
- **path** (str) - Required - The path for which to revoke ACEs.
```

--------------------------------

### Run all formatters with Nox

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Execute all configured formatters using Nox to ensure consistent code style across the project.

```bash
nox -Re formatters
```

--------------------------------

### Install Collection from requirements.yml

Source: https://github.com/ansible-collections/community.proxmox/blob/main/README.md

Include the community.proxmox collection in your Ansible project by defining it in a requirements.yml file. This ensures consistent collection versions across your projects.

```yaml
---
collections:
  - name: community.proxmox
```

--------------------------------

### community.proxmox.proxmox_snap

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Snapshot Management: Create, delete, and roll back snapshots for both LXC containers and KVM VMs.

```APIDOC
## `community.proxmox.proxmox_snap` — Snapshot Management

Create, delete, and roll back snapshots for both LXC containers and KVM VMs.

```yaml
# Create a snapshot before patching
- name: Pre-patch snapshot
  community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    description: "Before July 2025 patches"
    state: present

# Create snapshot, keep only last 3
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: rolling-snap
    retention: 3
    state: present

# Rollback
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    state: rollback

# Delete snapshot
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    state: absent
```
```

--------------------------------

### Run all unit tests with Nox

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Execute all unit tests for the collection using Nox.

```bash
nox -Re ansible-test-units-devel
```

--------------------------------

### Run basic sanity tests for all files

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Execute basic sanity tests for all files within the collection using Nox.

```bash
nox -Re ansible-test-sanity-devel
```

--------------------------------

### Manage Snapshots for VMs and Containers with Proxmox Snap Module

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Create, delete, and roll back snapshots for LXC containers and KVM VMs. Supports adding descriptions and managing retention policies.

```yaml
# Create a snapshot before patching
- name: Pre-patch snapshot
  community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    description: "Before July 2025 patches"
    state: present

# Create snapshot, keep only last 3
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: rolling-snap
    retention: 3
    state: present

# Rollback
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    state: rollback

# Delete snapshot
- community.proxmox.proxmox_snap:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 100
    snapname: pre-patch-2025-07
    state: absent
```

--------------------------------

### Create Outbound Firewall Rules at Cluster Level

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Define outbound firewall rules at the cluster level in Proxmox. This example allows outbound TCP traffic to a specific destination. Ensure the `level` is set to `cluster`.

```yaml
- community.proxmox.proxmox_firewall:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    level: cluster
    rules:
      - type: out
        action: ACCEPT
        dest: 8.8.8.8
        proto: tcp
        dport: 443
        enable: true
```

--------------------------------

### community.proxmox.proxmox_sendkey

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Sends keyboard input to a VM console via the Proxmox API.

```APIDOC
## community.proxmox.proxmox_sendkey — Send Keys to VM Console

### Description
Send keyboard input (key sequences or plain text strings) to a VM console via the Proxmox API. Useful for interacting with VM boot menus or pre-OS-boot prompts.

### Parameters
- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **name** (str) - Optional - The name of the VM to send keys to. Use either 'name' or 'vmid'.
- **vmid** (int) - Optional - The ID of the VM to send keys to. Use either 'name' or 'vmid'.
- **keys_send** (list) - Optional - A list of special key sequences to send (e.g., 'ctrl-alt-delete').
- **string_send** (str) - Optional - A string of text to send to the console, including newline characters.
- **delay** (float) - Optional - A delay in seconds between sending keys.
```

--------------------------------

### Update Proxmox Node TLS Certificate from Variables

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

This example shows how to update a Proxmox node's TLS certificate using raw PEM-encoded strings stored in variables. This is useful for managing certificates dynamically.

```yaml
- community.proxmox.proxmox_node:
    api_host: pve.example.com
    api_user: root@pam
    api_password: secret
    node_name: pve01
    certificates:
      certificate: "{{ pve_cert_pem }}"
      private_key: "{{ pve_key_pem }}"
      state: present
```

--------------------------------

### Create a new Proxmox cluster

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Bootstrap a new Proxmox cluster on the first node. Configure cluster name and network links.

```yaml
# Create a new cluster on the first node
- community.proxmox.proxmox_cluster:
    api_host: 10.10.1.1
    api_user: root@pam
    api_password: secret
    state: present
    cluster_name: prod-cluster
    link0: 10.10.1.1
    link1: 10.10.2.1
```

--------------------------------

### Proxmox PCT Remote Connection Plugin Setup

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Configure the `community.proxmox.proxmox_pct_remote` connection plugin to execute Ansible tasks inside LXC containers. This requires SSH access to the Proxmox host and a specific VMID for the container.

```yaml
# inventory/hosts.yml — configure containers as targets
all:
  hosts:
    my-container:
      ansible_host: pve-host.example.com   # PVE host (SSH endpoint)
      ansible_user: ansible                 # SSH user on the PVE host
      ansible_connection: community.proxmox.proxmox_pct_remote
      ansible_pct_id: 101                   # LXC container VMID
      ansible_ssh_private_key_file: ~/.ssh/ansible_pct
```

```yaml
# playbook.yml — use the connection plugin transparently
- name: Configure container
  hosts: my-container
  gather_facts: false
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present

    - name: Copy config file into container
      ansible.builtin.copy:
        src: nginx.conf
        dest: /etc/nginx/nginx.conf
```

--------------------------------

### Add Proxmox Backup Server (PBS) storage

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Integrate Proxmox Backup Server as a storage backend. Provide PBS connection details and the datastore name.

```yaml
# Add Proxmox Backup Server
- community.proxmox.proxmox_storage:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    name: pbs-main
    type: pbs
    content: ["backup"]
    pbs_options:
      server: backup.example.com
      username: backup@pbs
      password: "{{ vault_pbs_password }}"
      datastore: vm-backups
      fingerprint: "F3:04:D2:..."
```

--------------------------------

### Add ZFS pool storage with thin-provisioning

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Configure ZFS pool storage in Proxmox VE, enabling thin-provisioning with the 'sparse: true' option.

```yaml
# Add ZFS pool with thin-provisioning
- community.proxmox.proxmox_storage:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    name: zfs-vms
    type: zfspool
    content: ["images", "rootdir"]
    zfspool_options:
      pool: rpool/data
      sparse: true
```

--------------------------------

### Re-generate virtual environment for formatters

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

If discrepancies are found between local formatting and CI, re-generate the virtual environment for formatters using Nox.

```bash
nox -e formatters
```

--------------------------------

### community.proxmox.proxmox_template

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Manage LXC templates and ISO images in Proxmox VE.

```APIDOC
## community.proxmox.proxmox_template — Manage LXC templates and ISO images

### Description

Download LXC templates from Proxmox appliance repositories, upload local ISO files, or download templates from URLs with checksum verification. This module also supports removing templates.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **node** (str) - Required - The Proxmox node name.
- **storage** (str) - Required - The storage name to use for templates or ISOs.
- **content_type** (str) - Required - The type of content to manage (e.g., `vztmpl`, `iso`).
- **template** (str) - Optional - The name of the template to download or remove.
- **src** (str) - Optional - The path to the local ISO file to upload.
- **url** (str) - Optional - The URL to download a template from.
- **checksum_algorithm** (str) - Optional - The algorithm to use for checksum verification (e.g., `sha256`).
- **checksum** (str) - Optional - The expected checksum of the downloaded file.
- **state** (str) - Optional - Whether the template should be present (`present`) or absent (`absent`). Defaults to `present`.
```

--------------------------------

### Query VM Information with Proxmox VM Info Module

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Retrieve information about VMs or containers. Use 'type' to filter by qemu, lxc, or all. The 'config' parameter can fetch 'none', 'current', or 'pending' configurations.

```yaml
- name: Get all VMs on a node
  community.proxmox.proxmox_vm_info:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    type: qemu        # qemu | lxc | all
  register: vm_list

# Output: vm_list.proxmox_vms is a list of dicts with keys:
# vmid, name, status, cpu, mem, maxmem, node, type, uptime, etc.

- name: Get a specific VM with current config
  community.proxmox.proxmox_vm_info:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    vmid: 101
    config: current   # none | current | pending
  register: vm_detail

- debug:
    msg: "VM {{ vm_detail.proxmox_vms[0].name }} is {{ vm_detail.proxmox_vms[0].status }}"
```

--------------------------------

### Proxmox VE Authentication Parameters

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Demonstrates password and API token authentication for Proxmox VE modules. Credentials can also be set via environment variables.

```yaml
# Password authentication
- community.proxmox.proxmox_vm_info:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: "{{ vault_pve_password }}"
    validate_certs: true
```

```yaml
# API token authentication (preferred for automation)
- community.proxmox.proxmox_vm_info:
    api_host: pve.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ vault_pve_token_secret }}"
    node: pve01
    type: qemu
```

--------------------------------

### Create EVPN SDN zone with BGP

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Set up an EVPN SDN zone in Proxmox, integrating with a BGP controller. `vrf_vxlan` specifies the VXLAN ID for the VRF.

```yaml
# Create an EVPN zone with BGP
- community.proxmox.proxmox_zone:
    api_host: pve.example.com
    api_user: root@pam
    api_password: secret
    zone: evpn-zone
    type: evpn
    state: present
    controller: bgp-controller
    vrf_vxlan: 10000
```

--------------------------------

### Type login credentials into VM console

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Send a string, including newline characters for Enter, to a VM console. A `delay` can be specified to control the typing speed. Useful for automating logins.

```yaml
# Type login credentials into a Linux VM console
- community.proxmox.proxmox_sendkey:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    vmid: 101
    string_send: "root\n"
    delay: 0.5
```

--------------------------------

### Download LXC template from Proxmox appliance repo

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Use this module to download LXC templates from the Proxmox VE appliance repository. Ensure the 'template' parameter matches the desired template name.

```yaml
- community.proxmox.proxmox_template:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    storage: local
    content_type: vztmpl
    template: ubuntu-22.04-standard_22.04-1_amd64.tar.zst
```

--------------------------------

### Clone a VM with Full Copy using Proxmox KVM Module

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Use the proxmox_kvm module to clone an existing VM. Specify the source VM, new VM name, target node, storage, and format.

```yaml
- community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    clone: template-vm
    name: cloned-vm
    node: pve01
    storage: local-lvm
    format: raw
    timeout: 300
```

--------------------------------

### Manually run pre-commit hooks

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Manually execute the pre-commit hooks to check code quality and formatting before committing changes.

```bash
pre-commit run
```

--------------------------------

### Manage KVM Virtual Machines with community.proxmox.proxmox_kvm

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Provides full lifecycle management for KVM virtual machines, including creation, cloning, cloud-init, and power state control. Supports virtio disks and multiple network interfaces.

```yaml
# Create a VM with virtio disks and dual NIC
- name: Create KVM VM
  community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    name: myvm
    node: pve01
    memory: 4096
    cores: 4
    vcpus: 4
    net:
      net0: 'virtio,bridge=vmbr0'
      net1: 'e1000,bridge=vmbr1'
    virtio:
      virtio0: 'local-lvm:30'
      virtio1: 'local-lvm:10,format=raw'
    boot: "order=virtio0;net0"
    state: present
```

```yaml
# Cloud-init VM
- name: Create cloud-init VM
  community.proxmox.proxmox_kvm:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    name: cloud-vm
    memory: 2048
    cores: 2
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    sata:
      sata0: 'local-lvm:32,format=raw'
    ciuser: ubuntu
    cipassword: supersecret
    sshkeys: "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"
    ipconfig:
      ipconfig0: 'ip=dhcp'
```

--------------------------------

### API Token Authentication Variables

Source: https://github.com/ansible-collections/community.proxmox/blob/main/docs/docsite/rst/guides.rst

Use these variables to configure API token authentication. Recommended for production environments.

```yaml
api_host: 10.0.0.1
api_token_id: username@realm!tokenid
api_token_secret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```

--------------------------------

### community.proxmox.proxmox_node

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Manage Proxmox nodes.

```APIDOC
## community.proxmox.proxmox_node — Manage Proxmox Nodes

### Description

Manage node power state, SSL/TLS certificates, DNS configuration, and subscription licenses.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address of the node.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **node** (str) - Required - The name of the Proxmox node to manage.
- **power_state** (str) - Optional - The desired power state of the node (`shutdown`, `reboot`, `reset`).
- **ssl_certificate** (str) - Optional - Path to the SSL certificate file.
- **ssl_private_key** (str) - Optional - Path to the SSL private key file.
- **dns_servers** (list) - Optional - A list of DNS server IP addresses.
- **dns_search_domains** (list) - Optional - A list of DNS search domains.
- **subscription_key** (str) - Optional - The Proxmox subscription key.
```

--------------------------------

### community.proxmox.proxmox_storage

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Manage storage backends in Proxmox VE.

```APIDOC
## community.proxmox.proxmox_storage — Manage Storage Backends

### Description

Add or remove Proxmox VE storage backends, including NFS, iSCSI, PBS, CIFS, ZFS, CephFS, dir, and RBD.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **name** (str) - Required - The name of the storage backend.
- **type** (str) - Required - The type of storage (e.g., `nfs`, `pbs`, `zfspool`).
- **nodes** (list) - Optional - A list of node names where the storage should be available.
- **content** (list) - Optional - A list of content types supported by the storage (e.g., `backup`, `iso`, `images`).
- **nfs_options** (dict) - Optional - Options for NFS storage (e.g., `server`, `export`).
- **pbs_options** (dict) - Optional - Options for Proxmox Backup Server storage (e.g., `server`, `username`, `password`, `datastore`, `fingerprint`).
- **zfspool_options** (dict) - Optional - Options for ZFS storage (e.g., `pool`, `sparse`).
- **state** (str) - Optional - Whether the storage should be present (`present`) or absent (`absent`). Defaults to `present`.
```

--------------------------------

### Download template from URL with checksum verification

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Download a template from a URL and verify its integrity using a checksum. The 'checksum_algorithm' and 'checksum' parameters are required for verification.

```yaml
- community.proxmox.proxmox_template:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    node: pve01
    url: https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img
    checksum_algorithm: sha256
    checksum: "abc123..."
```

--------------------------------

### community.proxmox.proxmox_backup_schedule

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Manage backup job schedules for VMs in Proxmox VE.

```APIDOC
## community.proxmox.proxmox_backup_schedule — Manage Backup Job Schedules

### Description

Add or remove VMs from existing scheduled backup jobs defined in the cluster.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **vm_name** (str) - Optional - The name of the VM to add or remove from the schedule.
- **vm_id** (str) - Optional - The ID of the VM to add or remove from the schedule.
- **backup_id** (str) - Required - The ID of the backup job schedule.
- **state** (str) - Optional - Whether the VM should be present (`present`) or absent (`absent`) in the schedule. Defaults to `present`.
```

--------------------------------

### community.proxmox.proxmox_backup

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Trigger on-demand VM backups in Proxmox VE.

```APIDOC
## community.proxmox.proxmox_backup — Trigger VM Backups

### Description

Start on-demand backups for one, several, or all VMs in a cluster. Supports different backup modes and retention policies.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **mode** (str) - Required - The backup mode (`include`, `all`, `pool`).
- **vmids** (list) - Optional - A list of VM IDs to include in the backup.
- **storage** (str) - Required - The storage name to use for the backup.
- **compress** (str) - Optional - The compression algorithm to use (e.g., `zstd`).
- **backup_mode** (str) - Optional - The backup mode (e.g., `snapshot`).
- **retention** (str) - Optional - The retention policy for backups (e.g., `keep-last=7`).
- **wait** (bool) - Optional - Whether to wait for the backup job to complete. Defaults to `false`.
- **wait_timeout** (int) - Optional - The timeout in seconds for waiting for the backup job. Defaults to `3600`.
- **node** (str) - Optional - The Proxmox node name to run the backup on (used with `mode: all`).
- **pool** (str) - Optional - The resource pool name to backup VMs from (used with `mode: pool`).
```

--------------------------------

### Trigger VM backups to PBS

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Initiate on-demand backups for specific VMs to a Proxmox Backup Server. Configure retention policies and wait for completion.

```yaml
# Backup specific VMs to PBS
- community.proxmox.proxmox_backup:
    api_host: pve.example.com
    api_user: ansible@pve
    api_password: secret
    mode: include
    vmids: [100, 101, 102]
    storage: pbs-main
    compress: zstd
    backup_mode: snapshot
    retention: "keep-last=7,keep-weekly=4,keep-monthly=6"
    wait: true
    wait_timeout: 3600
```

--------------------------------

### Username/Password Authentication Variables

Source: https://github.com/ansible-collections/community.proxmox/blob/main/docs/docsite/rst/guides.rst

Use these variables for username and password authentication. Simplest method, good for development and testing.

```yaml
api_host: 10.0.0.1
api_user: username@realm
api_password: a-strong-password
```

--------------------------------

### Run sanity tests for specific files/directories

Source: https://github.com/ansible-collections/community.proxmox/blob/main/CONTRIBUTING.md

Run basic sanity tests for specified files and directories using Nox, allowing targeted testing.

```bash
nox -Re ansible-test-sanity-devel -- plugins/modules/system/pids.py tests/integration/targets/pids/
```

--------------------------------

### community.proxmox.proxmox_template

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Upload/Manage Templates: Upload or download OS templates (LXC), ISO images, and disk images to Proxmox storage.

```APIDOC
## `community.proxmox.proxmox_template` — Upload/Manage Templates

Upload or download OS templates (LXC), ISO images, and disk images to Proxmox storage.

```yaml

```

--------------------------------

### community.proxmox.proxmox Inventory Plugin

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Dynamically builds Ansible inventory from a live Proxmox cluster.

```APIDOC
## community.proxmox.proxmox Inventory Plugin — Dynamic Inventory

### Description
Builds Ansible inventory from a live Proxmox cluster, grouping VMs and containers by status, tags, pool membership, and custom criteria. Config file must end in `.proxmox.yml` or `.proxmox.yaml`.

### Configuration Options
- **plugin** (str) - Required - Must be 'community.proxmox.proxmox'.
- **url** (str) - Required - The URL of the Proxmox API (e.g., 'https://pve.example.com:8006').
- **user** (str) - Required - The Proxmox API username (e.g., 'ansible@pve').
- **token_id** (str) - Required - The ID of the API token.
- **token_secret** (str) - Required - The secret of the API token. Can be provided via environment variable `PROXMOX_TOKEN_SECRET`.
- **validate_certs** (bool) - Optional - Whether to validate SSL certificates. Defaults to true.
```

--------------------------------

### Create Bond Interface

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Configure a bond interface on a Proxmox node for link aggregation. Specify the bonding mode and slave interfaces. Ensure slave interfaces are available.

```yaml
- community.proxmox.proxmox_node_network:
    api_host: pve.example.com
    api_user: root@pam
    api_password: secret
    node: pve01
    state: present
    iface: bond0
    iface_type: bond
    bond_mode: active-backup
    bond_primary: eth0
    slaves: "eth0 eth1"
```

--------------------------------

### community.proxmox.proxmox_cluster

Source: https://context7.com/ansible-collections/community.proxmox/llms.txt

Create and join Proxmox VE clusters.

```APIDOC
## community.proxmox.proxmox_cluster — Create and Join Clusters

### Description

Bootstrap a new Proxmox cluster or join additional nodes to an existing one.

### Parameters

- **api_host** (str) - Required - The Proxmox API hostname or IP address of the node to manage.
- **api_user** (str) - Required - The Proxmox API username.
- **api_password** (str) - Required - The Proxmox API password.
- **state** (str) - Required - Whether the cluster should be present (`present`) or absent (`absent`).
- **cluster_name** (str) - Optional - The name of the cluster to create.
- **link0** (str) - Optional - The IP address of the first network link for the cluster.
- **link1** (str) - Optional - The IP address of the second network link for the cluster.
- **master_ip** (str) - Optional - The IP address of the master node to join the cluster.
- **fingerprint** (str) - Optional - The fingerprint of the master node's SSL certificate.
```