everpure.flasharray.purefa_qos_policy module – Manage Everpure FlashArray QoS policies

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

New in everpure.flasharray 1.46.0

Synopsis

  • Create, update, rename or delete QoS policies on Everpure FlashArrays and manage the managed directories they are attached to.

  • A QoS policy is a reusable object. It stores an aggregate bandwidth ceiling and an aggregate operations-per-second ceiling, both totaled across all clients of the managed directories it is attached to. The policy has no effect on traffic until it is attached to at least one managed directory.

  • This release covers managed-directory QoS policy only. File server QoS, QoS client-specific rules, QoS priority bands (floors), and block-entity (volume, host, volume group) QoS configuration are out of scope and not managed by this module.

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.

context

string

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: ""

directories

list / elements=string

Desired set of managed directories this policy should be attached to, given as filesystem:directory names.

Declarative. Directories in the list that are not attached to this policy are attached, and directories attached to this policy that are not in the list are detached. An empty list detaches the policy from all directories.

Omit the option to leave the policy’s directory attachments alone. Attachments change only when this option is named explicitly.

A managed directory already governed by a different QoS policy cannot be attached to this one; detach the existing policy first.

disable_warnings

boolean

added in everpure.flasharray 1.29.0

Disable insecure certificate warnings in debug logs

Choices:

  • false ← (default)

  • true

enabled

boolean

If true the policy is enabled.

Defaults to true on creation if not specified.

Choices:

  • false

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

max_total_bytes_per_sec

integer

Aggregate bandwidth ceiling, in bytes per second, totaled across all clients of the managed directories this policy is attached to.

Valid range is 1048576 (1 MiB/s) to 549755813888 (512 GiB/s).

Set to 0 to clear a previously configured limit. Omit the option to leave the current limit untouched on update, or to create the policy with no limit.

max_total_ops_per_sec

integer

Aggregate operations-per-second ceiling, totaled across all clients of the managed directories this policy is attached to.

Valid range is 100 to 100000000.

Set to 0 to clear a previously configured limit. Omit the option to leave the current limit untouched on update, or to create the policy with no limit.

name

string / required

Name of the QoS policy.

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.

rename

string

Value to rename the specified QoS policy to.

The destination name must not already be in use.

Renaming is a standalone operation. Other field changes given in the same task are not applied. Run the module again under the new name to apply them.

state

string

Define whether the QoS policy should exist or not.

absent fails if the policy is still attached to any managed directory. Detach it first (see directories).

Choices:

  • "absent"

  • "present" ← (default)

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.

Notes

Note

  • Requires Purity//FA REST API 2.54 or higher, which is where managed-directory QoS policies and their directory attachments first appear.

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

Examples

- name: Create a QoS policy with both limits
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    max_total_bytes_per_sec: 107374182400
    max_total_ops_per_sec: 10000
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a QoS policy with only a bandwidth ceiling
  everpure.flasharray.purefa_qos_policy:
    name: qos_bandwidth_only
    max_total_bytes_per_sec: 52428800
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Change only the operations ceiling without touching anything else
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    max_total_ops_per_sec: 20000
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Clear the bandwidth ceiling
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    max_total_bytes_per_sec: 0
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Attach a QoS policy to a set of managed directories
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    directories:
      - fs1:dir1
      - fs1:dir2
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Detach a QoS policy from all managed directories
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    directories: []
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Disable a QoS policy without deleting it
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    enabled: false
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Rename a QoS policy
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    rename: qos_platinum
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Delete an unattached QoS policy
  everpure.flasharray.purefa_qos_policy:
    name: qos_gold
    state: absent
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

Authors

  • Everpure Ansible Team (@avk)