How to Query, Sort and Filter FlashArray REST API results using Ansible

Introduction

In a recent post I shared how to create an educational environment to help develop Ansible skills, and provide way of gaining hands-on experience with Pure Storage FlashArray and FlashBlade Ansible modules.

In this post I am going to show how to use the the Ansible URI module to use some of the advanced features provided by Pure Storage REST API services.

REST APIs

The Pure Storage FlashArray provides REST API documentation which is accessible from Help panel on the left hand sidebar, for example Help -> REST 1.X API Guide.

The guide provides high level concepts in the Overview section, with the Resources section providing syntax and code examples for all the APIs.

In the post I will be focusing on the REST API Sorting and Filtering features.

Create Session

Using the Ansible URI module and POST method create a Pure session, providing the URL {{ faUrl }} and API Token {{ apiToken }}, saving the session details for example.

# Create FlashArray session  
  - name: Create FlashArray Session
    uri:
      url: https://{{ faUrl }}/api/1.19/auth/session
      method: POST
      validate_certs: "no"
      return_content: "yes"
      body:
        api_token: "{{ apiToken }}"
      body_format: json 
    register: session

Query Volumes

Using the authenticated session details we can return a list of FlashArray volumes using the Volume REST APIs, to avoid the need for client side sorting we can use the sort parameter, for example.

Sorting Syntax: ?sort=field_name

Field_name can be any of the fields in the response. 
To sort in descending order, append the minus sign (-) to the field name. 
To sort on multiple field names, list the field names as comma-separated values.

The FlashArray REST APIs also supports filtering, we can use this to reduce the number of records returned.

Filtering Syntax: ?filter=field_name operator filed_value

Field_name can be any of the fields in the response. The Operator type of filter match used to compare field_name to field_value.

In the example below I am sorting results by name and filtering results to only return a Volume prefix {{ volPrefix }} and Volume suffix {{ volSuffix }} for example.

# Get FA Volumes, filter and sort
  - name: Get FA Volumes
    uri:
      url: "https://{{ faUrl }}/api/1.19/volume?filter=name='{{ volPrefix }}*'%20and%20name='*{{ volSuffix }}'&sort=name"
      method: GET
      headers:
        Cookie: "{{ session.set_cookie }}"
      validate_certs: "no"
      return_content: "yes"
    register: faVols

Note the use of the %20 within the URL, this is required to avoid issues with the Ansible URI module and spaces within the URL.

FlashArray

Logging onto the FlashArray and navigating to Storage -> Volumes we can see a list of volumes.

Ansible Playbook

Using the code samples above, I have created an Ansible playbook called listVolumes.yaml, you can find this and other example in this GitHub repo.

Run the the playbook with ansible-playbook listVolumes.yaml -e (–extra vars) providing the Volume Prefix, for example.

[oracle@z-oracle oracle-database]$ ansible-playbook listVolumes.yaml -e volPrefix=RED

PLAY [FlashArray Volume List] ***********************************************************************************************************

TASK [Create FlashArray Session] ***********************************************************************************************************
Tuesday 29 March 2022  16:31:25 +0100 (0:00:00.130)       0:00:00.130 ********* 
ok: [localhost]

TASK [Get FA Volumes] ***********************************************************************************************************
Tuesday 29 March 2022  16:31:26 +0100 (0:00:00.824)       0:00:00.955 ********* 
ok: [localhost]

TASK [List filtered FA Volumes] ***********************************************************************************************************
Tuesday 29 March 2022  16:31:26 +0100 (0:00:00.577)       0:00:01.533 ********* 
ok: [localhost] => (item={'source': None, 'promotion_status': 'promoted', 'size': 1099511627776, 'serial': '513519106E354B3702F8AE89', 'created': '2022-03-07T11:39:16Z', 'name': 'RED-Ron', 'requested_promotion_state': 'promoted'}) => {
    "msg": "Found Volume: RED-Ron"
}
ok: [localhost] => (item={'source': None, 'promotion_status': 'promoted', 'size': 536870912000, 'serial': '513519106E354B3702FB9A17', 'created': '2022-03-29T15:30:00Z', 'name': 'RED-Tom', 'requested_promotion_state': 'promoted'}) => {
    "msg": "Found Volume: RED-Tom"
}

PLAY RECAP ***********************************************************************************************************
localhost           : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Tuesday 29 March 2022  16:31:26 +0100 (0:00:00.071)       0:00:01.604 ********* 
=============================================================================== 
Create FlashArray Session ------------------------------------------------ 0.82s
Get FA Volumes ----------------------------------------------------------- 0.58s
List filtered FA Volumes ------------------------------------------------- 0.07s

Or if required provide a Volume Suffix to filter results.

[oracle@z-oracle oracle-database]$ ansible-playbook listVolumes.yaml -e volSuffix=Tom

PLAY [FlashArray Volume List] ***********************************************************************************************************

TASK [Create FlashArray Session] ***********************************************************************************************************
Tuesday 29 March 2022  16:44:01 +0100 (0:00:00.131)       0:00:00.131 ********* 
ok: [localhost]

TASK [Get FA Volumes] ***********************************************************************************************************
Tuesday 29 March 2022  16:44:01 +0100 (0:00:00.793)       0:00:00.924 ********* 
ok: [localhost]

TASK [List filtered FA Volumes] ***********************************************************************************************************
Tuesday 29 March 2022  16:44:02 +0100 (0:00:00.615)       0:00:01.539 ********* 
ok: [localhost] => (item={'source': None, 'promotion_status': 'promoted', 'size': 536870912000, 'serial': '513519106E354B3702FB9A17', 'created': '2022-03-29T15:30:00Z', 'name': 'RED-Tom', 'requested_promotion_state': 'promoted'}) => {
    "msg": "Found Volume: RED-Tom"
}

PLAY RECAP ***********************************************************************************************************
localhost           : ok=3    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   

Tuesday 29 March 2022  16:44:02 +0100 (0:00:00.066)       0:00:01.606 ********* 
=============================================================================== 
Create FlashArray Session ------------------------------------------------ 0.79s
Get FA Volumes ----------------------------------------------------------- 0.62s
List filtered FA Volumes ------------------------------------------------- 0.07s

Summary

In this post I have demonstrated how the Ansible URI module can be used to call the Pure Storage FlashArray REST APIs, and how we can format a URL to sort and limit returned results.

The Ansible URI module provides a great way of interacting with modern infrastructure, services and applications which support REST APIs.

In a future post I will show how we can use the URI module to manage an Oracle database using Oracle REST Data Services (ORDS).

[twitter-follow screen_name=’RonEkins’ show_count=’yes’]