Summary:
As explained in the VAST REST API Overview, VAST provides extensive REST-based APIs for managing VAST. The VAST management interface (accessible via vcli and via a web browser) is a client to that REST API. You can write your own REST clients to execute the same operations.
In this article, we will collect a large number of small examples that build on what you already know. We are also going to show you how to figure out what the VMS Web UI is doing so that you can write programs that do exactly what VMS does.
Using a Web Browser to Determine VMS REST Calls
The VMS web interface, as well as the VMS CLI, use the VAST REST interface for all of their management activities. This means that you can do the same in your own custom applications. Perhaps the easiest way to understand the API calls made by the management clients is to simply leverage the built-in debugger in many web browsers.
Consider this simple example where we change the export policy for an existing export, all discovered using the built-in Firefox web debugging tools. Other browsers have similar extensions you can download and install.
To start our session, open Firefox and connect to the VMS web UI as normal, including the login. Then enable the built-in web debugger by selecting "Tools --> Web Developer --> Web Console." Once you do this, your screen should split and look something like this (notice the raw HTTP requests at the bottom):
Notice at the bottom that there is a debug window that shows details on each request. Click on the Network tab, and a running stream of HTTP requests from the browser to the VMS REST IP (10.100.127.201 in this example) is displayed - scroll down to see the most recent. You can click on any of those requests and get more details.
Let's modify an existing export (exports are replaced by views in VAST 3.x, but we leave the example as it shows important concepts) to specify a new policy and see what Firefox shows us:
Notice the HTTP PATCH request on the left side sent to /api/exports/9. As it happens the export being modified is export 9 (something you can learn from watching other traffic). On the right side, you see the HTTP headers, but the most interesting tab to look at is Params - this shows you the request sent to VAST:
The JSON document is nicely parsed by Firefox. That's the request sent to VAST - an HTTP PATCH to /api/exports/9 with the body containing the value { "policy_id": 3}. 3 represents the id of the export policy I'm setting on the existing export. The id of course can be learned by looking at other REST requests. At this point you know all you need to form the request. Here is the resulting request shown as a curl command:
curl -X PATCH "https://10.100.127.201/api/exports/5/" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"policy_id\": 3}"Something similar, of course, can be done via Python or any REST client. Remember of course you need to authenticate to curl as described in VAST REST API Overview.
Activating and Deactivating VAST Nodes
You can use the VAST REST API to activate and deactivate C and D nodes. Recall that active/enabled C-nodes respond to clients and execute work, while deactivated C-nodes do not. D-nodes on the other hand handle access to the raw storage from C-nodes. Perhaps you want to automate certain maintenance or testing activities by activating and deactivating nodes. You can easily do so.
Activation
To activate a running C-node, here is an example REST call using CURL. In this example, we are using C-node 4, but of course, you can use whatever node is relevant to your test.
curl -u admin:123456 --insecure -X PATCH "https://VMSVIP/api/cnodes/4/" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"enabled\": true}"D-nodes are similar except the API URL is .../api/dnodes/NUMBER/.
Deactivation
To deactivate a running C-node, here is an example REST call using CURL. In this example, we are using C-node 4, but of course, you can use whatever node is relevant to your test.
curl -u admin:123456 --insecure -X PATCH "https://VMSVIP/api/cnodes/4/" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"enabled\": false}"
Querying for Active Alarms
Here's an example querying for active alarms on a live cluster:
curl -u admin:123456 --insecure -X GET "https://VMSIP/api/alarms/"
[{"id":16,"timestamp":"2022-10-07T21:28:19.978509Z","last_updated":"2022-10-10T21:30:13.658072Z","event":"https://10.61.10.203/api/events/389/","event_definition":"https://10.61.10.203/api/eventdefinitions/214/","object_type":"License","object_id":1,"object_guid":"5b321fde-8237-4279-99c6-7ec764b222d8","object_name":"License-0tn7","cluster":"selab-avnet-203","severity":"MAJOR","alarm_message":"License will expire in 28 days","metadata":{"property":"remaining_days","threshold":28,"object_name":"License-0tn7","cluster_name":"selab-avnet-203"},"acknowledged":false,"event_type":"THRESHOLD","event_name":"LICENSE_REMAINING_DAYS_MAJOR"}]
The alarm above is a license warning, although the output can be a bit difficult to read. Let's run it again with the Python JSON formatter:
curl -u admin:123456 --insecure -X GET "https://VMSIP/api/alarms/" | python3 -m json.tool
[
{
"id": 16,
"timestamp": "2022-10-07T21:28:19.978509Z",
"last_updated": "2022-10-10T21:30:13.658072Z",
"event": "https://10.61.10.203/api/events/389/",
"event_definition": "https://10.61.10.203/api/eventdefinitions/214/",
"object_type": "License",
"object_id": 1,
"object_guid": "5b321fde-8237-4279-99c6-7ec764b222d8",
"object_name": "License-0tn7",
"cluster": "selab-avnet-203",
"severity": "MAJOR",
"alarm_message": "License will expire in 28 days",
"metadata": {
"property": "remaining_days",
"threshold": 28,
"object_name": "License-0tn7",
"cluster_name": "selab-avnet-203"
},
"acknowledged": false,
"event_type": "THRESHOLD",
"event_name": "LICENSE_REMAINING_DAYS_MAJOR"
}
]Creating a View
To create a new view exposing only NFS on an existing VAST cluster against an existing directory using CURL, you would do the following:
curl -u admin:123456 --insecure -X POST "https://VMSIP/api/views/" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"path\":\"/keystest\",\"alias\":\"/keystest3\",\"policy_id\":1,\"protocols\":[\"NFS\"],\"create_dir\":false}"The value of 1 for policy_id is the id of the default policy. You'll need to discover the id of the policy id you want to use of course.
Obviously, this can be enhanced by adding other protocols, such as "SMB", to the list or specifying true for the create_dir parameter. If you don't want to specify an alias, you can specify an empty alias, for example \"alias\":\"\" .
Getting Detailed Information about the Cluster
The REST API provides tremendous detailed information about the cluster. Here's how to get it:
curl -u admin:123456 --insecure -X GET "https://VMSIP/api/clusters/" |python3 -m json.tool
[
{
"id": 1,
"guid": "c34a4dff-31dc-5ed4-95ce-b49087a710fb",
"name": "selab-avnet-203",
"url": "https://10.61.10.203/api/clusters/1/",
"title": "selab-avnet-203",
...
"state": "ONLINE",
"enabled": true,
"physical_space": 310166732637470,
"physical_space_in_use": 8389452734864,
"logical_space": 246147729850368,
"logical_space_in_use": 6671537410271,
"drr": 1.0021759562768755,
"drr_text": "1.0:1",
"physical_space_tb": 310.167,
"physical_space_in_use_tb": 8.389,
"logical_space_tb": 246.148,
...
"logical_space_in_use_tb": 6.672,
"physical_space_in_use_percent": 2.7,
"logical_space_in_use_percent": 2.71,
"logical_drr_percent": 50.0,
"physical_space_wo_overhead": 337137752866816,
"physical_space_in_use_wo_overhead": 6670958783622,
"free_physical_space_wo_overhead": 330466794083194,
"free_physical_space_wo_overhead_tb": 330.467,
"usable_auxiliary_space_in_use": 13906827340.756458,
"usable_capacity_bytes": 245613263220190,
"free_usable_capacity": 238942304436568,
"free_usable_capacity_tb": 238.942,
"usable_capacity_tb": 245.613,
"auxiliary_space_in_use": 17489340655.74369,
"auxiliary_space_in_use_tb": 0.017,
....
}
]
There is information there regarding:
the cluster name
space used - both logical and physical
the DRR rate
space held in auxiliary, which reflects snapshots and recent deletes
replication settings
and so on...
Backup and Recreate Customized Analytics
To Backup
To back up all the definitions of all Analytics and save to a file
curl -u admin:123456 --insecure -X GET https://<VMS-IP>/api/monitors/ | jq . > /tmp/my_analytics.jsonThe resulting JSON file contains a list of JSON objects.
It's a full list of all Analytics on the cluster, including "pre-defined" (by Vast), and "customized" (by you) Analytics.
Each JSON object is a definition for an Analytics
Here is an example of one such definition
{ "id": 69, "object_type": "cluster", "object_ids": null, "prop_list": [ "Capacity,physical_space_in_use", "Capacity,physical_space", "Capacity,logical_auxiliary_space_in_use", "Capacity,auxiliary_space_in_use" ], "monitor_type": null, "time_frame": "2h", "from_time": null, "to_time": null, "granularity": "minutes", "name": "JinTest", "aggregation": null, "query_aggregation": null }
To Recreate
1. Prepare an updated Analytics definition file.
Each file shall contain only definition for one Analytics.
You need to remove the "id" field from the saved JSON definition
Because "id" will be auto assigned on the new cluster.
You can make changes to the definition as you want, such as changing the name to new name.
Here is an example of such file (In this example - /tmp/jintest2.json)
{ "object_type": "cluster", "object_ids": null, "prop_list": [ "Capacity,physical_space_in_use", "Capacity,physical_space", "Capacity,logical_auxiliary_space_in_use", "Capacity,auxiliary_space_in_use" ], "monitor_type": null, "time_frame": "2h", "from_time": null, "to_time": null, "granularity": "minutes", "name": "JinTest2", "aggregation": null, "query_aggregation": null }Notice that I changed the "name" to "JinTest2" as an example
2. Execute RestAPI Call
We can now recreate the Analytics on a Vast cluster by
curl -u admin:123456 --insecure -X POST https://<VMS-IP>/api/monitors/ -H 'Content-Type: application/json' -d @/tmp/jintest2.json
Manipulating Data
Delete a Folder
The ability to delete a folder using the RestAPI has two prerequisites:
Access to the trash folder on the cluster.
Access to one of the authorised users: admin, support or root.
Enabling trash folder access
On the WebUI navigate to Settings > Cluster and select the toggle for "Enable trash folder access".
Perform the deletion
With the prerequisites satisfied, it is now possible to perform the operation. Using a UNIX command shell, execute the command similar to the following:
curl -X DELETE "https://<VMS-VIP>/api/clusters/1/delete_folder/" --data 'path=/path/to/folder' -H "accept: application/json" -u admin:123456 --insecure
Snapshots
Of course, REST can be used to manipulate snapshots
Display all snapshots
curl -X GET "https://<VMS-VIP>/api/snapshots/" -H "accept: application/json" -u admin:123456 --insecure
Create a Snapshot
You can easily create a snapshot using REST by posting to /api/snapshots and specifying the directory to snapshot, the name, and the expiration time. For example, here we create a snapshot of /keystest and name it keystest3 (3rd time!). The time specified is UTC.
curl -X POST https://<VMS-VIP>/api/snapshots/ -H 'Content-Type: application/json' -H "accept: application/json" -d "{ \"name\": \"keystest4\", \"path\": \"/keystest\", \"expiration_time\": \"2021-11-11T20:58:09.000Z\" }" -u admin:123456 --insecure
#response
{"id":18995,"guid":"4e5410b1-dda0-426c-9206-f279429c9554","name":"keystest5","url":"https://10.61.10.201/api/snapshots/18995/","title":"keystest4(/keystest)","path":"/keystest","expiration_time":"2021-11-11T20:58:09Z","cluster":"selab-avnet-201","state":"SUCCEED","policy_id":null,"locked":false,"created":"2021-11-11T19:35:43.171215Z","type":"local","protection_policy_id":null,"eta_sec":4943.161310911179}
Delete a Snapshot
Deleting a snapshot is fairly straightforward. There is, however, one catch - deletes are by id. Thus, you need to find the snapshot id in order to delete it. If the REST API was used to create the snapshot, you'll see the id in the response (shown above). Given the id, here's how to delete it.
curl -X DELETE https://<VMS-VIP>/api/snapshots/18995 -H 'Content-Type: application/json' -H "accept: application/json" -u admin:123456 --insecureQuery by Name
Of course, you can also find a snapshot id by name.
curl -X GET "https://<VMS-VIP>/api/snapshots/?name=keystest3" -u admin:123456 --insecure