arensb.truenas.pool_snapshot_task module – Maintain periodic disk pool snapshot tasks.

Note

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

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 arensb.truenas.

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

New in arensb.truenas 1.5.0

Synopsis

  • Creates, deletes, and configures disk pool snapshot tasks.

Parameters

Parameter

Comments

allow_empty

boolean

When true, empty snapshots may be created. This can be useful when there are two overlapping sets of snapshots, e.g., a daily set and a weekly set: the weekly snapshot may be empty because the daily one already contains the changes to the filesystem, but you still want to keep the weekly snapshot when the daily one has expired.

Choices:

  • false

  • true

begin_time

string

Time at which to begin taking snapshots. This is a string in the form “HH:MM”

See also end_time.

dataset

string / required

The name of the dataset to snapshot. This can be a pool, ZFS dataset, or zvol.

day

aliases: date, dom

string

Day of month when the task should run, in cron format.

enabled

string

Whether this snapshot task is enabled.

end_time

string

Time at which to stop taking snapshots. This is a string in the form “HH:MM”

See also begin_time.

exclude

list / elements=string

A list of child datasets to exclude from snapshotting.

If a snapshot task is non-recursive, it may not have an exclude list, so if you specify a non-empty exclude list to a non-recursive task, this module will silently clear it.

hour

string

Hour when the task should run, in cron format.

lifetime_unit

string

A unit of time for the snapshot lifetime before it is deleted. One of the following units of time: hour, day, week, month, year, optionally pluralized.

Along with lifetime_value, specifies the length of time a snapshot will be kept before being deleted.

Choices:

  • "hour"

  • "hours"

  • "day"

  • "days"

  • "week"

  • "weeks"

  • "month"

  • "months"

  • "year"

  • "years"

lifetime_value

integer

The number of units of time that the snapshot will exist before it is deleted. Used in conjunction with lifetime_unit.

match

string / required

A snapshot task does not have a name or other visible unique identifier, so the match option provides a way of specifying which of several tasks the play is configuring, as well as telling whether the task exists yet or not.

The match option is a dict with one or more keywords identifying the task. At least one must be provided.

If the state option is present, only the first matching dataset will be updated. If state is absent, all matching datasets will be deleted.

dataset

string

Name of the dataset being snapshotted. This can be a pool, dataset, or zvol.

name_format

string

This is a regular expression that the name_format option must match. The idea being that you can name your snapshots something like daily-%Y%m%d, and identify them by the prefix, using name_format: ^daily-.

minute

string

Minute when the task should run, in cron format.

month

string

Month when the task should run, in cron format.

name_format

string / required

A template specifying the name of the snapshot. This must include the strings “%Y”, “%m”, “%d”, “%H”, and “%M”. Their meanings are as in strftime: year, month, date, hour, and minute. Other strftime sequences may also be included.

recursive

boolean

Whether to take snapshots of the child datasets, as well as of the dataset itself.

Choices:

  • false

  • true

state

string

Whether the task should exist or not.

Choices:

  • "absent"

  • "present" ← (default)

weekday

aliases: dow

string

Day of week when the task should run, in cron format.

Examples

- name: Hourly snapshots of data/vol1
  hosts: myhost
  collections: arensb.truenas
  become: yes
  tasks:
    - pool_snapshot_task:
        match:
          dataset: data/vol1
          name_format: "hourly-"
        dataset: data/vol1
        # Keep them for 7 days
        lifetime_value: 7
        lifetime_unit: days
        name_format: "hourly-%Y-%m-%d_%H:%M"
        # Snapshot everything under data/vol1, with a couple of exceptions.
        recursive: yes
        exclude:
          - data/vol1/ex1
          - data/vol1/ex2
        # Take snapshots every 2 hours on weekdays
        minute: "*"
        hour: "*/2"
        day: "*"
        month: "*"
        weekday: Mon-Fri

Return Values

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

Key

Description

deleted_tasks

list / elements=string

List of tasks that were deleted when state is ‘absent’.

Returned: success

task

dictionary

A data structure describing a newly-created snapshot task.

Returned: Success, when created.

Sample: {"allow_empty": true, "dataset": "tank", "enabled": true, "exclude": [], "id": 123, "lifetime_unit": "YEAR", "lifetime_value": 1, "naming_schema": "monthly-%Y-%m-%d_%H:%M", "recursive": true, "schedule": {"begin": "00:00", "dom": "1", "dow": "*", "end": "23:59", "hour": "0", "minute": "0", "month": "*"}, "state": {"state": "PENDING"}, "vmware_sync": false}