purestorage.flasharray.purefa_pgsnap module – Manage protection group snapshots on Everpure FlashArrays

Note

This module is part of the purestorage.flasharray collection (version 1.43.0).

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 purestorage.flasharray. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: purestorage.flasharray.purefa_pgsnap.

New in purestorage.flasharray 1.0.0

Synopsis

  • Create or delete protection group snapshots on Everpure FlashArray.

  • Recovery of replicated snapshots on the replica target array is enabled.

  • Support for ActiveCluster and Volume Group protection groups is supported.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.3

  • purestorage >= 1.19

  • py-pure-client >= 1.26.0

  • netaddr

  • requests

  • pycountry

  • urllib3

Parameters

Parameter

Comments

add_to_pgs

list / elements=string

added in purestorage.flasharray 1.27.0

A volume created from a snapshot will be added to the specified protection groups

api_token

string

FlashArray API token for admin privileged user.

apply_retention

boolean

Apply retention schedule settings to the snapshot

Choices:

  • false ← (default)

  • true

client_id

string

added in purestorage.flasharray 1.43.0

ID of the API Client that issues the identity token.

Used with private_key_file.

context

string

added in purestorage.flasharray 1.33.0

Name of fleet member on which to perform the operation.

This requires the array receiving the request is a member of a fleet and the context name to be a member of the same fleet.

Default: ""

disable_warnings

boolean

added in purestorage.flasharray 1.29.0

Disable insecure certificate warnings in debug logs

Choices:

  • false ← (default)

  • true

eradicate

boolean

Define whether to eradicate the snapshot on delete or leave in trash.

Choices:

  • false ← (default)

  • true

fa_url

string

FlashArray management IPv4 address or Hostname.

id_token

string

added in purestorage.flasharray 1.43.0

A pre-signed JWT to authenticate with, as an alternative to api_token.

The token is exchanged by the array for a short-lived access token.

Requires a matching API Client to be registered on the array (see purestorage.flasharray.purefa_apiclient).

issuer

string

added in purestorage.flasharray 1.43.0

The API Client’s trusted identity issuer registered on the array.

Used with private_key_file.

key_id

string

added in purestorage.flasharray 1.43.0

Key ID of the API Client that issues the identity token.

Used with private_key_file.

name

string / required

The name of the source protection group.

now

boolean

Whether to initiate a snapshot of the protection group immediately

Choices:

  • false ← (default)

  • true

offload

string

Name of offload target on which the snapshot exists.

This is only applicable for deletion and erasure of snapshots

overwrite

boolean

Define whether to overwrite the target volume if it already exists.

Required when restore=all and restoring to an existing protection group.

Choices:

  • false ← (default)

  • true

private_key_file

string

added in purestorage.flasharray 1.43.0

Path to the PEM RSA private key used to sign an identity token, as an alternative to api_token.

Requires client_id, key_id, issuer and username.

private_key_password

string

added in purestorage.flasharray 1.43.0

Password protecting private_key_file, if encrypted.

remote

boolean

Force immediate snapshot to remote targets

Choices:

  • false ← (default)

  • true

restore

string

Restore a specific volume from a protection group snapshot, or use all to restore all member volumes at once.

The protection group name is not required. Only provide the name of the volume to be restored, or all to restore all volumes.

When using all, if restoring to an existing protection group the overwrite parameter must be set to true.

When using all, the target parameter can specify a new or existing protection group name. If not specified, it defaults to the source protection group name.

state

string

Define whether the protection group snapshot should exist or not. Copy (added in 2.7) will create a full read/write clone of the snapshot.

Choices:

  • "absent"

  • "present" ← (default)

  • "copy"

  • "rename"

suffix

string

Suffix of snapshot name.

Special case. If latest the module will select the latest snapshot created in the group

target

string

Volume to restore a specified volume to.

If not supplied this will default to the volume defined in restore

Name of new snapshot suffix if renaming a snapshot

When restore=all, this specifies the target protection group name. If not supplied, defaults to the source protection group name.

throttle

boolean

added in purestorage.flasharray 1.21.0

If set to true, allows snapshot to fail if array health is not optimal.

Choices:

  • false ← (default)

  • true

username

string

added in purestorage.flasharray 1.43.0

Username the issued token should be granted to.

Must be a valid user on the array. Used with private_key_file.

with_default_protection

boolean

added in purestorage.flasharray 1.27.0

Whether to add the default container protection groups to those specified in add_to_pgs as the initial protection of a volume created from a snapshot.

Choices:

  • false

  • true ← (default)

Notes

Note

  • This module requires the purestorage and py-pure-client Python libraries.

  • Additional Python libraries may be required for specific modules.

  • You must set PUREFA_URL and PUREFA_API environment variables if fa_url and api_token arguments are not passed to the module directly.

  • Token-based authentication (id_token, or private_key_file with client_id, key_id, issuer and username) may be used as an alternative to api_token, and requires a matching API Client registered on the array via purestorage.flasharray.purefa_apiclient.

Examples

- name: Create protection group snapshot foo.ansible
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: ansible
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: present

- name: Delete and eradicate protection group snapshot named foo.snap
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: snap
    eradicate: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: absent

- name: Restore volume data from local protection group snapshot named foo.snap to volume data2
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: snap
    restore: data
    target: data2
    overwrite: true
    with_default_protection: false
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: copy

- name: Restore remote protection group snapshot arrayA:pgname.snap.data to local copy
  purestorage.flasharray.purefa_pgsnap:
    name: arrayA:pgname
    suffix: snap
    restore: data
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: copy

- name: Restore AC pod  protection group snapshot pod1::pgname.snap.data to pod1::data2
  purestorage.flasharray.purefa_pgsnap:
    name: pod1::pgname
    suffix: snap
    restore: data
    target: pod1::data2
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: copy

- name: Create snapshot of existing pgroup foo with suffix and force immediate copy to remote targets
  purestorage.flasharray.purefa_pgsnap:
    name: pgname
    suffix: force
    now: true
    apply_retention: true
    remote: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Delete and eradicate snapshot named foo.snap on offload target bar from arrayA
  purestorage.flasharray.purefa_pgsnap:
    name: "arrayA:foo"
    suffix: snap
    offload: bar
    eradicate: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: absent

- name: Rename protection group snapshot foo.fred to foo.dave
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: fred
    target: dave
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: rename

- name: Restore all volumes from protection group snapshot foo.snap (overwrite existing)
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: snap
    restore: all
    overwrite: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: copy

- name: Clone all volumes from protection group snapshot foo.snap to new protection group foo_clone
  purestorage.flasharray.purefa_pgsnap:
    name: foo
    suffix: snap
    restore: all
    target: foo_clone
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
    state: copy

Return Values

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

Key

Description

snapshot

string

Suffix of the created protection group snapshot.

Returned: success

Authors

  • Everpure Ansible Team (@sdodsley)