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

Note

This module is part of the community.proxmox collection (version 2.0.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 / required

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 / required

Specify the user to authenticate with.

Uses the PROXMOX_USER environment variable if not specified.

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.

client_keyring

string

The client keyring to be used.

fs_name

string

The Ceph filesystem name

monhost

list / elements=string

The hostname or IP address of the monhost.

password

string

The password for the storage system.

path

string

The path to be used within the CephFS.

Default: "/"

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.

password

string / required

The required password for the storage system.

preallocation

string

The preallocation mode for raw and qcow2 images.

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.

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 / required

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.

Choices:

  • "backup"

  • "images"

  • "import"

  • "iso"

  • "rootdir"

  • "snippets"

  • "vztmpl"

dir_options

dictionary

Extended information for adding Directory storage.

path

string / required

The required path of the direcotry on the node(s).

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.

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.

options

string

The options to pass to the NFS service. (e.g., version, pNFS).

preallocation

string

The preallocation mode for raw and qcow2 images.

server

string / required

The required IP address or DNS name of the NFS server.

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.

namespace

string

The namespace to use from the Proxmox Backup Server.

password

string / required

The required password for the Proxmox Backup Server.

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.

pool

string

The required RBD pool name.

state

string

The state of the defined storage type to perform.

Choices:

  • "present" ← (default)

  • "absent"

type

string / required

The storage type/protocol to use when adding the storage.

Choices:

  • "cephfs"

  • "cifs"

  • "dir"

  • "iscsi"

  • "nfs"

  • "pbs"

  • "rbd"

  • "zfspool"

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)

zfspool_options

dictionary

Extended information for adding ZFS storage.

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: none

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"
      export: "/mnt/storage01/b01pbs01"
    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

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)