community.proxmox.proxmox_storage module – Manage storage in PVE clusters and nodes

Note

This module is part of the community.proxmox collection (version 2.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.proxmox. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.proxmox.proxmox_storage.

New in community.proxmox 1.3.0

Synopsis

• Manage storage in PVE clusters and nodes.

Requirements

The below requirements are needed on the host that executes this module.

• proxmoxer >= 2.3

• requests

Parameters

Parameter	Comments
api_host string	Specify the target host of the Proxmox VE cluster. Uses the PROXMOX_HOST environment variable if not specified.
api_otp string	Specify the OTP. Uses the PROXMOX_OTP environment variable if not specified.
api_password string	Specify the password to authenticate with. Uses the PROXMOX_PASSWORD environment variable if not specified.
api_port integer	Specify the target port of the Proxmox VE cluster. Uses the PROXMOX_PORT environment variable if not specified.
api_timeout integer	Time limit for requests towards the Proxmox VE API. Default: 5
api_token_id string	Specify the token ID. Uses the PROXMOX_TOKEN_ID environment variable if not specified.
api_token_secret string	Specify the token secret. Uses the PROXMOX_TOKEN_SECRET environment variable if not specified.
api_user string	Specify the user to authenticate with. Uses the PROXMOX_USER environment variable if not specified. Default: "root@pam"
btrfs_options dictionary	Extended information for adding BTRFS storage.
format string	Default image format Choices: "raw" "qcow2" "vmdk"
is_mountpoint string	Assume the given path is an externally managed mountpoint and consider the storage offline if it is not mounted. Using a yes/no value serves as a shortcut to using the target path in this field Default: "no"
max_protected_backups integer	Maximal number of protected backups per guest. Use -1 for unlimited.
nocow boolean	Set the NOCOW flag on files. Disables data checksumming and causes data errors to be unrecoverable from while allowing direct I/O. Only use this if data does not need to be any more safe than on a single ext4 formatted disk with no underlying raid system. Choices: false ← (default) true
path string / required	The required path of the directory on the node(s).
preallocation string	Preallocation mode for raw and qcow2 images on file-based storages. The default is metadata, which is treated like off for raw images. Choices: "off" "metadata" "falloc" "full"
prune_backups string	Retention options for backups. For details, see Backup Retention. See https://pve.proxmox.com/pve-docs/vzdump.1.html#vzdump_retention for an overview.
bwlimit string	Set I/O bandwidth limit for various operations (in KiB/s). Format for bwlimit is [clone=<LIMIT>][,default=<LIMIT>][,migration=<LIMIT>][,move=<LIMIT>][,restore=<LIMIT>].
ca_path path	Path to a local certificate, which will be used to verify TLS connections. Ignored if validate_certs=false.
cephfs_options dictionary	Extended information for adding CephFS storage.
format string	Default image format Choices: "raw" "qcow2" "vmdk"
fs_name string / required	The Ceph filesystem name
fuse boolean	Mount CephFS through FUSE. Choices: false true
keyring aliases: client_keyring string	The client keyring to be used.
max_protected_backups integer	Maximal number of protected backups per guest. Use -1 for unlimited.
monhost list / elements=string	The hostname or IP address of the monhost.
options string	The options to pass to the CephFS mount.
password string	The password for the storage system.
path string	The path to be used within the CephFS. Default: "/"
prune_backups string	Retention options for backups. For details, see Backup Retention. See https://pve.proxmox.com/pve-docs/vzdump.1.html#vzdump_retention for an overview.
subdir string	The subdir to be used within the CephFS. The Proxmox default is ‘/’.
username string	The username for the storage system.
cifs_options dictionary	Extended information for adding CIFS storage.
domain string	The required domain for the CIFS share.
format string	Default image format Choices: "raw" "qcow2" "vmdk"
max_protected_backups integer	Maximal number of protected backups per guest. Use -1 for unlimited.
options string	The options to pass to the CIFS mount.
password string	The required password for the storage system.
path string	The mount path of the directory on the node(s).
preallocation string	Preallocation mode for raw and qcow2 images. The default is metadata, which is treated like off for raw images. Choices: "off" "metadata" "falloc" "full"
prune_backups string	Retention options for backups. For details, see Backup Retention. See https://pve.proxmox.com/pve-docs/vzdump.1.html#vzdump_retention for an overview.
server string / required	The required hostname or IP address of the remote storage system.
share string / required	The required share to be used from the remote storage system.
smbversion aliases: smb_version string	The minimum SMB version to use for.
snapshot_as_volume_chain boolean	Enable support for creating snapshots through volume backing-chains. Choices: false true
subdir aliases: subdirectory string	The subdir to be used within the CIFS.
username string	The required username for the storage system.
content list / elements=string	The content types that can be stored on this storage. backup VM backups. images VM disk images. import VM disk images for import. iso ISO images. rootdir container root directories. snippets cloud-init, hook scripts, etc. vztmpl container templates. none do not used directly (for iSCSI). Choices: "backup" "images" "import" "iso" "rootdir" "snippets" "vztmpl" "none"
dir_options dictionary	Extended information for adding Directory storage.
format string	Default image format Choices: "raw" "qcow2" "vmdk"
is_mountpoint string	Assume the given path is an externally managed mountpoint and consider the storage offline if it is not mounted. Using a yes/no value serves as a shortcut to using the target path in this field Default: "no"
max_protected_backups integer	Maximal number of protected backups per guest. Use -1 for unlimited.
path string / required	The required path of the direcotry on the node(s).
preallocation string	Preallocation mode for raw and qcow2 images. The default is metadata, which is treated like off for raw images. Choices: "off" "metadata" "falloc" "full"
prune_backups string	Retention options for backups. For details, see Backup Retention. See https://pve.proxmox.com/pve-docs/vzdump.1.html#vzdump_retention for an overview.
snapshot_as_volume_chain boolean	Enable support for creating snapshots through volume backing-chains. Choices: false true
disable boolean	Flag to disable the storage. Choices: false true
esxi_options dictionary	Extended information for adding ESXi storage.
password string	The password for the ESXi system.
port integer	Use this port to connect to the storage instead of the default one.
server string / required	The required hostname or IP address of the remote ESXi system.
skip_cert_verification boolean	Disable TLS certificate verification, only enable on fully trusted networks. Choices: false true
username string / required	The required username for the ESXi system.
iscsi_options dictionary	Extended information for adding iSCSI storage.
portal string / required	The required hostname or IP address of the remote storage system as the portal address.
target string / required	The required iSCSI target.
iscsidirect_options dictionary	Extended information for adding iSCSI storage.
portal string / required	The required hostname or IP address of the remote storage system as the portal address.
target string / required	The required iSCSI target.
lvm_options dictionary	Extended information for adding LVM storage.
base string	The base volume. This is mostly useful when the LVM volume group resides on a remote iSCSI server.
saferemove aliases: wipe_remove boolean	Called “Wipe Removed Volumes” in the web UI. Zero-out data when removing LVs. Choices: false true
saferemove_stepsize aliases: wipe_remove_stepsize integer	Wipe step size in MiB. Choices: 1 2 4 8 16 32
saferemove_throughput aliases: wipe_remove_throughput string	Wipe throughput (cstream -t parameter value), up to 10 MiB/s by default.
snapshot_as_volume_chain boolean	Enable support for creating snapshots through volume backing-chains. Choices: false true
tagged_only boolean	Only list logical volumes tagged with pve-vm-ID. Choices: false true
vgname string / required	The required LVM volume group name. This must point to an existing volume group.
lvmthin_options dictionary	Extended information for adding LVM-Thin storage.
thinpool string / required	The required name of the LVM thin pool.
vgname string / required	The required LVM volume group name. This must point to an existing volume group.
name string / required	The name of the storage displayed in the storage list.
nfs_options dictionary	Extended information for adding NFS storage.
export string / required	The required path of the NFS export.
format string	Default image format Choices: "raw" "qcow2" "vmdk"
max_protected_backups integer	Maximal number of protected backups per guest. Use -1 for unlimited.
options string	The options to pass to the NFS service. (e.g., version, pNFS).
path string	The mount path of the directory on the node(s).
preallocation string	Preallocation mode for raw and qcow2 images. The default is metadata, which is treated like off for raw images. Choices: "off" "metadata" "falloc" "full"
prune_backups string	Retention options for backups. For details, see Backup Retention. See https://pve.proxmox.com/pve-docs/vzdump.1.html#vzdump_retention for an overview.
server string / required	The required IP address or DNS name of the NFS server.
snapshot_as_volume_chain boolean	Enable support for creating snapshots through volume backing-chains. Choices: false true
nodes list / elements=string	A list of nodes where this storage is available. Required when state=present.
pbs_options dictionary	Extended information for adding Proxmox Backup Server as storage.
datastore string / required	The required datastore to use from the Proxmox Backup Server.
encryption_key string	An existing encryption key for the datastore. Use autogen to generate one automatically without passphrase. Must be provided as a JSON-encoded string.
fingerprint string	The fingerprint of the Proxmox Backup Server system.
master_pubkey string	Base64-encoded, PEM-formatted public RSA key. Used to encrypt a copy of the encryption-key which will be added to each encrypted backup.
namespace string	The namespace to use from the Proxmox Backup Server.
password string	The required password for the Proxmox Backup Server.
port integer	Use this port to connect to the storage instead of the default one.
server string / required	The hostname or IP address of the Proxmox Backup Server.
username string / required	The required username for the Proxmox Backup Server.
rbd_options dictionary	Extended information for adding RBD storage.
data_pool string	The Data Pool (for erasure coding only).
keyring aliases: client_keyring string	The client keyring to be used (for external clusters).
krbd boolean	Always access rbd through krbd kernel module. Choices: false true
monhost list / elements=string	The hostname or IP address of the monhost (for external clusters).
namespace string	The RBD Namespace.
pool string / required	The required RBD pool name.
username string	The RBD Id.
shared boolean	Indicate that this is a single storage with the same contents on all nodes (or all listed in the nodes option). Choices: false true
state string	The state of the defined storage type to perform. Choices: "present" ← (default) "absent"
type string	The storage type/protocol to use when adding the storage. Choices: "btrfs" "cephfs" "cifs" "dir" "esxi" "iscsi" "iscsidirect" "lvm" "lvmthin" "nfs" "pbs" "rbd" "zfs" "zfspool"
update boolean	If true, the Storage will be updated with new value. Choices: false ← (default) true
validate_certs boolean	Validate the TLS certificates used for the connection to the Proxmox VE API. May be set through the environment variable PROXMOX_VALIDATE_CERTS. Choices: false true ← (default)
zfs_options dictionary	Extended information for adding ZFS over iSCSI storage.
blocksize string / required	The ZFS blocksize parameter. A power of 2 with optional k or m suffix.
comstar_hg string	The host group for comstar views. Only for zfs_options.iscsiprovider=comstar.
comstar_tg string	The target group for comstar views. Only for zfs_options.iscsiprovider=comstar.
iscsiprovider string / required	The iSCSI target implementation used on the remote machine. LIO and iet for Linux. istgt for FreeBSD. comstar for Solaris. Choices: "LIO" "iet" "istgt" "comstar"
lio_tpg string	The target portal group for Linux LIO targets. Only for zfs_options.iscsiprovider=lio.
nowritecache boolean	Disable write caching on the target. Choices: false true
pool string / required	The required name of the ZFS pool to use.
portal string / required	The required hostname or IP address of the remote storage system as the portal address.
sparse boolean	Use ZFS thin-provisioning. Choices: false true
target string / required	The required iSCSI target.
zfs_base_path string	Base path where to look for the created ZFS block devices. Set automatically during creation if not specified. Usually /dev/zvol.
zfspool_options dictionary	Extended information for adding ZFS storage.
blocksize string	The ZFS blocksize parameter. A power of 2 with optional k or m suffix.
mountpoint string	The mount point of the ZFS pool/filesystem.
pool string / required	The required name of the ZFS pool to use.
sparse boolean	Use ZFS thin-provisioning. Choices: false true

Attributes

Attribute	Support	Description
action_group	Action group: community.proxmox.proxmox	Use group/community.proxmox.proxmox in module_defaults to set defaults for this module.
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

Authentication

Complete guide for the Proxmox API authentication

Examples

- name: Add PBS storage to Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    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"
    content: ["backup"]

- name: Add NFS storage to Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    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 Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    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"]

- name: Remove storage from Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    state: absent
    name: net-nfsshare01
    type: nfs

- name: Add ZFS storage to Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    state: present
    name: zfspool-storage
    type: zfspool
    content: ["rootdir", "images"]
    zfspool_options:
      pool: rpool/data
      sparse: true

- name: Update ZFS storage on Proxmox VE Cluster
  community.proxmox.proxmox_storage:
    state: present
    name: zfspool-storage
    type: zfspool
    content: ["images"]
    zfspool_options:
      pool: rpool/data
      sparse: true
    update: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
storage string	Status message about the storage action. Returned: success Sample: "Storage 'net-nfsshare01' created successfully."

Authors

• Florian Paul Azim Hoberg (@gyptazy)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication