community.general.zpool module – Manage ZFS zpools

Note

This module is part of the community.general collection (version 12.6.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
Parameters
Attributes
Examples

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`) is 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
    ashift: 12
    compression: lz4
    vdevs:
      - disks:
          - /dev/sda

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

Authors

Tom Hesse (@tomhesse)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/zpool_module.html