by Julian Cates

 

There’s an old adage which claims that if you’re going to do a task more than once, it’s probably worthwhile to invest the time up front to write a script for it so that you can reap the time savings with each subsequent iteration of that task. There have historically been many ways to go about this – shell scripts, Perl scripts, batch scripts, PowerShell, PowerCLI, python, etc.  Additionally, today we are also seeing a preponderance of orchestration tools which integrate with disparate IT infrastructure components to perform complex workflows simply and easily. There are seemingly as many ways to automate a task as there are tasks to be automated.

 

One thing that is common to all of these solutions is the need to be able to communicate with each of the components being managed. There have been some elegant ways to interface with various components along with some rather kludgy ones. One means that has gained popularity to the point of ubiquity is that of providing an interface to your component through the use of a RESTful API. Using this API, an administrator can use the scripting or orchestration tool of their choosing in order to interact with infrastructure components in a well-defined, repeatable manner.

 

Now with the introduction of Nimble OS 2.3, you can use the Nimble-provided RESTful API to automate and orchestrate tasks on your Nimble Storage arrays.

 

There are numerous objects which Nimble now exposes through REST.  As of version 2.3, you can now directly manipulate the following:

 

ObjectCreateReadUpdateDelete
Access Control Records
Arrays
Audit Log
CHAP Users
Initiator Groups
Initiators
Jobs
Performance Policies
Pools
Protection Schedules
Protection Templates
Replication Partners
Snapshot Collections
Snapshots
Software Versions
Tokens
Users
Versions
Volume Collections
Volumes

 

In addition to the typical "CRUD" operations, volumes and volume collections have additional operations which allow them to be promoted, demoted, and restored.

 

For a deeper look at all of these object sets, along with the numerous attributes of each which can be manipulated through the RESTful API, I would encourage you to take a look at the Nimble OS API Reference available for download through InfoSight.

 

Now let’s take a look at some example usage. In all instances, the API is accessed through the use of objects written in JavaScript Object Notation (JSON) and the HTTPS protocol. The first step is to submit a JSON object containing a username and password used to authenticate with the array. The array will return an authentication token which is then used with subsequent API calls.

 

 

Using the REST APIs with Linux and Curl

 

Since the objects are submitted via HTTPS, the most straightforward way to demonstrate the functionality is through the use of curl on Linux. In these examples, we’ll also make use of the jq utility, which is a very useful way to parse and visualize the JSON objects which the array returns.

 

In the first example, we’ll obtain a token from the array by submitting our authentication credentials. We’ll need to pass the JSON object containing the username and password. That object in JSON would look like this:

 

{"data":{"password":"mypassword","username":"admin"}}

 

For our example, we’ve assigned this object to a variable called $DATASTRING, and we’re also using a variable for the array name or IP:

rest1.png

 

In the JSON response we receive back from the array, the session_token is what we’re looking for. We will use that token in the header of our future requests. For example, let’s look at how we might go about getting a listing of all the volumes on this particular array. That request would look something like this:

 

curl -k -X 'GET' -H "X-Auth-Token:$TOKEN" https://$ARRAY:5392/v1/volumes 2>/dev/null | ./jq -r .data


To break that down somewhat, we are submitting a GET request through curl and providing a custom header with the –H option.  In this case, we’re using it to submit our authentication token, once again conveniently stored in a variable, $TOKEN. Once again, we’re piping everything to jq in order to help us visualize it.  The abridged output looks like this:

rest2.png

 

Now let’s take it one step further and get all the details about one of our volumes.  We’ll reference it by ID (stored in the $VOLUME variable) in our JSON request:

 

curl -k -X 'GET' -H "X-Auth-Token:$TOKEN" https://$ARRAY:5392/v1/volumes/$VOLUME 2>/dev/null | ./jq -r .data

rest3.png

 

As you can see, there are quite a few volume attributes that can be accessed.  For our last Linux based example, we’ll get a little bit fancy and use jq to just give us a couple of fields that we are interested in – name and size – and use some native Linux tools to sort it alphabetically and apply some formatting to make it easier to read.  The full command line looks like this:

 

curl -k -X 'GET' -H "X-Auth-Token:$TOKEN" https://$ARRAY:5392/v1/volumes/detail 2>/dev/null | ./jq  -r '.data[] | "\(.name) \(.size)"' | sort | awk '{printf "%-50s %s\n", $1, $2}'

rest4.png

 

There you have the Nimble Storage REST API demonstrated in its most primal form. Some of the command lines may look a bit complex at first glance, and mostly this is due to the nature of Linux syntax and the specifics of parsing the response we get back from the array.

Using the REST APIs with Windows PowerShell

 

Next, I’d like to run through some similar examples using my personal favorite means of invoking the APIs – Windows PowerShell.

 

One of the cool things about using PowerShell to access the Nimble REST API is that PowerShell has some built-in functions to format JSON and invoke REST APIs. This makes it incredibly intuitive to use. Let’s take a look at how we might perform a similar task in PowerShell as we did in Linux.  In the following example, we will first obtain an authentication token, and then use that token to obtain a listing of volumes and their sizes.

 

The PowerShell code would look something like this:

 

###########################

# Enable HTTPS

###########################

 

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

 

###########################

# Get Token

###########################

 

$array = "<ARRAYNAME>"

$username = "admin"

$password = "<PASSWORD>"

 

 

$data = @{

       username = $username

       password = $password

}

 

$body = convertto-json (@{ data = $data })

 

$uri = "https://" + $array + ":5392/v1/tokens"

$token = Invoke-RestMethod -Uri $uri -Method Post -Body $body

$token = $token.data.session_token

 

###########################

# Get Volume List

###########################

 

$header = @{ "X-Auth-Token" = $token }

$uri = "https://" + $array + ":5392/v1/volumes"

$volume_list = Invoke-RestMethod -Uri $uri -Method Get -Header $header

$vol_array = @();

 

foreach ($volume_id in $volume_list.data.id){

 

       $uri = "https://" + $array + ":5392/v1/volumes/" + $volume_id

       $volume = Invoke-RestMethod  -Uri $uri -Method Get -Header $header

       $vol_array += $volume.data

 

}

 

###########################

# Print Results

###########################

 

$vol_array | sort-object name | select name,size | format-table -autosize


Executing this powershell code would result in the following:

rest5.png

 

As you can see in these few short examples, whatever your preferred automation or orchestration solution is, using it along with the Nimble REST API is a powerful way to programmatically interact with your storage array. We’ve only just scratched the surface here of what is possible. I would encourage you to grab a copy of the API reference, download the attached ZIP file for many more examples, and then go try your hand at it.

 

And if you come up with something really cool, share it here on the Nimble Connect community. We’d love to see it!