everpure.flasharray.purefa_workload module – Manage Fusion Fleet Workloads

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

New in everpure.flasharray 1.33.0

Synopsis

• Apply/Rename/Delete Fusion fleet workloads

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 added in everpure.flasharray 1.36.0	Name of the fleet member on which to perform the workload operation, or the name of the fleet itself. Defaults to the whole fleet. Selecting the fleet means - “the workload with this name, wherever it is in the fleet”. A create is the one exception, because there is nothing to look up. Either specify this or placement, or set recommendation, in which case Fusion chooses the target array. A workload is identified by its name and its member. The same name on two fleet members is two separate workloads, so naming a different member creates a second one rather than moving the first. If two or more members hold the name in the same context (e.g. Fleet), the task is ambiguous and fails naming them, rather than picking one.
disable_warnings boolean added in everpure.flasharray 1.29.0	Disable insecure certificate warnings in debug logs Choices: false ← (default) true
eradicate boolean	whether to eradicate a workload Applies only to state=absent. Any other state is refused. Choices: false ← (default) true
fa_url string	FlashArray management IPv4 address or Hostname.
host string	Host to connect to every volume in the workload after provisioning. With state=absent the host is disconnected from the workload’s volumes instead of the workload being deleted. Only the workload’s own volumes are affected. Volumes the host is connected to outside this workload are never changed. Refused together with rename, which does not disturb connections and connects nothing. Run the two as separate tasks. Default: ""
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 workload.
parameters list / elements=dictionary	Parameter values to apply when creating a workload from the preset. Parameters are only applied on the create path and are not applied when recovering an existing destroyed workload. Any task that does not create is told they were not applied, rather than dropping them silently.
name string / required	Name of the preset parameter to set.
value dictionary / required	Value for the preset parameter. Exactly one of string, integer, boolean, or resource_reference must be provided.
boolean boolean	Boolean parameter value. Choices: false true
integer integer	Integer parameter value.
resource_reference dictionary	Reference to another resource.
id string	ID of the referenced resource.
name string	Name of the referenced resource.
resource_type string	Optional resource type for the reference.
string string	String parameter value.
placement string	Name of the fleet member on which the workload will be deployed. Same as context, so naming both with different members fails. Naming neither this nor context means the whole fleet - see context for what that resolves to, and for the one operation that cannot default. Ignored when recommendation is true, as the recommended target replaces it.
preset string	Name of an existing workload preset to build the workload from. Required to create a workload, and to expand one Presets are fleet objects, named <fleet>:<preset> by the API. Give the bare name; the fleet is prefixed automatically.
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.
recommendation boolean	whether to use the Fusion placement recommendation based on the workload preset definitions during creates. This will use the first recommended placement if more than one is available Only useful during a create. Every other operation works from the member already holding the workload, which is looked up rather than chosen, so setting this there changes nothing. Choices: false ← (default) true
rename string	new name for a workload
state string	Define whether to create or delete a fleet workload. Using the expand option will add volume(s) to the workload. If absent is specified together with a host, rather than deleting the workload, the host will be disconnected from the workload Choices: "absent" "present" ← (default) "expand"
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.
volume_configuration string	Name of the volume configuration to use for adding volumes to a workload
volume_count integer	Number of additional volumes to add to an existing workload Only used with state=expand, where it is required. Must be a positive integer. Zero is rejected.
wait boolean added in everpure.flasharray 1.45.0	Whether to wait for the array to finish provisioning before returning. Cannot be disabled when host is set. A host can only be connected to every volume in a workload once the volume set has settled. Choices: false true ← (default)
wait_timeout integer added in everpure.flasharray 1.45.0	Maximum number of seconds to wait for a single array operation when wait is true. The task fails if that operation has not finished within this time. This bounds each operation individually rather than the task as a whole, so a task that waits for more than one can take a multiple of it. Default: 300

Notes

Note

• 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 workload using an existing preset on a specific placement target and connect to host myhost
  everpure.flasharray.purefa_workload:
    name: foo
    preset: bar
    host: myhost
    placement: arrayB
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a workload using an existing preset using the recommended target and connect to host myhost
  everpure.flasharray.purefa_workload:
    name: foo
    preset: bar
    host: myhost
    recommendation: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a workload on the recommended target, waiting for it to be ready
  everpure.flasharray.purefa_workload:
    name: foo
    preset: bar
    recommendation: true
    wait: true
    wait_timeout: 600
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592
  register: new_workload

- name: Report the fleet member Fusion placed the workload on
  ansible.builtin.debug:
    msg: "{{ new_workload.workload.name }} placed on {{ new_workload.workload.context }}"

- name: Report the volumes the array provisioned
  ansible.builtin.debug:
    msg: "{{ new_workload.workload.volumes }}"

- name: Create a workload using preset parameters
  everpure.flasharray.purefa_workload:
    name: foo
    preset: bar
    context: arr1
    parameters:
      - name: replication_target
        value:
          resource_reference:
            name: arr2
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Add volumes to workload foo based on volume configuration fin and connect to host myhost
  everpure.flasharray.purefa_workload:
    name: foo
    preset: bar
    volume_configuration: fin
    volume_count: 3
    host: myhost
    state: expand
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Add a volume to workload foo, wherever in the fleet it lives
  everpure.flasharray.purefa_workload:
    # Naming neither context nor placement searches the fleet and acts on the
    # member holding foo, so the task does not need to know which one that is.
    name: foo
    preset: bar
    volume_configuration: fin
    volume_count: 1
    state: expand
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Rename an existing workload
  everpure.flasharray.purefa_workload:
    name: foo
    rename: bar
    context: arr1
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Disconnect an existing workload from host
  everpure.flasharray.purefa_workload:
    name: foo
    host: myhost
    state: absent
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Delete an existing workload on a named fleet member
  everpure.flasharray.purefa_workload:
    # Omitting context here would delete foo wherever in the fleet it is found.
    # That works, but name the member when the target matters.
    name: foo
    context: arr1
    state: absent
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Eradicate an existing workload on a named fleet member
  everpure.flasharray.purefa_workload:
    # Eradication cannot be undone, so say which array it applies to. Run it
    # with --check first; the reported context is the array that would lose the
    # workload.
    name: foo
    context: arr1
    state: absent
    eradicate: true
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Recover a deleted workload
  everpure.flasharray.purefa_workload:
    name: foo
    state: present
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Reconnect an existing workload to a host
  everpure.flasharray.purefa_workload:
    name: foo
    host: myhost
    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
workload dictionary	Describes what a task did to the workload. Returned on every action. An eradication leaves nothing to read off, so it reports name and context alone - which workload, and the array it was removed from - and none of the other keys below. The dict is empty only when there was no workload at all, as for state=absent against a name that exists nowhere in the fleet. More detail is available from the array by everpure.flasharray.purefa_info rather than repeated here. Returned: success
completed boolean	Whether the array has finished the operation in flight for this workload. A destroyed workload is complete but still pending eradication - see time_remaining. Returned: success Sample: false
context string	Name of the fleet member the workload is placed on. When recommendation is used this is the target chosen by Fusion. Together with name it identifies the workload - the same name on another fleet member is a different workload. Returned: success Sample: "arrayB"
destroyed boolean	Whether deletion of the workload has been requested. This says nothing about whether the deletion has finished - see completed. Returned: success Sample: false
name string	Name of the workload. This is the new name after a rename. Returned: success Sample: "foo"
status string	Status of the workload, as reported by the array. Normally one of creating, ready, destroying, destroyed, eradicating or recovering. Passed through unmodified, so a future Purity release may report a value not in this list, and null when the array reports no status at all. Use completed to test for completion rather than comparing this field - a null or unrecognised status counts as still in flight and raises a warning. Returned: success Sample: "ready"
time_remaining integer	Milliseconds until a destroyed workload is eradicated. Null unless destroyed is true. A check-mode run that predicts a destroy also reports null, because the countdown only starts once the destroy is applied; a check-mode run that merely reports a workload already destroyed passes the array’s own value through. Returned: success Sample: 86400000
volumes list / elements=string	Names of the volumes belonging to this workload, as they stand after the action. In check mode a create reports an empty list and an expand reports only the volumes that already exist. Returned: success Sample: ["foo-vol1", "foo-vol2"]

Authors

• Everpure Ansible Team (@sdodsley)

Collection links

• Issue Tracker
• Repository (Sources)