Getting Started with the PowerMax REST API: Time for a REST
Mon, 13 Mar 2023 18:24:33 -0000
|Read Time: 0 minutes
So, a few years down the line and over 15,000 views later, I’ve decided to refresh my infamous “Time for a REST” post and put it in a new, permanent location on Info Hub. The original site has been retired, so I’ve rewritten and updated the post here.
This blog post will not teach you Python, and it assumes basic programming skills. I recommend Learn Python the Hard Way—It’s totally free. If you want to dig deeper, the $60 course at RealPython.com is a worthwhile investment in yourself.
This blog post covers some basics on REST. If you want to explore it further, there’s a mountain of information available. You could even ask ChatGPT, which is all the rage at the moment.
I will, however, give a brief overview here. If you already know about REST and just want to know about the PowerMax REST API, you can just skip the next section.
What is REST API?
REST, which stands for Representational State Transfer, is an architectural style of shaping web services. It is not a standard but, rather, a style describing the act of transferring a state of something by its representation. An API s a set of routines, protocols, and tools for building software applications. An API specifies how software components should interact and are used when programming UI components. Basically, REST API gives you a way of interacting with an application without having to know every detail about how the underlying application is implemented.
Why REST? I can think of more than a few reasons, but here are some of my top reasons for using REST:
- Simplicity—REST is based on HTTP protocols. If you know how to use a web browser by entering an address to get information from a website, you already know a little about REST.
- Industry Standard—REST is widely used everywhere. Look at any web application out there —for example, Service Now, Amazon, maps.com, weatherchannel.com, to name but a few —and you’ll probably find that it has a REST API. REST is very lightweight and easy to get started with. Pretty much every enterprise application provides a REST interface and a way to connect and get information to other REST APIs.
- Choice—You’re not stuck with one toolset; you can use any programming language you’re already familiar with to work with REST. This means that you don’t have to retool if you don’t want to; however, there are great tools out there that might persuade you to choose one language over another. Modern languages, like Python for example, are easy to learn and have a ton of resources and packages already written to help.
- Versatility—Providing a REST interface into our products makes it very easy for people to plug in and build on the work that’s already engineered into the system. It also enables other vendors and customers to build tools that interface with the PowerMax REST API and increase options for customers.
This YouTube video gives a great explanation of other REST APIs and some ideas about how to use them: REST API concepts and examples.
REST is really what makes automation possible. The PowerMax REST API enables storage configurations to be dynamic and automated through Infrastructure as Code (IaC) tools such as Ansible, Terraform, Puppet, and so on.
REST is also very useful for reporting and data mining; we have many customers pulling information from the system into tools such as Splunk and Grafana.
Types of REST calls
REST is all about state—getting the states of objects, creating new objects by providing their representative state, and changing the state of an existing object or deleting the object.
Unisphere for PowerMax REST API supports the following types of REST calls:
- GET—Get state information on objects.
- POST—Call to create an object.
- PUT—Make an edit to an object’s state. Typically, you have to do a GET to ensure that you have all the information before you can do a PUT.
- DELETE—Remove object.
For more general information about REST, check out Getting Started with REST API.
Securing your REST API access
Security is always a concern, and working with REST APIs you will need to authenticate. The method might be different, depending on the API, Some APIs will work with tokens, while others will work with username and password (Basic Authentication).
For the PowerMax REST API, each call is verified with Basic Authentication over HTTPS by username and password. With this authentication method, users can have granular roles, and their REST calls can be limited to specific arrays/storage groups and functions. For example, a user could be set up so that the user can only create snapshots for a specific set of storage groups. For more information about role-based access, see the Unisphere for PowerMax API documentation.
What can I do with the PowerMax REST API?
Before we get into making an API call, it’s worth looking at what can be done with the PowerMax REST API. The following figure gives a high-level overview of the main tasks that you can perform. In addition to the components shown, there is a migration API, Workload Planner API, and vVOL API.
Storage group based control with PowerMax REST API
Unisphere for PowerMax is designed around the concept of the storage group for management of applications. A storage group is a container for a set of devices that are related in some way, usually representative of an application or a tenant with data on the PowerMax array.
Most operations using REST API are built to take advantage of the storage group as a control entity—for example, SnapVX and SRDF. Using a storage group for management reduces the number of objects that storage administrators need to manage. A storage group must exist for masking devices to a host for access through the SAN so that REST can take advantage of this construct.
Some legacy processes might need to be re-worked so that they fit into the storage group operation workflows. Historically, operating systems reacted badly to volumes being removed and re-added; however, modern operating systems are no longer sensitive to these types of changes.
Accessing the PowerMax API documentation and schema
Now that we’ve covered the bare bones of REST and some of what’s possible with the PowerMax REST API, we can look at making an actual REST API call. To make a REST call, you will need to know the structure of the API schema.
All REST API schemas for Dell products are published on https://developer.dell.com. This site provides for unrestricted access to assist developers who might not have access to Dell support materials. From the overview section, the documentation, which includes sample payloads and responses, can be downloaded in an OpenAPI.json file, or you can browse the documentation on the site.
The PowerMax API is organized by functional resource. Each API call is prepended with https://{{ipaddress|hostname}}/univmax/restapi, where ipaddress|hostname is the Unisphere for PowerMax server address managing the array that you want to control or gather information about. This section of the URI is known as the Base URI.
Depending on what you want to do next, you will need to look at the documentation and follow the resource tree. Any active management API call to the PowerMax array will have a version that is specified after the URI, for example: https://{{ipaddress|hostname}}/univmax/restapi/{{API_version}}/sloprovisioning/symmetrix
This API call will find information about what arrays are managed by the Unisphere server.
Making a REST call
A simple GET call using the Client for URL tool cURL looks something like this:
curl --url https://UnipshereIPaddress:8443/univmax/restapi/version --insecure -u username:verysecretpassword
States are transmitted and received in JSON. JSON stands for JavaScript Object Notation. JSON is easily readable, consisting of key value pairs. The key is on the left, and the value is on the right, with : separating key and value.
The response to the GET version API call above is a JSON payload containing the version of Unisphere, the current API version, and a list of supported API versions. Here’s an example:
{ "version": "T10.0.1.448", "api_version": "100", "supported_api_versions": [ "100", "92", "91" ] }
Making a POST or PUT call either creates or updates an object on the PowerMax array. Unlike a GET call, which is much simpler, you need to send a payload describing the object you want to create or the changes you want to make.
curl -X PUT \ -H "Content-Type: application/json" \ -H "Authorization: Basic <base64 encoded username:password>" \ -d ' { "executionOption": "SYNCHRONOUS", "storageGroupId": "API_Created_SG", "srpId": "SRP_1", "sloBasedStorageGroupParam": [ { "volumeAttributes": [ { "capacityUnit": "TB", "volume_size": "1", "num_of_vols": 2, "volumeIdentifier": { "volumeIdentifierChoice": "identifier_name", "identifier_name": "API_Created_1TB_Volume" } }, { "capacityUnit": "GB", "volume_size": "1", "num_of_vols": 2, "volumeIdentifier": { "volumeIdentifierChoice": "identifier_name", "identifier_name": "API_Created_1GB_Volume" } } ] } ] }' \ "https://{{ipaddress|hostname}}/univmax/restapi/100/sloprovisioning/symmetrix/000120200287”
Here's a breakdown of the different parts of the cURL command:'
-X PUT: Specifies that we are using the PUT HTTP method to update a resource.
-H "Content-Type: application/json": Specifies the content type of the request body as JSON.
-H "Authorization: Basic <base64 encoded username:password>": Specifies the authorization header with a base64-encoded string of your PowerMax username and password. Note that this is just an example; you should never expose your username and password in plain text.
-d 'payload': Specifies the JSON payload. In this example, it will create a storage group on array serial 000120200287 with four volumes, two of 1 TB and two of 1 GB.
"https://{{ipaddress|hostname}}/univmax/restapi/100/sloprovisioning/symmetrix/000120200287": Specifies the URL of the resource to create the object.
Building the payload for your POST and PUT calls is generally the toughest part of creating a REST call. The API documentation includes examples that can be copied and pasted with the minimum required keys. Note there are additional keys that can be added to take advantage of more advanced features should your workflows require them.
Beyond the basics
At this point, we’ve discussed the structure of API calls and how to create some cURL command, but that’s not really automation, is it?
To truly take advantage of the API, you will want to write some reusable scripts. And that is where we are here to help. The next section introduces you to our Python SDK, which is pre-loaded with pre-written and documented functions covering all the major API functionality, taking your API usage to the next level.
Jump-starting your REST development with PyU4V
If you’re just getting started with the PowerMax REST API, the good news is that there are tools out there to help you. A small team within Dell Engineering has produced a Python SDK library with hundreds of useful functions that can be consumed in Python scripts. The library is fully documented at https://pyu4v.readthedocs.io, and source code is available at https://github.com/dell/PyU4V. There have been many releases at this stage, and download statistics show that it’s heavily utilized.
PyU4V can be installed on a system with Python. Simply enter pip install PyU4V to install the latest.
The version of PyU4V will match the version of Unisphere. You can use older versions of PyU4V to access older versions of endpoints. They will continue to operate and return the same information regardless of the Unisphere version; however, for the latest functionality, you should aim to be on the latest version.
With the PyU4V function library installed, you should be good to start writing your scripts.
PyU4V pre-written functions are organized into function modules. Complete details are on the documentation website:
https://pyu4v.readthedocs.io/en/latest/quick_start.html#pyu4v-unisphere-rest-coverage
You might want to install a good IDE to help you write the code (IDE is integrated Development Environment. It helps with keeping track of variables and autocomplete on method names and variable calls, and so on). I really like pycharm; I’m sure there are others, but this one has served me well.
As with any programming task, we usually start with Hello World!. In this case I’m going to connect you to your Unisphere instance and list the arrays attached.
Running the script is as follows:
Other examples are in the programmers’ guide section of the PyU4V documentation; take some time to review them. For any call that is not covered in PyU4V, you can always use the custom methods. I’ll write some more about this in a follow-up post.
This post has been shortened from its original length, hopefully making it easier to consume.
I’ll be posting additional sections on gathering performance stats and working with snapshots in future blogs.
Related Blog Posts
RESTing on our Laurels - What’s New with the PowerMax API and Unisphere 10.1
Tue, 17 Oct 2023 13:12:28 -0000
|Read Time: 0 minutes
Unisphere 10.1 has just been released! Although the internal code name was Laurel, we are doing a lot in the API, so we definitely haven’t been RESTing on our laurels!
With this release the Unisphere for PowerMax team focused on what could be done better in the PowerMax API, to make things easier for developers and to reduce the amount of code people must maintain to work with the PowerMax API. Personally, I think they have knocked it out of the park with some new features. These features lay the groundwork for more of the same in the future. As always, there is a full change log for the API published along with updated OpenAPI documents available on https://developer.dell.com. In this blog I provide my own take and highlight some areas that I think will help you as a customer.
Let’s start with the traditional Unisphere for PowerMax API. With this new version of Unisphere there is a new version of the API and simpler versioning referencing throughout the API. For example, the following GET version API call returns the api_version (in this case, 101), and the currently supported API versions with this release (101, 100, and 92). As always, the previous two versions are supported. Here, the supported_api_versions key takes any guesswork out of the equation. If you are using PyU4V, a new version (10.1) is available, which supports all of the new functionality mentioned here.
https://Unisphere:8443/univmax/restapi/version (GET) { "version": "T10.1.0.468", "api_version": "101", "supported_api_versions": [ "101", "100", "92" ] }
I’ll break the other changes down by functional resource so you can skip any that you’re not using:
- Serviceability API calls
- Replication Call Enhancements
- Sloprovisioning Call Enhancements
- System Call Enhancements
- Performance API Call Enhancements
- The All New Enhanced PowerMax API – Bulk API calls
Serviceability API calls
For embedded Unisphere for PowerMax users, when the system is updated to the latest version of Unipshere, a new Serviceability API Resource becomes available.
The new serviceability API calls (as shown in the following figure) give control over the embedded Unisphere, providing access to solutions enabler settings, and Unisphere settings that up until now have only been accessible in the UI, such as:
- Setting up the nethosts file for client/server access from CLI hosts running Solutions Enabler
- Host based access control
- Certificate Management of the Solutions Enabler Guest OS
- And more
Here’s the tree of the Serviceability API resource:
Note: When executing API calls to update the Unisphere application, the server will restart as a result of these changes. You must wait for these to complete before you can issue more API calls. Also, as a reminder, if you are changing the IP address of the Unisphere server you must update your API connection for future calls.
Replication call enhancements
Good news for customers using snapshots and snapshot policies. New replication calls and keys will make the management workflows easier for anyone automating snapshot control and using policies.
An updated API call adds keys for directly associated policies vs inherited policies:
101/replication/symmetrix/{symmetrixId}/storagegroup/{storageGroupId} (GET)
In the API, identifying and tracking back linked snapshots has been time consuming in the past. Based on valued customer feedback, our product management and developers have implemented key changes that will help.
The ability to list storage groups that are linked targets has been there for a while, with query parameters in the following GET call:
101/replication/symmetrix/{symmetrixId}/storagegroup?is_link_target=true
However, finding out which snapshot was linked, and which source storage group owned that snapshot was a challenge. To make this easier, new keys now appear:
101/replication/symmetrix/{symmetrixId}/storagegroup/{storageGroupId} (GET)
As you can see, the 10.1 API call returns a new key (snapshot_link_info) that includes all the information you need to be able to manipulate the linked snapshots, without having to engineer any trickery yourself.
Sloprovisioning call enhancements
Probably the single biggest change to the Provisioning API calls is the ability to Validate and return a Bad Request when the performance_impact_validation_option is set for sloprovisoning the /maskingview POST call. This gives the developer a way to check, at the time of provisioning, whether a workload is suited to run on the supplied PowerMax serial number. This call uses performance data from the workload planner database and can help create enhanced provisioning workloads with performance and zoning in mind.
The Payload can now accept a new key (performance_impact_validation_option) which can be set to:
- IfRecommended – Run performance impact tests. If no performance capacity threshold is breached, run the requested configuration change.
- Preview – Run performance impact tests and return performance impact scores for the requested operation. Return the input object (with generated fields, if applicable) for relevant follow up API calls.
In addition, the payload has a “portGroupSelection” key that can automatically create a new port group or use an existing port group based. If automatic selection is used, selection can be either UtilizationBased or ZoningBased. (Note: Automatic port selection is only available for Fibre (SCSI FC))
If you choose to use an existing port group, existing port groups are evaluated by the workload planner algorithms examining port groups that are already configured on the system. The algorithm will select the least loaded port group for the provisioning and ignore zoning. Users have the Option to restrict selection to a supplied list of port groups using the API keys. See documentation for details of the various keys.
Note: When using the performance impact selection, you can’t specify an existing storage group because it’s assumed that they are already provisioned. Full documentation for the API call mentioned is here with the supported parameters.
The provisioning API calls include other additions:
- Update POST for Create Masking View, to allow the specifying of a Starting LUN Address. This was a customer enhancement to make it easier to configure boot from SAN.
- Update PUT for Modify SG, to allow the specifying of a Starting LUN Address when adding volumes. .
- Update PUT for Modify SG, to allow terminating snapshots associated with volumes being removed from a SG in a single call. This is very useful because it prevents stranded snapshots from consuming space on the array.
System call enhancements
We have added system calls to enable the refresh of Unisphere. This is useful to customers who are working in a distributed environment and who want to ensure that Unisphere data is up to the second with the latest information. This should be the case, but in the event that there were changes made on a remote system, it could take a minute or so before these are reflected in the object model. The new refresh call has some guardrails, in that you can only run it once every five minutes. If you try to execute too soon, status code 429 will return with message telling you to wait for it to come back:
“Bad or unexpected response from the storage volume backend API: Error POST None resource. The status code received is 429 and the message is {'retry_after_ms': 285417}.”
The documentation for this API call (/101/system/symmetrix/{array_serial}/refresh) is here.
Getting information about REST API resources and server utilization was previously only ever available in the user interface. It made sense to make this information available through the REST API because the information pertains to REST. The new GET call to obtain this information (/101/system/management_server_resources) is available, documentation is here.
Along the same lines, we have also added the following calls:
- Change Log Level - /101/system/logging (PUT/GET)
- Configure/Check SNMP Destination - /101/system/snmp (GET/POST/PUT/DELETE)
- Server Cert management - /101/system/snmp/server_cert (POST)
- Configure SNMPv3 with TLS - /101/system/snmp/v3_tls (POST)
- Manage PowerMax Licensing via API
Performance API call enhancements
There is only one minor change in the traditional API for performance with this release. We are adding the ability to register a list of storage groups for real time performance and also bring file metrics for SDNAS onto the Unisphere for PowerMax array for monitoring. The POST call /performance/Array/register has been updated to take new keys, selectedSGs, and a file.
The new payload would look something like this:
{ "symmetrixId": "01234568779", "selectedSGs": "sg1,sg2,sg3", "diagnostic": "true", "realtime": "true", "file": "true" }
There are some additional changes for mainframe and also Workload Planner which are covered in the changelog documentation. I just want to highlight here what I think most customers will be interested in and give some background.
The all new enhanced PowerMax API – Bulk API calls
I’ve been looking forward to being able to announce some very nice enhancements to the PowerMax API. The API provides new calls with resources accessible under a different Base URI. Rather than https:// {server_ip}:{port}/univmax/restapi/, the new API calls are under https://{server_ip}:{port}/univmax/rest/v1.
The difference between the two entry points will become apparent as you get used to these calls and the versioning will be arguably simpler going forward. Documentation is here.
- GET - /systems/{id}/volumes
- GET - /systems/{id}/storage-groups
- GET - /systems/{id}/performance-categories
- GET - /systems/{id}/performance-categories/{id}
For complete details about these endpoints, see:
- The API documentation marked "POWERMAX - ENHANCED ENDPOINTS"
- The Unisphere for PowerMax 10.1 REST API Changelog
“Ok” I hear you say, “so what’s the big deal?”. Well, these endpoints behave differently from our existing API calls. The provide more information faster so that developers don’t have to maintain a lot of code to get the information they need.
The volumes GET call returns details about every volume on a system in a single call. There is no pagination required and you don’t need to worry about iterators or have to deal with anything fancy. The API just gives you back one big JSON response with all the information you need. This eliminates the need to loop on calls and will dramatically cut down the number of API calls you need to issue to the server.
The same is true for the storage groups calls. With a single call, you can get information on all storage groups on the system, their attributes, and which volumes are in those groups.
But wait, there’s more…
We have implemented a modified form of filtering of the response. You can now filter on all attributes and nested attributes that are returned in the response:
../storage-groups?filter=cap_gb eq 100 ../storage-groups?filter=volumes.wwn like 12345678
The available filter options are:
The endpoints require you to “select” the desired attributes instead of returning everything up front. By doing so, you can control how server-intensive each request is by omitting or including only the relevant info:
…/storage-groups?select=cap_gb,uuid,type,num_of_volumes
This returns only the cap_gb,uuid, type and num_of_volumes for each storage group.
This also applies to nested attributes (a full stop is used to define child attributes):
…/storage-groups?select=volumes.wwn,volumes.effective_wwn,snapshots.timestamp_ms
If no attributes are defined in the “select”, only the default values, such as “id”, are returned. The list of attributes that can be selected is available in the documentation here.
Functions are also available for this in PyU4V. Currently multiple filter options are combined in an AND pattern and select can be applied to the data to reduce the output to only what you are interested in. The following is an example of this functionality as executed through PyU4V 10.1:
With this new functionality you can get all details for your volumes and storage groups in two calls per array, reduced from tens of thousands of calls on larger systems.
Enhanced performance metrics with the new Bulk API
In addition to the new GET calls for Volumes and Storage groups, there are new calls for the performance metrics.
The /systems/{id}/performance-categories (GET) call returns a list of performance categories valid for the arrays you are querying.
When you query each category, the API returns the last interval of diagnostic performance data using the new /systems/{id}/performance-categories/{id} GET call. This returns all key performance indicator metrics at the diagnostic level for the category and all instances in that category for the last five minutes.
These new enhanced API calls reduce the amount of code that developers need to write and maintain. The API call is intentionally designed to provide only the latest information. This reduces the amount of code for which developers need to maintain performance data collection for dashboard type tools and data collectors.
The following example shows a PyU4V script executing a few lines of code to gather all performance stats for every category on every component of a PowerMax array. It’s also gathering details on all volumes and all storage groups using the new Enhanced API calls. On my system, the code takes about eight seconds on average to gather all that information.
To wrap up
Hopefully this blog has provided some insight into the latest changes in the PowerMax REST API. As you can see, our developers have not been RESTing on their laurels!
Watch this space for more about the PowerMax API, and if there are topics that are of interest to you and you would like to learn more, send a request to @rawstorage on Twitter and I’ll try to accommodate your request!
Be sure to provide feedback through your account team for any enhancement requests or start a discussion on https://www.dell.com/community/en/topics/automation. Our product managers will take your requests and bring them to the development team.
Author: Paul Martin
Local Replication with the PowerMax REST API, Working with SnapVX Snapshots
Tue, 13 Jun 2023 16:02:04 -0000
|Read Time: 0 minutes
PowerMax arrays provide feature rich local replication options in SnapVX and clone technologies. The PowerMax REST API supports all of these features, and Dell Technologies provides pre-written Python functions as part of PyU4V -- a Python package for managing the PowerMax REST API as well as Ansible modules that support SnapVX. In this blog I provide examples in native REST calls and in a Python example.
If you are not familiar with REST, you’ll enjoy reading one or both of these blogs:
- https://infohub.delltechnologies.com/p/getting-started-with-rest-api-1
- https://infohub.delltechnologies.com/p/getting-started-with-the-powermax-rest-api-time-for-a-rest
Full API documentation is available on the developer hub here. All REST endpoints for the SnapVX and clone operations are under the replication resource of the API. This means that URI addresses are prefixed with the base URL https://{{base_url}}/{{api_version}}/replication. In addition to SnapVX and clone functionality, it’s also possible to assign snapshot policies to storage groups at the time of creation or when modifying using sloprovisioning resources. Examples appear further ahead in this blog.
Managing SnapVX snapshots with the REST API
SnapVX provides PowerMax administrators with the ability to take point in time snapshots across a collection of devices to create a consistent point in time image of the data in a very space efficient manner. The user can manipulate the snapshots for restore purposes or link them to volumes and present them to hosts using masking views to provide a copy of the snapshot image.
For details about SnapVX functionality, see the white paper Dell PowerMax and VMAX All Flash: TimeFinder SnapVX Local Replication. The PowerMax REST API provides all the functionality of Unisphere for PowerMax with snapshot management, and just like the UI management is orchestrated with the storage group. If you need to manipulate a snapshot for a single volume, you can use the CLI tools or add the volume to its own storage group.
Some points to remember with SnapVX snapshots:
- A SnapVX snapshot is never altered by host access and therefore is always available to the administrator for restore purposes until it is terminated by user action or it expires based on the time to live value (if set).
- Snapshots will only automatically expire when they are unlinked from all target storage groups.
- Snapshots can be set secure at or after creation time. Once set secure, the user cannot terminate the snapshot until the time to live has passed or modify the security of that snapshot except to extend secure time to live.
- When linking snapshots with the API or UI, if the target storage group doesn’t already exist the API will automatically create the storage group with the correct number of devices and size, matching the source device configurations.
- If you add devices to a source storage group, you must add devices to target storage groups. This is not automatic and needs to be planned for. Naming conventions can help simplify this process.
- Although SnapVX snapshots present with both a generation number and snapId, if automating, snapid is preferred because this number is a static reference id.
Creating and identifying SnapVX SnapShots with the REST API
Creating a snapshot is a simple process. A REST API POST call is sent to the management software, directed at the storage group to be snapped, specifying a name for the snapshot along with any optional parameters to be set (for example, you can set the snapshot to be secure or set time to live).
The following is an example POST call and payload for creating a snapshot of a storage group, with a snapshot named REST_SG_snapshot, setting a time to live of 10 days. (Values to be supplied are enclosed in {} signaling substitution required for actual values or variables.)
https://unisphereIP:8443/univmax/restapi/{{api_version}}/replication/symmetrix/{symmetrixId}/storagegroup/{storageGroupId}/snapshot (POST) Payload { "snapshotName": "REST_SG_snapshot", "timeToLive": 10 }
PyU4V has functions for complete control of SnapVX, making the API easier to consume. The following is a simple script to create a snapshot and print the return from the API.
import PyU4V conn = PyU4V.U4VConn(username='smc', password='smc', server_ip='unisphereip', port='8443', array_id=None, verify=False) #create a snapshot and assign returned information to variable snap_details snap_details = (conn.replication.create_storage_group_snapshot( storage_group_id='snapsrc', snap_name='snap4blog', ttl=1, secure=False, hours=True)) #Get SnapIds for all snapshots for storage group with name snap4blog all_sg_snaps = (conn.replication.get_storage_group_snapshot_snap_id_list( storage_group_id='snapsrc', snap_name='snap4blog')) #print details of snapshot created above print(snap_details) #Print only snapid from snap_details print(snap_details.get('snapid')) #Print all SnapIds associated with snap4blog snapshot on snapsrc storage group print(all_sg_snaps)
The output is shown below.
- The first print statement shows the detailed information for the snapshot just created with details such as timestamp, snapid, and so on.
- The second line prints only the snapid extracted from the JSON using the key ‘snapid’.
- The third line prints the variable ‘all_sg_snaps’ showing all snapshot ids with the name snap4blog associated with the snapsrc storage group.
To make the snapshot data available to a host, you can add some additional REST calls to link to a storage group.
The following script performs these tasks:
- Lists any storage group that has a snapshot linked to it on my test array. There are none to begin with.
- Creates a link to an existing snapshot using the snapid
- Runs the listing again. This time there is data to display showing the linked storage group.
#list any storage group that is being used as a linked target for snapvx #snapshot print(conn.common.get_request( target_uri=f'/100/replication/symmetrix/' f'000120200287/storagegroup?is_link_target=True', resource_type=None)) #Link a snapshot from ‘snapsrc’ storage group to ‘snaptgt’ storage group, #this will create snaptgt storage group as it doesn’t exist #with the name ‘snap4blog’ and snapid matching value in variable set earlier. conn.replication.modify_storage_group_snapshot_by_snap_id( src_storage_grp_id='snapsrc',tgt_storage_grp_id='snaptgt', snap_name='snap4blog', snap_id=snap_details.get('snapid'), link=True) #Print updated list of storage groups used as snap target print(conn.common.get_request( target_uri=f'/100/replication/symmetrix/' f'000120200287/storagegroup?is_link_target=True',0 resource_type=None))
The following is the output of the functions showing the snaptgt group in the list after the link has been issued.
SnapVX lends a lot of flexibility when refreshing test and development environments. The ability to relink the same snapshot (essentially wiping any changes to the target copy while preserving the point in time image) greatly simplifies iterative testing. You can also quickly relink to a different snapshot or unlink to reuse the target volumes for another purpose. To relink a snapshot with PyU4V, simply change the parameter in the modify_storage_group call instead of “link=True” we set “relink=True”.
If you are relinking directly from the API, modify the payload for the PUT call to reflect that the action is relink, as shown here:
https://UnisphereIP:8443/univmax/restapi/100/replication/symmetrix/{symmetrixId}/storagegroup/{storageGroupId}/snapshot/{snapshotId}/snapid/{snapId} (PUT)
When you no longer require your snapshots, don’t forget to terminate or unlink any linked targets to allow for automatic expiration if you’ve set a time to live. All actions use the same URI link, however the REST method will be PUT (with modified payload) or DELETE.
It’s generally a good practice to adopt a friendly naming convention for storage groups that are being used as snapvx targets to make them easy to identify in the UI and API output. Simply adding _TGT to the sg name may be enough, but your naming convention can be whatever works best for your organization.
Snapshot policies
In addition to regular snapshots, SnapVX provides a mechanism for users to assign snapshot policies to storage groups. (More details about snapshot policies are described in the white paper Dell PowerMax and VMAX All Flash: TimeFinder SnapVX Local Replication.) Assigning a snapshot policy means that you will have an automated rotation and preservation of a defined number of snapshots for your storage groups with a clearly defined recovery time objective. Users don’t need to manage the scheduling -- the policy automates all of that and can be assigned when storage groups are created, or at a later time.
Associating snapshot policies to storage groups is available through the POST and PUT calls for creating storage groups. A separate set of API calls is available for managing directly from the Snapshot Policy section of the API documentation.
For Py4V in Python, the code only requires an extra variable on the create and modify functions. The following example will create a snapshot policy (example_policy) that will take a snapshot every 12 minutes, retaining a maximum of 24 snapshots. The second part creates a storage group associated with this policy. Note that there are default policies already created on all arrays that users can use without having to create anything new.
import PyU4V api = PyU4V.U4VConn(username='smc',password='smc', server_ip='unisphereip', verify=None, array_id='000297600841') api.snapshot_policy.create_snapshot_policy( snapshot_policy_name='example_policy', interval="12 Minutes", local_snapshot_policy_snapshot_count=24) api.provisioning.create_non_empty_storage_group( srp_id="SRP_1", storage_group_id="blog_example_sg", num_vols=1, vol_size=1, cap_unit="GB",snapshot_policy_ids=["example_policy"], service_level="Diamond", workload=None)
Hopefully this blog has given you the basics to working with SnapVX snapshots using REST and Python!
For more information and a list of all functions for SnapVX, see the documentation for PyU4V on readthedocs.io and the REST API documentation on the Dell developer portal here.
In upcoming blogs, I will also be looking at using clone technology with the REST API, and when this is a good alternative to SnapVX depending on your needs. Have fun automating and if you have questions, you can always start a discussion on the PyU4V GitHub -- we are always willing to help!
Author: Paul Martin