NAME
gyptazy - it's all about FreeBSD, Proxmox, BGP and Coding!

OPTIONS

CONTENT

Proxmox Storage Management with Ansible via proxmox_storage Module

():

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 and finally provides an API-driven storage management for Proxmox based systems.

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.

Why Proxmox Storage Management Needs Ansible Automation

Storage is one of the most critical and stateful components in any Proxmox VE environment. In clustered setups, storage definitions must be identical across all nodes to guarantee predictable behavior for virtual machines, containers, backups, and migrations. Even small inconsistencies can lead to failed deployments, unavailable storage, or unexpected runtime issues.

While Proxmox provides a powerful API and web interface, managing storage manually does not scale. Adding or modifying NFS shares, CephFS mounts, iSCSI targets, or Proxmox Backup Server repositories across multiple nodes quickly becomes repetitive, error-prone, and difficult to audit. As clusters grow, this operational overhead increases exponentially.

Ansible addresses these challenges by introducing declarative, idempotent automation. Instead of applying changes manually, storage configurations are defined once in code and consistently enforced across nodes and clusters. This ensures that every Proxmox host converges to the same desired state, regardless of how often playbooks are executed.

By combining Ansible with a native, API-driven module like proxmox_storage, storage management becomes part of a reproducible infrastructure-as-code workflow. Changes are version-controlled, reviewable, and fully automatable, making Proxmox storage provisioning reliable, scalable, and suitable for CI/CD-driven or enterprise environments.

Key Features of the Ansible proxmox_storage Module

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

The proxmox_stroage module support various different backends like:

Key Capabilities

The key capatabilities represent in:

Ansible Examples for Managing Proxmox Storage

Within this section you can find further examples of the module's usage like adding or removing different storage backends.

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: Idempotent Storage Management for Proxmox with Ansible

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.

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.

You might also want to have a look at my other Ansible modules for Proxmox like proxmox_storage, proxmox_node, proxmox_cluster or even fully automated Proxmox install images.

Resources