community.general.zpool module – Manage ZFS zpools

Note

This module is part of the community.general collection (version 11.2.1).

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.general.

To use it in a playbook, specify: community.general.zpool.

New in community.general 11.0.0

Synopsis

  • Create, destroy, and modify ZFS zpools and their vdev layouts, pool properties, and filesystem properties.

Parameters

Parameter

Comments

altroot

string

Alternate root for mounting filesystems.

disable_new_features

boolean

If true, disable new ZFS feature flags when creating.

Choices:

  • false ← (default)

  • true

filesystem_properties

dictionary

Dictionary of ZFS filesystem properties to set on the root dataset (for example compression, dedup).

Default: {}

force

boolean

If true, force operations (for example overwrite existing devices).

Choices:

  • false ← (default)

  • true

mountpoint

string

Filesystem mountpoint for the root dataset.

name

string / required

Name of the zpool to manage.

pool_properties

dictionary

Dictionary of ZFS pool properties to set (for example autoexpand, cachefile).

Default: {}

state

string

Whether the pool should exist.

Choices:

  • "present" ← (default)

  • "absent"

temp_name

string

Temporary name used during pool creation.

vdevs

list / elements=dictionary

List of vdev definitions for the pool.

disks

list / elements=path / required

List of device paths to include in this vdev.

role

string

Special vdev role (for example log, cache, spare).

Choices:

  • "log"

  • "cache"

  • "spare"

  • "dedup"

  • "special"

type

string

Vdev topology (for example stripe, mirror, raidz).

Choices:

  • "stripe" ← (default)

  • "mirror"

  • "raidz"

  • "raidz1"

  • "raidz2"

  • "raidz3"

Attributes

Attribute

Support

Description

check_mode

Support: partial

In check mode, any zpool subcommand that supports the dry-run flag (-n) will be run with -n and its simulated output is included in the module’s diff results.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: full

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Create pool "tank" on /dev/sda
  community.general.zpool:
    name: tank
    vdevs:
      - disks:
          - /dev/sda

- name: Create mirrored pool "tank"
  community.general.zpool:
    name: tank
    vdevs:
      - type: mirror
        disks:
          - /dev/sda
          - /dev/sdb

- name: Add a cache device to tank
  community.general.zpool:
    name: tank
    vdevs:
      - disks:
          - /dev/sda
      - role: cache
        disks:
          - /dev/nvme0n1

- name: Set pool and filesystem properties
  community.general.zpool:
    name: tank
    pool_properties:
    ashift: 12
    filesystem_properties:
    compression: lz4
    vdevs:
      - disks:
          - /dev/sda

- name: Destroy pool "tank"
  community.general.zpool:
    name: tank
    state: absent

Authors

  • Tom Hesse (@tomhesse)