Prerequisites
Make sure that the Spectrum Scale GUI is up and running and that you have access to it. The minimal required Spectrum Scale GUI version is 5.0.2 which can be checked by logging in to the GUI, selecting the small lifebelt icon in the upper right corner and clicking on "About". The IBM API Explorer is available in plain Spectrum Scale as well as in Elastic Storage Server.
Step 1: Access the IBM API Explorer site served by your Spectrum Scale GUI instance
Access the following website in your browser by replacing [hostname] with the hostname or IP address of your Spectrum Scale GUI server in the following URL:
https://[hostname]/ibm/api/explorer/
After you have entered the credentials of your (existing) Spectrum Scale GUI user the following page will open up:
Step 2: Explore the available endpoints under "Spectrum Scale REST API v2"
The next step is to expand the list of all available REST API endpoints by clicking on "Spectrum Scale REST API v2". Take some time to review the listed endpoints.
Step 3: Query the "/scalemgmt/v2/cluster" endpoint
To query the "/scalemgmt/v2/cluster" endpoint you have to enter your credentials first by expanding "GET /scalemgmt/v2/cluster" and clicking on the red exclamation mark:
You can use the same credentials that you have used to access the "/ibm/api/explorer" URL or any other Spectrum Scale GUI user.
The exclamation mark will change its color from red to blue. Be aware that the credentials were not checked yet. So if an error with code "401" is returned the entered credentials were wrong.
Now you are ready to actually execute the query by clicking on the "Try it out!" button. If everything went fine you should get back a response containing metadata of your cluster in JSON format.
As a goodie the corresponding curl command is also displayed which can be used right away to query the Spectrum Scale REST API using the command line. If your Spectrum Scale GUI/REST API server is using a self-signed certificate you need to add the "-k" parameter to the curl command to accept self-signed certificates. I assume you are aware of the security implications coming with this... Instead of base64 encoding your username and password you can also replace
--header 'Authorization: Basic YWRtaW46YWRtaW4wMDE='
with
-u username:password
A final curl command would then look like this (If the command as shown below works fine on your system you should go ahead and change your password right away, since I'm using the default password here...):
curl -k -X GET --header 'Accept: application/json' --header 'Authorization: Basic YWRtaW46YWRtaW4wMDE=' 'https://9.155.108.188:443/scalemgmt/v2/cluster'
The response looks like this:
{
"cluster": {
"clusterSummary": {
"clusterId": 6157148208084482000,
"clusterName": "gpfs-cluster-2.novalocal",
"primaryServer": "os-21.novalocal",
"rcpPath": "/usr/bin/scp",
"rcpSudoWrapper": false,
"repositoryType": "CCR",
"rshPath": "/usr/bin/ssh",
"rshSudoWrapper": false,
"uidDomain": "novalocal"
},
"cesSummary": {
"addressPolicy": "even-coverage",
"cesSharedRoot": "/mnt/objfs",
"enabledServices": "SMB,NFS",
"logLevel": 0
}
},
"status": {
"code": 200,
"message": "The request finished successfully."
}
}
All endpoints starting with GET can be safely executed since they will only retrieve data. You must be careful with endpoints starting with POST, PUT or DELETE since they actually change the configuration of your cluster. The button named "Try it out!" is a bit misleading here since it will indeed execute commands on the cluster. For example "trying out" the DELETE /filesets endpoint will indeed delete the fileset...
Step 4: Creating a Snapshot
A more advanced topic is to create a snapshot using the Spectrum Scale REST API. The first step is to expand the endpoint called
"POST /scalemgmt/v2/filesystems/{filesystemName}/filesets/{filesetName}/snapshots
The next step is to fill in all the missing and required properties in the "Parameters" section as seen on the screenshot below. This is basically the "filesystemName" and the "filesetName" for which you want to create the snapshot and the "body" of the request. The "body" of any REST API request is always in JSON format and can get quite complex. The "Model" and "Example Section" on the right side of the IBM API Explorer can provide some more guidance on the data that's needed. The "body" for the snapshot creation is simple and consists only of the "snapshotName".
{
"snapshotName": "myFirstApiSnapshot"
}
A click on the "Try it out!" button will send the request to the Spectrum Scale REST API server and return a so called "job".
The curl request looks a bit scattered due to the JSON formatting:
curl -k -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic YWRtaW46YWRtaW4wMDE=' -d '{ \
"snapshotName": "myFirstApiSnapshot" \
}' 'https://9.155.108.188:443/scalemgmt/v2/filesystems/gpfs0/filesets/root/snapshots'
A "job" object is returned showing that the request was accepted and that the command is now running:
{
"jobs": [
{
"jobId": 1000000000001,
"status": "RUNNING",
"submitted": "2019-02-06 22:43:21,955",
"completed": "N/A",
"runtime": 4,
"request": {
"data": {
"snapshotName": "myFirstApiSnapshot"
},
"type": "POST",
"url": "/scalemgmt/v2/filesystems/gpfs0/filesets/root/snapshots"
},
"result": {},
"pids": []
}
],
"status": {
"code": 202,
"message": "The request was accepted for processing."
}
}
All POST, PUT and DELETE requests are always executed asynchronously and a job object is returned. The returned "jobId" can then be used to retrieve the status of a job. To do this expand the endpoint:
GET /scalemgmt/v2/jobs/{jobId}
And enter the "jobId" that was returned above in the "jobId" field in the "Parameters" section.
Click one more time on "Try it out!" to retrieve the status of your job:
The curl request looks like the follows:
curl -k -X GET --header 'Accept: application/json' --header 'Authorization: Basic YWRtaW46YWRtaW4wMDE=' 'https://9.155.108.188:443/scalemgmt/v2/jobs/1000000000001'
And a "job" object is returned which shows that the command has finished successfully.
{
"jobs": [
{
"jobId": 1000000000001,
"status": "COMPLETED",
"submitted": "2019-02-06 22:43:21,955",
"completed": "2019-02-06 22:43:23,287",
"runtime": 1332,
"request": {
"data": {
"snapshotName": "myFirstApiSnapshot"
},
"type": "POST",
"url": "/scalemgmt/v2/filesystems/gpfs0/filesets/root/snapshots"
},
"result": {
"progress": [],
"commands": [
"mmcrsnapshot 'gpfs0' 'myFirstApiSnapshot' -j 'root' "
],
"stdout": [
"EFSSG0019I The snapshot myFirstApiSnapshot has been successfully created."
],
"stderr": [],
"exitCode": 0
},
"pids": []
}
],
"status": {
"code": 200,
"message": "The request finished successfully."
}
}
All the other endpoints work similar to the request above. Go ahead and explore more of the available endpoints!
#SpectrumScaleRESTAPI#spectrumscale#softwaredefinedstorage#Softwaredefinedstorage#IBMSpectrumScale#tutorial#SpectrumScaleGUI