Introducing Storage Management for Proxmox Nodes and Clusters with the new Ansible Module proxmox_storage
(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
o CephFS
o NFS
o CIFS (SMB)
o iSCSI
o Proxmox Backup Server (PBS)
Key Capabilities
o Cluster-wide or node-specific enablement:
Define storage available to every node in the cluster or limit
it to specific hosts with nodes.
o Idempotent storage management:
Use state: present or state: absent for consistency.
o Detailed configuration per storage type:
o CephFS: monhosts, credentials, filesystem, keyrings, paths.
o CIFS: server, share, domain, SMB version, user credentials.
o NFS: server, export path, mount options.
o iSCSI: portal addresses, target names.
o PBS: server, credentials, datastore, fingerprint.
o Content type specification:
VM disks, containers, ISOs, backups, etc.
o 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.
Resources: o Ansible module: proxmox_storage
o Ansible: community.proxmox