arensb.truenas.filesystem module – Manage ZFS datasets (filesystems/volumes) via TrueNAS middleware

Note

This module is part of the arensb.truenas collection (version 1.11.4).

To install it, use: ansible-galaxy collection install arensb.truenas.

To use it in a playbook, specify: arensb.truenas.filesystem.

Synopsis

  • Create, update, and delete ZFS datasets on TrueNAS using the middleware API.

  • Prevents sending null or invalid fields that cause errors.

  • Normalizes property values so that e.g. ‘64K’ is treated the same as ‘65536’ for volblocksize comparisons. If a user tries to change volblocksize or sparse on an existing volume, the module raises an error (since TrueNAS disallows it).

Parameters

Parameter

Comments

comment

string

Arbitrary comment or notes for the dataset.

create_ancestors

boolean

If True, create any missing parent datasets automatically when creating.

Under TrueNAS CORE, this option is ignored. However, missing ancestors are not created.

Choices:

  • false ← (default)

  • true

force_size

boolean

Whether to ignore checks if the volume size is below thresholds.

Only valid for type=VOLUME.

Choices:

  • false ← (default)

  • true

name

string / required

Full name (ZFS path) of the dataset, e.g. “pool/dataset”.

sparse

boolean

Whether to create a sparse volume (if type=VOLUME).

Cannot be changed after creation.

Choices:

  • false

  • true

state

string

If “present”, ensure the dataset is created/updated.

If “absent”, ensure the dataset is deleted.

Choices:

  • "absent"

  • "present" ← (default)

type

string

Dataset type: FILESYSTEM or VOLUME.

Choices:

  • "FILESYSTEM" ← (default)

  • "VOLUME"

  • "filesystem"

  • "volume"

volblocksize

string

Volume block size if type=VOLUME, e.g. “64K” or “65536”.

Only valid at dataset creation time; cannot be changed on an existing volume.

Choices:

  • "512"

  • "512B"

  • "1K"

  • "2K"

  • "4K"

  • "8K"

  • "16K"

  • "32K"

  • "64K"

  • "128K"

  • "256K"

  • "65536"

volsize

integer

Size of the volume if type=VOLUME.

This can be either an integer, or a string like ‘640K’, ‘32MB’, ‘10GiB’, or ‘1TB’.

Allowable suffixes are:

“K”, “M”, “G”, “T” (powers of 2), “KB”, “MB”, “GB”, “TB” (powers of 10), “KiB”, “MiB”, “GiB”, “TiB” (powers of 2)

This is required when creating a volume, but not when updating an existing one.

Examples

- name: Delete dataset if it exists
  filesystem:
    name: test-expansion/chunkr3
    state: absent

- name: Create volume with 'sparse' = true
  filesystem:
    name: test-expansion/test-iscsi
    type: VOLUME
    volsize: 655360
    volblocksize: "64K"
    sparse: true

Return Values

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

Key

Description

filesystem

dictionary

Dataset properties as returned by the TrueNAS middleware.

Returned: on success

Authors

  • Your Name (@yourhandle)