damex.incus.incus_storage_volume module – Ensure Incus storage volume

Note

This module is part of the damex.incus collection (version 1.11.10).

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 damex.incus.

To use it in a playbook, specify: damex.incus.incus_storage_volume.

Synopsis

• Create, update, and delete Incus custom storage volumes via the Incus REST API.

• Storage volumes are project-scoped resources within a storage pool.

• The content type is set on creation and cannot be changed afterwards.

Parameters

Parameter	Comments
client_cert string	Client certificate content for remote authentication. Requires url and client_key. Mutually exclusive with token and client_cert_path.
client_cert_path string	Client certificate path for remote authentication. Requires url and client_key_path. Mutually exclusive with token and client_cert.
client_key string	Client key content for remote authentication. Requires url and client_cert. Mutually exclusive with client_key_path.
client_key_path string	Client key path for remote authentication. Requires url and client_cert_path. Mutually exclusive with client_key.
config dictionary	Storage volume configuration key-value pairs. Boolean values are converted to lowercase strings. Default: {}
block.filesystem string	Filesystem type for block volumes.
block.mount_options string	Mount options for block volumes.
block.type string	Block volume format (lvmcluster only). Only used when creating a new volume. Ignored on update. Choices: "raw" "qcow2"
btrfs.compression string	Compression algorithm for the Btrfs volume, e.g. zstd, zstd:3 or none.
lvmcluster.remove_snapshots boolean	Removal of newer snapshots when restoring older snapshot (lvmcluster only). Choices: false true
size string	Size of the storage volume.
snapshots.expiry string	Automatic expiry time for snapshots.
snapshots.pattern string	Pongo2 template for snapshot names.
snapshots.schedule string	Cron expression for automatic snapshots.
zfs.block_mode boolean	Whether to use a ZFS volume as a block device. Choices: false true
zfs.blocksize string	Block size for the ZFS volume.
zfs.delegate boolean	Whether to delegate ZFS dataset to the instance. Choices: false true
zfs.remove_snapshots boolean	Removal of newer snapshots when restoring older snapshot. Choices: false true
zfs.reserve_space boolean	ZFS space reservation equal to config.size (filesystem volumes only). Uses refreservation when zfs.use_refquota is set, reservation otherwise. Choices: false true
zfs.use_refquota boolean	ZFS refquota instead of quota for config.size, so snapshot usage does not count against it (filesystem volumes only). Choices: false true
connection_retry_interval integer	Seconds between connection attempts while waiting for the Incus API. Default: 5
connection_timeout integer	Seconds to wait for the Incus API to become reachable. Covers daemon restarts and dropped connections. Default: 30
content_type string	Content type of the storage volume. Only used when creating a new volume. Ignored on update. Content type cannot be changed after creation. Choices: "filesystem" ← (default) "block"
description string	Storage volume description. Default: ""
name string / required	Name of the storage volume.
pool string / required	Name of the storage pool containing the volume.
project string	Incus project to query. Default: "default"
server_cert string	Server certificate content for remote verification. Requires url. Mutually exclusive with server_cert_path.
server_cert_path string	Server certificate path for remote verification. Requires url. Mutually exclusive with server_cert.
socket_path string	Incus Unix socket path for local connections. Default: "/var/lib/incus/unix.socket"
state string	Desired state of the storage volume. Choices: "present" ← (default) "absent"
target string	Cluster member to create the storage volume on.
token string	Token for remote authentication. Requires url. Mutually exclusive with client_cert.
url string	Remote Incus server URL (e.g. https://host:8443). If specified, connects via HTTPS instead of Unix socket.
validate_certs boolean	Server TLS certificate validation. Choices: false true ← (default)
wait boolean	Async operation completion wait. Set to false for fire-and-forget behaviour. Choices: false true ← (default)

Examples

- name: Ensure filesystem storage volume
  damex.incus.incus_storage_volume:
    pool: default
    name: data

- name: Ensure block storage volume with size
  damex.incus.incus_storage_volume:
    pool: zfs
    name: disk1
    content_type: block
    config:
      size: 50GiB

- name: Ensure storage volume with snapshots
  damex.incus.incus_storage_volume:
    pool: default
    name: backups
    config:
      snapshots.schedule: "@daily"
      snapshots.expiry: 7d

- name: Ensure storage volume in project
  damex.incus.incus_storage_volume:
    pool: default
    name: data
    project: myproject

- name: Ensure storage volume on cluster member
  damex.incus.incus_storage_volume:
    pool: local
    name: data
    target: node1

- name: Ensure storage volume is absent
  damex.incus.incus_storage_volume:
    pool: default
    name: data
    state: absent

Return Values

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

Key	Description
changed boolean	Resource state change indicator. Returned: always
changed_keys list / elements=string	Configuration keys that changed. Returned: always
diff dictionary	Before and after state for diff mode. Returned: changed
after dictionary	State after the change. Returned: success
before dictionary	State before the change. Returned: success
restart_required boolean	Indicator that the Incus daemon must be restarted for changes to take effect. Returned: always

Authors

• Roman Kuzmitskii (@damex)

Collection links

• Issue Tracker
• Repository (Sources)