Using the XtremIO REST API

In Part 1 of Using the XtremIO REST API I covered how to access the API, and how to read data from it. Part 2 covered how to create and modify objects. Next up is the function most people want to use from the API - Snapshots!

Before attempting to use snapshots, it's worth understanding a little about the XtremIO Snapshot Refresh implementation by reading my previous post on XtremIO Snapshot Refresh.

The majority of operations regarding snapshots are done using one of two URIs - /api/json/v2/types/snapshots and /api/json/v2/types/snapshot-sets. There are also a number of URI's for things like managing Consistency Groups - these work like most other objects so are not specifically covered here.

Creating a Snapshot

Creating a snapshot is fundamentally no different to creating any other object - a POST request to the snapshot URI, with a body containing the details of what you want to take a snapshot of. The source of the snapshot can be either a consistency group (consistency-group-id), an existing snapshot set (snapshot-set-id), one or more volumes (volume-list), or volumes tagged with one or more tags (tag-list). In general, using a consistency group or a snapshot set are going to be the cleanest option, especially if you intent to do any refresh options on the set in the future.

You can also optionally specify the name of the Snapshot Set that will be created when the snapshot is taken (snapshot-set-name), the snapshot type (snapshot-type, read/write or readonly), and the suffix that will be added to the source volume names to form the snapshot volume names (snap-suffix).

For example, to create a new snapshot of the volumes in the "OracleCG" consistency group, and call the resulting snapshot set "OracleSnap1" we could use :

[scott ~]$ curl -X POST -d '{"consistency-group-id":"OracleCG","snapshot-set-name":"OracleSnap1"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshots
{
    "links": [
        {
            "href": "https://xms/api/json/v2/types/snapshots/36",
            "rel": "self"
        },
        {
[...trimmed...]
}

The result is a JSON blob that contains links to each of the snapshot volumes created as a part of the snapshot operation.

Deleting a Snapshot

Deleting a snapshot is exactly the same as deleting a volume or any other object - just use the DELETE method with the full URI for the object you want to delete.

It is also possible to simply delete the snapshot set, which will delete all of the snapshot volumes within that snapshot set, as well as the set itself. The syntax is the same as other deletes, just a DELETE method request against the relevant snapshot set object (eg, /api/json/v2/types/snapshot-sets/6 or /api/json/v2/types/snapshot-sets?name=MySnapSet)

Refreshing a Snapshot

Unlike in the CLI, there is no separate command to refresh a snapshot - it's just the same request as creating the snapshot in the first place, only with different options in the body. The REST API guide has a list of all of the possible options in the table titled "Create Snapshot and Reassign", and those options correspond exactly to the equivalent options in the CLI version of the command.

For example, above we took a snapshot of the consistency group "OracleCG" with a resulting snapshot set "OracleSnap1". In order to refresh the snapshot with a new copy of the primary volumes, we would use :

[scott ~]$ curl -X POST -d '{"from-consistency-group-id":"OracleCG","to-snapshot-set-id":"OracleSnap1","no-backup":"true"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshots
{
    "links": [
        {
            "href": "https://xms/api/json/v2/types/snapshots/40",
            "rel": "self"
        },
        {
[...trimmed...]
}

We are asking the data to be "refreshed" FROM the volumes in the consistency group OracleCG, TO the volumes in the snapshot set OracleSnap1, and for the 'backup' volumes that are created as a part of the process (ie, the original volumes before the snapshot and reassign) to be removed.

What is returned is a list of the "new" snapshot volumes taken as a part of the refresh. As per the refresh process these volumes will have the same names/NAA/SCSI IDs/etc as the original snapshots, so from the host perspective they will appear to be the same volumes - even thought we know that they are actually new snapshots volumes!

Note that whilst the "no-backup" attribute requires a value, the value itself is ignored - any value passed will result in the backup volume being deleted.

Refresh and Snapshot Set names

One of the side effects of the way snapshot refresh works is that name of the snapshot set the volumes are in after the refresh is different to the one before the refresh.

Whilst this is by design, it can be a little confusing, especially if you want to be able to use a consistent command when refreshing a snapshot multiple times.

Thankfully there is an easy way to handle this - simply rename the snapshot set after (or even before) the refresh has been been completed.

eg, First refresh the snapshot set, giving the resulting snapshot set a new (fixed) name :
curl -X POST -d '{"from-consistency-group-id":"OracleCG","to-snapshot-set-id":"OracleSnap1","no-backup":"true","snapshot-set-name":"OracleSnap1-tmp"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshots

Then once the refresh is complete, rename the new snapshot set back to the old name. Note that a rename is a change on an existing object, so it's a PUT operation :
curl -X PUT -d '{"new-name":"OracleSnap1"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshot-sets?name=OracleSnap1-tmp

Although the snapshot refresh operation is instantaneous, the process of deleting the old snapshot set can take a few seconds, so it's advisable to put a delay of at least a few seconds between the above to commands to allow time for the old snapshot set to be deleted before attempting to re-use its name.

Alternatively, you can rename the existing set first, and then refresh using the final name which removes the need to include a delay. eg :

curl -X PUT -d '{"new-name":"OracleSnap1-old"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshot-sets?name=OracleSnap1

curl -X POST -d '{"from-consistency-group-id":"OracleCG","to-snapshot-set-id":"OracleSnap1-old","no-backup":"true","snapshot-set-name":"OracleSnap1"}' -u admin:Xtrem10 -k -s https://xms/api/json/v2/types/snapshots

(Note that the API Snapshot Set rename feature does not work in XtremIO version 4.0.0/4.0.1 - upgrade to 4.0.2 or later if you're running one of those versions)

Next up, Part 4 - Best Practices