It's been a while since I've posted anything on this subject so probably a good time to give some more practical examples. Disclaimer this guide will not teach you programming and the creator of this lab is not a seasoned developer.  There are certainly more elegant ways of doing things, however I'm keeping it symmple.  (Did you see what I did there?)

 

The first example I will tackle here is provisioning on VMAX 3 and All Flash arrays with REST API.  To be able to work with any of this code you will need an Array at 5977 or higher and also a Unipshere for VMAX instance, this can be running as embedded Managment server on the array or as a standalone host both fully support the REST API.

 

Like any script the end goal is what will determine how you need to move forward and break the end goal down into more manageable steps. Once the sub-tasks are known we can identify the REST calls needed and start to build up a script.


Provisioning Tasks for VMAX3 and VMAX-ALL Flash are located under the /sloprovisioning/symmetrix resources. The simplest way to accomplish our task would be to simply use the POST (create) REST call to create a masking view /sloprovisioning/symmetrix/{symmetrixId}/maskingview

 

The above call can accomplish the task in a single REST call. But we may want to do some checks before we go ahead and do the provisioning, this way is we have a failure, the script can handle it easier and roll back if need be.

 

The main components of a masking view which is provides access to VMAX storage to a host or cluster has three components.

 

  1. Storage Group - Container for all the volumes for the application. May be cascaded where we have storage groups contained within a storage group. To use cascaded storage groups with REST API you must first create an empty storage group then use a REST PUT (edit) call to modifiy the storage group adding individual storage groups instead of volumes.
  2. Host or Host Group - Initiators can only belong to one host at a time, and are comprised of a list of WWPN for the HBA from the host or ISCSI IQN. A Host Group can contain multiple Hosts and is generally used when provisioning to a cluster
  3. Port Group - A port can belong to more than one port group. However, for storage systems running HYPERMAX OS 5977 or higher, you cannot mix different types of ports (physical FC ports, virtual ports, and iSCSI virtual ports) within a single port group.

Each component has similar naming guidelines names must be unique and cannot exceed 64 characters. Only alphanumeric characters, underscores  _ and - are allowed.


SO as long as we are able to create each of the above components provisioning will be successful.

 

First create the Host passing a list of initiators payload to the REST call is POST to the endpoint  /sloprovisioning/symmetrix/{symmetrixId}/host optionally a check can be made with a GET call on the Host name to see if it is already in use. If you are planning on provisioning to cluster then REST URI endpoint for the hostgroup creation  /sloprovisioning/symmetrix/{symmetrixId}/hostgroup

 

Next create the Port Group we will use for the application for the front end ports /sloprovisioning/symmetrix/{symmetrixId}/portgroup

 

Next the storage Group will be created and initial volumes added REST call is POST to endpoint  /sloprovisioning/symmetrix/{symmetrixId}/storagegroup

 

Add additional volumes to the storage group of various sizes repeated as necessary, REST call is PUT /sloprovisioning/symmetrix/{symmetrixId}/storagegroup/{storageGroupId} the Payload for the PUT call will have details of the parameters to be changed, in this case "editStorageGroupActionParam" and "expandStorageGroupParam" with details on the

number and size of volumes being added. Please refer to the documentation library or the REST client to examine this payload.

 

Finally Create the Masking View with all pieces together REST call is POST /sloprovisioning/symmetrix/{symmetrixId}/maskingview, since we are creating each of the individual components the payload for the POST will use useExisting{component}param where

{component} will be host or storagegroup etc.

 

For successful completion of this script it is assumed that the Host, Storage and Port groups do not already exist on the selected array. It should also be ports specified for the Port Group exist and are of the same emulation type e.g FA .

 

Just to highlight you will get a return code with each call so best to know what they mean and how to deal with them, below is a quick list of the main ones, I'll add more over time.

 

  • Successful REST calls will return status code of 200
  • Client Error will return status code of 400 - Check your payloads and endpoints, usually a { or ) out or missing required parameters.
  • Server Error will return status code 500 - Check the Symapi log and SMAS log on your unisphere server, there was a problem processing the request.

 

Use the REST Java client to explore the REST endpoints as outlined and Payloads. Details of how to use the REST client are in my previous post here Getting Started with VMAX REST API

 

Ok...  So we have a recipe of sorts, how do I use this..  Well if you've setup your python environment as outlined in my previous post and installed the requests library you should be all set... 

 

Simply clone the github and copy the files to your test server, I've posted an example provisioning_example.py to the GitHub which is a functional example of how to provision using the recipe above.  To get this to work in your environment simply fill in the required parameters in PyU4V.conf and you are all set.

 

GitHub - ciarams87/PyU4V: A library showing some of the functionality possible using the ReST API of UniSphere for VMAX


Optionally you can modify the code to accept parameters for things like IP, user and password,  When you are instantiate the rest_functions class for the first time in your script you can choose to pass these in from your main script making the setup more flexible, if you're using an IDE such as PyCharm it's pretty simple to see what parameters can be passed.

setting optional parameters.png


I've opted not to do that however the code is designed that you can use it either way,   I'm using the config file in all it's glory to minimize the number of parameters I need to pass when calling the script.  Below is an example of how this script in action.  Remember if you are trying to execute this in your environment you will need VMAX3 or VMAX-ALL Flash as we are using the sloprovisioning REST endpoints.

lab1success.png

After Successful run of the script, logging into Unisphere verify that it's not all smoke and mirrors stuff actually happened in the ether.


privverify.png


Hopefully this was useful to you, Next POST will give an example of how to protect your DATA with Target-less Snapshots using REST for VMAX.