Proxmox Storage Management via New Ansible Module

(2025-08-13):
Managing Proxmox storage resources at scale has traditionally been a cumbersome task. In clustered environments where consistency, reliability, and speed are critical, manually adding or removing storage definitions on each node wastes valuable time and introduces the risk of human error. Imagine configuring NFS shares, CephFS mounts, iSCSI targets or Proxmox Backup Server repositories across dozens or even hundreds of nodes, each in different locations, and having to repeat the same steps manually or with ad-hoc scripts. It slows down operations, disrupts automation pipelines, and often leads to inconsistencies between nodes.

Until now, there was no clean, supported, and API-driven way to manage storage across Proxmox environments directly within Ansible. This is exactly the gap the new proxmox_storage module fills. Recently added to the upstream community.proxmox Ansible collection, this module introduces a structured and reliable approach to provisioning storage on single Proxmox VE nodes or entire clusters, fully aligned with infrastructure-as-code principles.

The proxmox_storage module supports adding or removing various storage types including CephFS, NFS, CIFS, iSCSI, and Proxmox Backup Server targets through your Ansible playbooks. Whether you are onboarding a single new node or synchronizing a storage change across your entire cluster, it is now just another task in your playbook. No more manual configuration, no risky post-deployment adjustments, and no brittle one-off scripts. Everything is fully automated via the Proxmox API.

It is not just about adding storage. The module ensures idempotent configuration, meaning your storage definitions remain consistent across all nodes and deployments even when you re-run playbooks or update your infrastructure. This allows for repeatable and predictable storage management in CI/CD-driven or large-scale enterprise environments.

Features

The proxmox_storage module provides a unified, API-driven approach to managing storage resources in both individual Proxmox VE nodes and full Proxmox clusters. It eliminates the need for repetitive manual configuration by allowing storage definitions to be created, updated, or removed directly within Ansible playbooks.

Supported Storage Backends

CephFS
NFS
CIFS (SMB)
iSCSI
Proxmox Backup Server (PBS)

Key Capabilities

Cluster-wide or node-specific enablement:
Define storage available to every node in the cluster or limit it to specific hosts with nodes.
Idempotent storage management:
Use state: present or state: absent for consistency.
Detailed configuration per storage type:
- CephFS: monhosts, credentials, filesystem, keyrings, paths.
- CIFS: server, share, domain, SMB version, user credentials.
- NFS: server, export path, mount options.
- iSCSI: portal addresses, target names.
- PBS: server, credentials, datastore, fingerprint.
Content type specification:
VM disks, containers, ISOs, backups, etc.
Full check mode support:
Preview changes without applying.

Examples

Adding Storage to Proxmox


- name: Add PBS storage to Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    api_host: proxmoxhost
    api_user: root@pam
    api_password: password123
    validate_certs: false
    nodes: ["de-cgn01-virt01", "de-cgn01-virt02"]
    state: present
    name: backup-backupserver01
    type: pbs
    pbs_options:
      server: proxmox-backup-server.example.com
      username: backup@pbs
      password: password123
      datastore: backup
      fingerprint: "F3:04:D2:C1:33:B7:35:B9:88:D8:7A:24:85:21:DC:75:EE:7C:A5:2A:55:2D:99:38:6B:48:5E:CA:0D:E3:FE:66"
      export: "/mnt/storage01/b01pbs01"
    content: ["backup"]


- name: Add NFS storage to Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    api_host: proxmoxhost
    api_user: root@pam
    api_password: password123
    validate_certs: false
    nodes: ["de-cgn01-virt01", "de-cgn01-virt02"]
    state: present
    name: net-nfsshare01
    type: nfs
    nfs_options:
      server: 10.10.10.94
      export: "/mnt/storage01/s01nfs01"
    content: ["rootdir", "images"]


- name: Add iSCSI storage to gyptazy Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    api_host: proxmoxhost
    api_user: root@pam
    api_password: password123
    validate_certs: false
    nodes: ["de-cgn01-virt01", "de-cgn01-virt02", "de-cgn01-virt03"]
    state: present
    type: iscsi
    name: net-iscsi01
    iscsi_options:
      portal: 10.10.10.94
      target: "iqn.2005-10.org.freenas.ctl:s01-isci01"
    content: ["rootdir", "images"]

Removing Storage


- name: Remove storage from Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    api_host: proxmoxhost
    api_user: root@pam
    api_password: password123
    validate_certs: false
    state: absent
    name: net-nfsshare01
    type: nfs

Conclusion

The introduction of the proxmox_storage module significantly expands the range of Proxmox VE operations that can be managed through Ansible. By adding native support for provisioning and removing storage across clusters or individual nodes, Ansible becomes an even more powerful orchestrator for Proxmox environments. Tasks that once required manual interaction, custom scripts, or repeated API calls are now standardized, idempotent, and fully integrated into infrastructure-as-code workflows.

This addition demonstrates one of Ansible’s greatest strengths: its ability to grow through community-driven development. Just like the proxmox_node module solved a long-standing licensing challenge, proxmox_storage fills another important automation gap. It makes large-scale Proxmox management more efficient, consistent, and reliable.

It also underlines the real power of open-source solutions. The code is available to everyone, contributions flow back upstream, and new functionality becomes available to the whole community. This kind of collaboration enables sysadmins, DevOps engineers, and infrastructure teams to recreate, adapt, and build upon proven solutions, whether they are working with a small lab or a globally distributed cluster of hundreds of nodes.

In short, this is more than just a new module. It is a step forward in making Proxmox management truly hands-off, repeatable, and enterprise-ready while staying true to the principles of open-source: shared knowledge, collaborative improvement, and the freedom to adapt automation to your exact needs.

You might also want to have a look at my other Ansilbe modules for Proxmox like proxmox_storage for storage management (e.g.: iSCSI, NFS, Ceph), proxmox_node for node management like Proxmox subscriptions, certificates etc., , proxmox_cluster easy creation and joining of Proxmox clusters or even fully automated install images including a Proxmox cloud image to make your sysop life easier.

Resources:

Ansible module: proxmox_storage
Ansible: community.proxmox