everpure.flashblade.purefb_mgmt_role module – Manage FlashBlade custom management roles, permissions, and policy attachment

Note

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

To use it in a playbook, specify: everpure.flashblade.purefb_mgmt_role.

New in everpure.flashblade 1.28.0

Synopsis

  • Manage FlashBlade Management Access Roles and the permissions they grant (object=role).

  • Attach or detach management access policies to a local admin (object=admin_attach) or to a directory-service role mapping (object=ds_attach).

  • Policies and their rules are managed by everpure.flashblade.purefb_mgmt_policy.

  • API-client policy attachment is not covered here; it is managed via the access_policies field on everpure.flashblade.purefb_apiclient.

Requirements

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

  • python >= 3.9

  • py-pure-client

  • netaddr

  • datetime

  • pytz

  • distro

  • pycountry

  • urllib3

Parameters

Parameter

Comments

admin

string

Name of the local admin whose policy list should be reconciled.

Required for object=admin_attach.

The array refuses policy changes on built-in users (such as pureuser); use a local admin created by everpure.flashblade.purefb_user.

api_token

string

FlashBlade API token for admin privileged user.

client_id

string

added in everpure.flashblade 1.26.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: ""

description

string

Free-form description of the role. Applied at creation time only; the FlashBlade REST API does not support editing a role’s description.

disable_warnings

boolean

added in everpure.flashblade 1.18.0

Disable insecure certificate warnings

Choices:

  • false ← (default)

  • true

ds_role

string

Name of the directory-service role mapping whose policy list should be reconciled.

Required for object=ds_attach.

fb_url

string

FlashBlade management IP address or Hostname.

id_token

string

added in everpure.flashblade 1.26.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.flashblade.purefb_apiclient).

issuer

string

added in everpure.flashblade 1.26.0

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

Used with private_key_file.

key_id

string

added in everpure.flashblade 1.26.0

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

Used with private_key_file.

name

string

Name of the custom role. Required for object=role.

Maximum 63 characters. Cannot begin with an underscore (reserved).

object

string / required

What the module operates on.

role manages a custom role and its permissions.

admin_attach attaches or detaches policies on a local admin.

ds_attach attaches or detaches policies on a directory-service role mapping.

Choices:

  • "role"

  • "admin_attach"

  • "ds_attach"

permissions

list / elements=dictionary

Declarative list of permissions on the role. Setting this list adds missing entries and removes any not listed. Identity key is resource; changing actions on an existing resource is a PATCH.

Omit (or set to null) to leave the current permission list untouched.

Provide an empty list to remove every permission from the role.

Built-in (Pure-defined) roles cannot be modified; supplying this option for one fails. Omit it to use the task as a bare existence check on a built-in role.

Only meaningful with object=role.

actions

list / elements=string / required

Allowed verbs on the resource. Any subset of get, post, patch, delete, or the special value all.

all cannot be combined with specific verbs.

Duplicates are rejected.

The array stores all as a grant distinct from the four explicit verbs, even though the effective access is identical today. Re-declaring an existing permission in the other spelling is a real state change and reports changed=true.

all is forward-compatible - verbs added by future Purity releases are included automatically, while an enumerated list stays frozen at the verbs listed.

resource

string / required

Target API resource. Accepted as either the short name (e.g. file-system-snapshots) or the fully-qualified form (e.g. purestorage.com/v2/file-system-snapshots).

policies

list / elements=string

List of management access policy names to attach (with state=present) or detach (with state=absent) from the subject.

Names are matched against the attached policies case-insensitively.

Required for object=admin_attach and object=ds_attach.

private_key_file

string

added in everpure.flashblade 1.26.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.flashblade 1.26.0

Password protecting private_key_file, if encrypted.

state

string

For object=role, whether the role should exist.

For attachment modes, whether the listed policies should be attached (present) or detached (absent). Other policies on the subject are untouched.

Detaching from a subject that does not exist is a no-op; attaching to one fails.

Choices:

  • "absent"

  • "present" ← (default)

username

string

added in everpure.flashblade 1.26.0

Username the issued token should be granted to.

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

Notes

Note

  • You must set PUREFB_URL and PUREFB_API environment variables if fb_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.flashblade.purefb_apiclient

Examples

- name: Create a custom role with one permission
  everpure.flashblade.purefb_mgmt_role:
    object: role
    name: backup-operator
    description: Manages file system snapshots and restores in a realm
    permissions:
      - resource: file-system-snapshots
        actions: [get, post, patch, delete]
    fb_url: 10.10.10.2
    api_token: T-55a68eb5-c785-4720-a2ca-8b03903bf641

- name: Grant a role read-only on a second resource, remove any other permissions
  everpure.flashblade.purefb_mgmt_role:
    object: role
    name: backup-operator
    permissions:
      - resource: file-system-snapshots
        actions: [get]
      - resource: file-systems
        actions: [get]
    fb_url: 10.10.10.2
    api_token: T-55a68eb5-c785-4720-a2ca-8b03903bf641

- name: Delete a custom role
  everpure.flashblade.purefb_mgmt_role:
    object: role
    name: backup-operator
    state: absent
    fb_url: 10.10.10.2
    api_token: T-55a68eb5-c785-4720-a2ca-8b03903bf641

- name: Attach a policy to a local admin
  everpure.flashblade.purefb_mgmt_role:
    object: admin_attach
    admin: svc-automation
    policies: [tenant-a-ops]
    fb_url: 10.10.10.2
    api_token: T-55a68eb5-c785-4720-a2ca-8b03903bf641

- name: Detach policies from a DS role mapping
  everpure.flashblade.purefb_mgmt_role:
    object: ds_attach
    ds_role: tenant-a-admins
    policies: [tenant-a-ops, tenant-a-readonly]
    state: absent
    fb_url: 10.10.10.2
    api_token: T-55a68eb5-c785-4720-a2ca-8b03903bf641

Authors

  • Pure Storage Ansible Team (@avk)