everpure.flasharray.purefa_preset module – Manage Fusion fleet block workload presets

Note

This module is part of the everpure.flasharray collection (version 1.46.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 everpure.flasharray. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: everpure.flasharray.purefa_preset.

New in everpure.flasharray 1.46.0

Synopsis

• Create, replace, rename or delete Fusion fleet workload presets for block (FlashArray volume) workloads.

• A preset is the template that everpure.flasharray.purefa_workload builds a workload from. It names a placement, the volumes to provision there, and optionally QoS limits, snapshot schedules, replication schedules, deploy-time parameters and tags.

• The preset is managed declaratively and as a whole. Every run compares the preset you describe with the preset on the fleet and, when they differ, replaces the fleet’s copy with yours. See the notes for what that means for sections you leave out.

• Only block presets are supported. File presets (directories, exports, quotas), and the bucket and lifecycle sections of newer Purity releases, are not managed by this module, and it refuses to replace a preset that has them.

Requirements

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

• python >= 3.3

• purestorage >= 1.19

• py-pure-client >= 1.88.0

• netaddr

• requests

• pycountry

• urllib3

Parameters

Parameter	Comments
api_token string	FlashArray API token for admin privileged user.
client_id string added in everpure.flasharray 1.43.0	ID of the API Client that issues the identity token. Used with private_key_file.
description string	A brief description of the workload the preset configures. Up to 1024 characters.
disable_warnings boolean added in everpure.flasharray 1.29.0	Disable insecure certificate warnings in debug logs Choices: false ← (default) true
fa_url string	FlashArray management IPv4 address or Hostname.
id_token string added in everpure.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 everpure.flasharray.purefa_apiclient).
issuer string added in everpure.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 everpure.flasharray 1.43.0	Key ID of the API Client that issues the identity token. Used with private_key_file.
name string / required	Name of the preset. Presets are fleet objects that the API names <fleet>:<preset>. Give the bare name. A leading <fleet>: is accepted and removed. Between 1 and 63 characters. Letters, numbers and - only, beginning and ending with a letter or number, and not made up of digits alone.
new_name string	New name for the preset, applied with a rename. Only valid with state=present. The preset name must exist, or already have been renamed to new_name by an earlier run, and new_name must not already be in use by another preset. Any other change in the task is made first, under the old name, and the rename last. If the rename is then refused, the task fails and says that the content was replaced but the rename was not made. Follows the same naming rules as name.
parameters list / elements=dictionary	Values the user is asked for when a workload is created from the preset. Fields that accept a parameter reference use them. Every parameter must be used somewhere in the preset, and every reference must name a parameter defined here.
allowed_values list / elements=string	Values the user may choose from. At most 5. Valid for type=string, up to 64 characters each, and type=integer.
default string	Value used when none is given. For type=integer a whole number. For type=boolean true or false. For type=resource_reference the name of the resource, which must match resource_type. Must be one of allowed_values when those are set, and for an integer between minimum and maximum.
description string	Description of the parameter. Up to 1024 characters.
display_name string	Human-friendly name shown in the GUI. Up to 64 characters.
maximum integer	Largest acceptable value, inclusive. Only valid for type=integer.
minimum integer	Smallest acceptable value, inclusive. Only valid for type=integer.
name string / required	Name of the parameter. Letters, numbers and _ only, unique among the parameters.
resource_type string	Kind of resource the parameter refers to. Required for type=resource_reference and not valid otherwise. Use storage-classes for placement.storage_class and remote-arrays for placement.targets and replications.target. The array fails with an internal error for any other value, so only these two are accepted. The user may choose any resource of that kind. Purity//FA 6.10.6 accepts exactly one allowed value for the parameter, naming only the resource type, and refuses a named resource in it, so there is no option to restrict the choice. A preset on the fleet whose parameter is restricted to named resources differs from the task and is replaced. Choices: "storage-classes" "remote-arrays"
subtype string	Hint to the GUI about the kind of quantity the value is, which it uses to prompt for the value with suitable units. size is for a number of bytes, such as volumes.provisioned_size, and prompts with size units. iops and bandwidth are for the two QoS limits, duration for an interval in milliseconds such as every and keep_for, and time for a time of day in milliseconds since midnight, such as at. Only valid for type=integer. The array refuses a subtype on any other type. The choices are the five values Purity//FA 6.10.6 accepts. The array fails with an internal error for any other value, so a value outside the list is refused before any request is made. Choices: "size" "iops" "bandwidth" "time" "duration"
type string / required	Type of value the parameter collects. Choices: "string" "integer" "boolean" "resource_reference"
placement dictionary	Where the workload’s volumes are deployed. A preset has exactly one placement and every volume uses it. Required when state=present.
name string	Name of the placement configuration. It must be unique among all the configuration names in the preset, whatever their type. Default: "default-placement"
qos string	Name of the entry in qos to apply to the volumes in this placement. The limits are shared by all of the placement’s volumes.
storage_class dictionary / required	The storage class the placement can be deployed to. Give exactly one of name or parameter. A parameter reference written as a template in name is refused. The array does not check that the storage class exists. A misspelt name is accepted when the preset is saved and fails only when a workload is created from it.
name string	Name of the storage class, for example flasharray-x.
parameter string	Name of a parameters entry of type=resource_reference and resource_type=storage-classes, whose value is chosen when a workload is created.
targets list / elements=dictionary	The fleet member the placement is deployed to. At most one. When omitted the target is the fleet member that receives the workload request. Give exactly one of name or parameter in each entry. A parameter reference written as a template in name is refused. Each entry must name a member that exists even when skip_verify_deployable is true. Requires REST API 2.54 or higher.
name string	Name of the fleet member.
parameter string	Name of a parameters entry of type=resource_reference and resource_type=remote-arrays, whose value is chosen when a workload is created.
private_key_file string added in everpure.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 everpure.flasharray 1.43.0	Password protecting private_key_file, if encrypted.
qos list / elements=dictionary	QoS limit configurations. At most one entry. Each must be used by placement.qos.
bandwidth_limit string	Bandwidth limit in bytes per second shared by all the volumes in the placement. From 1048576 (1 MiB/s) to 549755813888 (512 GiB/s). A whole number, or a parameter reference. See the notes for how to write one.
iops_limit string	IOPS limit shared by all the volumes in the placement. Between 100 and 100000000. A whole number, or a parameter reference. See the notes for how to write one.
name string / required	Name of the QoS configuration. It must be unique among all the configuration names in the preset, whatever their type.
naming_template string	Naming template for the QoS policy that is created. When omitted, a configuration that is already on the fleet keeps the template it has, and a new one gets the array’s default. To change the template set it explicitly. To return to the default set it to the default pattern. The default pattern on Purity//FA 6.10.6 is {{functions.left(workload.name, 25)}}-{{functions.left(workload.configuration.name, 25)}}.
replications list / elements=dictionary	Periodic replication (snapshot replication) configurations. At most two entries. Each must be used by at least one entry in volumes.
name string / required	Name of the replication configuration. It must be unique among all the configuration names in the preset, whatever their type.
naming_template string	Naming template for the replication policy that is created. When omitted, a configuration that is already on the fleet keeps the template it has, and a new one gets the array’s default. To change the template set it explicitly. To return to the default set it to the default pattern, which is the same as for qos.
rules list / elements=dictionary / required	The frequency and retention of the replicated snapshots. One or two rules. The same suboptions and rules as snapshots.rules.
at string	Time of day at which to take the snapshot, in milliseconds since midnight. Only valid when every is a whole number of days, and only on the first rule. A whole number, or a parameter reference. See the notes for how to write one.
every string / required	Interval between snapshots in milliseconds. A whole number, or a parameter reference. See the notes for how to write one.
keep_for string / required	How long snapshots are kept before being eradicated, in milliseconds. Must not be shorter than every. A whole number, or a parameter reference. See the notes for how to write one.
suffix string	Snapshot suffix. Can be set on one rule only, the one with the largest keep_for.
target dictionary / required	The remote array snapshots are replicated to. The array accepts any name here, including the array the volume is on, so check it. Give exactly one of name or parameter. A parameter reference written as a template in name is refused.
name string	Name of the remote array.
parameter string	Name of a parameters entry of type=resource_reference and resource_type=remote-arrays, whose value is chosen when a workload is created.
skip_verify_deployable boolean	When true the array makes only the most basic syntax checks, instead of also asking each fleet member whether it could deploy a workload from the preset. Useful for loading a preset that no member can deploy yet, so that it can be edited into shape. This setting is an instruction for the request and is not stored in the preset. It is not part of the comparison made to decide whether the preset changed. Choices: false ← (default) true
snapshots list / elements=dictionary	Snapshot schedule configurations. At most two entries. Each must be used by at least one entry in volumes.
name string / required	Name of the snapshot configuration. It must be unique among all the configuration names in the preset, whatever their type.
naming_template string	Naming template for the snapshot policy that is created. When omitted, a configuration that is already on the fleet keeps the template it has, and a new one gets the array’s default. To change the template set it explicitly. To return to the default set it to the default pattern, which is the same as for qos.
policy_action string	What a workload does about snapshot policies. With always_create creating the workload fails if a policy of the same name exists. With create_or_reuse an existing policy is reused. The array defaults to create_or_reuse. Choices: "always_create" "create_or_reuse" ← (default)
rules list / elements=dictionary / required	The frequency and retention of the snapshots. One or two rules. Intervals of all rules must be multiples of each other. A rule has no time zone. The array refuses one on a FlashArray preset, so there is no option for it.
at string	Time of day at which to take the snapshot, in milliseconds since midnight. Only valid when every is a whole number of days, and only on the first rule. A whole number, or a parameter reference. See the notes for how to write one.
every string / required	Interval between snapshots in milliseconds. A whole number, or a parameter reference. See the notes for how to write one.
keep_for string / required	How long snapshots are kept before being eradicated, in milliseconds. Must not be shorter than every. A whole number, or a parameter reference. See the notes for how to write one.
suffix string	Snapshot suffix. Can be set on one rule only, the one with the largest keep_for.
state string	Define whether the preset should exist or not. present creates the preset, or replaces it when it differs from the task. absent deletes the block preset. A preset that is not a block preset is refused. Workloads that were built from the preset keep working. They are not removed and the array does not stop the preset being deleted while they exist. Choices: "absent" "present" ← (default)
tags list / elements=dictionary	Tags added to workloads built from the preset. Keys must be unique within a namespace.
copyable boolean	Whether the tag is copied when the volume it is on is copied. Choices: false true ← (default)
key string / required	Key of the tag. Up to 64 characters.
namespace string	Namespace of the tag. Namespaces that begin with pure are reserved. Default: "default"
value string / required	Value of the tag. Up to 256 characters, and not empty. The array fails with an internal error for a tag without a value. May be a parameter reference. See the notes for how to write one.
username string added in everpure.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.
volumes list / elements=dictionary	The volumes the preset provisions. Between 1 and 5 entries. Required when state=present. The total number of volumes, the sum of the count values, can be at most 500.
count string	Number of volumes to provision. A whole number, or a parameter reference. See the notes for how to write one. Default: "1"
name string / required	Name of the volume configuration. It must be unique among all the configuration names in the preset, whatever their type.
naming_template string	Naming template for the volumes created from this configuration. When omitted, a configuration that is already on the fleet keeps the template it has, and a new one gets the array’s default. To change the template set it explicitly. To return to the default set it to the default pattern. The default pattern on Purity//FA 6.10.6 is {{functions.left(workload.name, 25)}}-{{functions.left(workload.configuration.name, 25)}}-{{functions.pad_left(workload.configuration.index, 4)}}.
placement string	Name of the placement configuration. Defaults to the one placement in placement, so it only needs setting to make the reference explicit.
provisioned_size string / required	Virtual size of each volume in bytes. Must be a multiple of 512 and at most 4503599627370496 (4 PiB). A whole number, or a parameter reference. See the notes for how to write one.
replications list / elements=string	Names of the entries in replications to apply to these volumes, each at most once.
snapshots list / elements=string	Names of the entries in snapshots to apply to these volumes, each at most once.
workload_type string	The kind of workload the preset configures. Required when state=present. The array accepts any text here without complaint, so the module checks it against the documented list. Choices: "Clarity" "Epic" "Exchange" "File" "MsSQL" "MySQL" "Oracle" "PostgreSQL" "SAP-Hana" "SAP" "VDI" "VSI" "Wfs" "Zerto" "Custom"

Notes

Note

• Requires Purity//FA REST API 2.51 or higher, 2.54 for placement.targets.

• Writing a preset needs a fleet-wide identity, that is a directory user, and an API token made for it. A token made for a local array user can read presets but every write fails with a 403 error, and the module says so.

• The preset is replaced as a whole. Anything you leave out of the task is empty after the run. That is how a section is removed, and it also means an edit made to the preset in the GUI that the task does not describe is lost the next time the task changes something. The one exception is a configuration’s naming template, which is kept when the task leaves it out.

• The module decides whether anything changed by comparing the preset on the fleet, read back from the array, with the preset described by the task. The array spells numbers as text and fills in defaults, which are not counted as differences. A naming template the task leaves out is taken from the configuration of the same name and kind on the fleet, both for the comparison and for the request, so a replacement made for another reason does not reset it.

• Parameter references. Fields that accept one take a value such as {{ parameters.volume_size }}, which the array fills in when a workload is created. Ansible would expand that text itself, so it has to be protected, either by writing the value with the !unsafe tag in YAML or by wrapping it in {% raw %} and {% endraw %}. See the examples.

• Most mistakes that the array would report one at a time, or not at all, are found before any request is made, and reported together. These are references to configurations that do not exist, configurations nothing uses, a name used by two configurations, parameters that are undefined or unused, and the limits. The array does not check placement.storage_class or replications.target, so a wrong value is found only when a workload is created from the preset.

• The module cannot predict whether the array will accept the preset in check mode, only whether it would change. In particular it cannot tell whether placement.targets or skip_verify_deployable would be accepted.

• Supports check_mode and --diff. The difference shown is between the preset on the fleet and the preset described by the task, both in the module’s normalised form, not the exact request.

• Preset names are scoped to the fleet. The module always reads and writes through the fleet, wherever the connection is made.

• This module requires the py-pure-client Python library.

• 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 everpure.flasharray.purefa_apiclient.

See Also

See also

everpure.flasharray.purefa_workload

Manage Fusion Fleet Workloads.

everpure.flasharray.purefa_info

Collect information from Everpure FlashArray.

Examples

- name: Create a preset with one placement and one volume
  everpure.flasharray.purefa_preset:
    name: app-small
    workload_type: Custom
    description: One 1 GiB volume
    placement:
      storage_class:
        name: flasharray-x
    volumes:
      - name: data
        provisioned_size: '1073741824'
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a preset with QoS, a snapshot schedule and a replication schedule
  everpure.flasharray.purefa_preset:
    name: app-protected
    workload_type: PostgreSQL
    placement:
      name: pg-placement
      qos: pg-qos
      storage_class:
        name: flasharray-x
    qos:
      - name: pg-qos
        iops_limit: '50000'
        bandwidth_limit: '1073741824'
    snapshots:
      - name: hourly
        rules:
          - every: '3600000'
            keep_for: '86400000'
    replications:
      - name: offsite
        target:
          name: arrayB
        rules:
          - every: '86400000'
            keep_for: '604800000'
            at: '7200000'
    volumes:
      - name: data
        count: '2'
        provisioned_size: '107374182400'
        snapshots: [hourly]
        replications: [offsite]
    tags:
      - key: app
        value: postgres
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a preset that asks for the size, the storage class and a tag at deploy time
  everpure.flasharray.purefa_preset:
    name: app-flexible
    workload_type: Custom
    parameters:
      - name: vol_size
        type: integer
        subtype: size
        default: '1073741824'
        minimum: 1073741824
        maximum: 1099511627776
      - name: tier
        type: resource_reference
        resource_type: storage-classes
        default: flasharray-x
      - name: env
        type: string
        default: dev
        allowed_values: [dev, test, prod]
    placement:
      storage_class:
        parameter: tier
    volumes:
      - name: data
        # A parameter reference has to be protected from Ansible's own templating.
        provisioned_size: !unsafe '{{ parameters.vol_size }}'
    tags:
      - key: environment
        # The same protection written as a raw block.
        value: "{% raw %}{{ parameters.env }}{% endraw %}"
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Remove the snapshot schedule by leaving it out, because the whole preset is replaced
  everpure.flasharray.purefa_preset:
    name: app-protected
    workload_type: PostgreSQL
    placement:
      name: pg-placement
      qos: pg-qos
      storage_class:
        name: flasharray-x
    qos:
      - name: pg-qos
        iops_limit: '50000'
    volumes:
      - name: data
        provisioned_size: '107374182400'
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Rename a preset and show what would change
  everpure.flasharray.purefa_preset:
    name: app-small
    new_name: app-tiny
    workload_type: Custom
    placement:
      storage_class:
        name: flasharray-x
    volumes:
      - name: data
        provisioned_size: '1073741824'
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
  check_mode: true
  diff: true

- name: Load a preset that no fleet member can deploy yet
  everpure.flasharray.purefa_preset:
    name: app-draft
    workload_type: Custom
    skip_verify_deployable: true
    placement:
      storage_class:
        name: flasharray-x
    volumes:
      - name: data
        provisioned_size: '1073741824'
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Delete a preset
  everpure.flasharray.purefa_preset:
    name: app-small
    state: absent
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

Return Values

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

Key	Description
diff dictionary	The preset before and after, as text, in the module’s normalised form. A naming template the task leaves out is shown on both sides as it is on the fleet. On a rename the old and new names are part of the text, so the change shows even when nothing else differs. Returned: when running with --diff
preset dictionary	Describes the preset after the task. Returned: success
changed_sections list / elements=string	The top-level sections of the preset that the run changed, or in check mode would change. Empty when nothing changed. A create or delete lists every section that was set or unset. Returned: success Sample: ["volume_configurations", "workload_tags"]
name string	Name of the preset. This is the new name after a rename. It is the name that was asked for after a delete, or in check mode when the preset does not exist yet. Returned: success Sample: "app-small"
revision integer	Revision counter the array keeps for the preset. It is null after a delete, and in check mode where the preset does not exist yet. The counter is increased by the array and is not a reliable sign of a change. Use changed. Returned: success Sample: 3

Authors

• Everpure Ansible Team (@sdodsley)

Collection links

• Issue Tracker
• Repository (Sources)