hpe-storage / nimble-golang-sdk

Go Software Development Kit (SDK) for HPE Nimble Storage Arrays

HPE Nimble Storage SDK for Go

This is the Go Software Development Kit (SDK) for HPE Nimble Storage arrays. The HPE Nimble Storage array has a Representational State Transfer (REST) web service application programming interface (API). The SDK implements a simple client Go module for communicating with the HPE Nimble Storage REST API. The Go module is being used to communicate with the API over HTTPS.

The SDK provides Go modules to interact with the HPE Nimble Storage REST API. The code abstracts the lower-level API calls into Go objects that you can easily incorporate into any automation or DevOps workflows. Use it to create, modify and delete most resources like volumes, volume collections, initiator groups and more, as well as perform other tasks like snapshotting, cloning, restoring data, etc.

Synopsis

Examples are available in examples. This is a brief Go program that creates a 5GiB volume on the specified array.

package main

import (
	"fmt"
	"github.com/hpe-storage/nimble-golang-sdk/pkg/client/v1/nimbleos"
	"github.com/hpe-storage/nimble-golang-sdk/pkg/param"
	"github.com/hpe-storage/nimble-golang-sdk/pkg/service"
)

func main() {

	// Create new group service
	groupService, err := service.NewNimbleGroupService(
		service.WithHost("192.168.1.1"),	// Managment hostname or IP of array
		service.WithUser("admin"),			// Username
		service.WithPassword("admin"))		// Password

	if err != nil {
		fmt.Printf("Unable to connect to group, %+v\n", err.Error())
		return
	}

	// Logout when finished
	defer groupService.LogoutService()

	// Initialize volume attributes
	var sizeField int64 = 5120

	// Set mandatory volume attributes
	newVolume := &nimbleos.Volume{
		Name:              param.NewString("myvol1"),
		Size:              &sizeField,
	}

	// Assign volume service instance
	volSvc := groupService.GetVolumeService()

	// Create volume
	volume, err := volSvc.CreateVolume(newVolume)

	if err != nil {
		fmt.Printf("Failed to create volume, %+v\n", err.Error())
		return
	}
	// Volume created
	fmt.Printf("Volume \"%s\" created (%s)\n", *volume.Name, *volume.ID)
}

Service types may be found in pkg/service and it's recommended to have a basic understanding and familiarity of the HPE Nimble Storage REST API.

Requirements

The SDK require Go version 1.13 or later. The SDK is coupled to the following NimbleOS version span.

	Minimum version	Maximum version
NimbleOS	5.0.10	5.3.2

As future versions of NimbleOS and new endpoint services become available, the SDK will be updated.

Support

HPE Nimble Storage SDK for Go is supported by HPE when used with HPE Nimble Storage arrays on valid support contracts. Please send an email to [email protected] to get started with any issue you might need assistance with. Engage with your HPE representative for other means on how to get in touch with Nimble support directly.

Contributing

Contributing guidelines are available in CONTRIBUTING

Community

Join the HPE DEV slack by signing up at slack.hpedev.io. HPE employees may sign in direct at hpedev.slack.com with a valid HPE address. We hang out in #NimbleStorage.

License

The HPE Nimble Storage SDK for Go is released under the Apache 2.0 license, see LICENSE for details.

nimble-golang-sdk's Issues

Querying snapshots by Volume Name

NOTE: This behavior is observed on the master branch as of Aug 5, 2021.

I found an issue when querying for snapshots by Volume Name when the volume name contains characters unsafe for URL's. In the event that a volume name contains something like :, which is not url safe, the SDK will convert the request to an advanced search.

This advanced search request is rejected by the SAN.

Here is an example of the code snip-it:

	params := &param.GetParams{
		Filter: &param.SearchFilter{
			Criteria: []*param.SearchFilter{
				{FieldName: &nimbleos.SnapshotFields.VolName, Operator: param.EQUALS.String(), Value: *vol.Name},
				{FieldName: &nimbleos.SnapshotFields.IsManuallyManaged, Operator: param.EQUALS.String(), Value: "true"},
			},
		},
	}
	snaps, err := service.GetSnapshotService().GetSnapshots(params)

Here is the REST API debug log:

==============================================================================
Volume: SERVER-Data-Daily-7-Day-2021-10-26::20:41:18.409:EDT
2021/11/23 14:39:43.863943 DEBUG RESTY 
==============================================================================
~~~ REQUEST ~~~
POST  /v1/snapshots/detail  HTTP/1.1
HOST   : x.x.x.x:5392
HEADERS:
	Content-Type: application/json
	User-Agent: go-resty/2.6.0 (https://github.com/go-resty/resty)
	X-Auth-Token: 32aa460f44d0a95ee57982c92a71f47e
BODY   :
{
   "data": {
      "_constructor": "AdvancedCriteria",
      "operator": "",
      "criteria": [
         {
            "fieldName": "vol_name",
            "operator": "equals",
            "value": "SERVER-Data-Daily-7-Day-2021-10-26::20:41:18.409:EDT"
         },
         {
            "fieldName": "is_manually_managed",
            "operator": "equals",
            "value": "true"
         }
      ]
   },
   "operationType": "fetch"
}
------------------------------------------------------------------------------
~~~ RESPONSE ~~~
STATUS       : 400 OK
PROTO        : HTTP/1.1
RECEIVED AT  : 2021-11-23T14:39:43.863640016-05:00
TIME DURATION: 42.352938ms
HEADERS      :
	Connection: Keep-Alive
	Content-Type: application/json;charset=utf-8
	Date: Tue, 23 Nov 2021 19:39:43 GMT
BODY         :
{
   "messages": [
      {
         "code": "SM_http_bad_request",
         "severity": "error",
         "text": "The request could not be understood by the server."
      },
      {
         "code": "SM_unsupported_query_operator",
         "severity": "error",
         "arguments": {
            "field": "AdvancedCriteria",
            "op": ""
         },
         "text": "Unsupported filter operator '' specified for the attribute 'AdvancedCriteria'."
      }
   ]
}

Automatic token refresh does not work. Need to update vendored version of rusty

I have experienced that when the auth token expires in a long running application, the SDK does not retry the failed operation after token refresh. Instead, after refreshing the token, it returns the error from the original failed attempt.

I did some digging and it turns out that the root cause is actually an off-by-one error the vendored version of resty v2.2.0. This bug was fixed in v2.3.0.

The max retries are set in pkg/client/group_mgmt_client.go

const (
...
	maxLoginRetries   = 1
...
)

and used https://github.com/hpe-storage/nimble-golang-sdk/blob/master/pkg/client/group_mgmt_client.go#L130

// NewClient instantiates a new client to communicate with the Nimble group
func NewClient(ipAddress, username, password, apiVersion string, waitOnJobs, isTenant bool, tlsConfig *tls.Config) (*GroupMgmtClient, error) {
...
	// Add a retry condition to perform a relogin if the session has expired
	groupMgmtClient.Client.
		AddRetryCondition(
...
		).SetRetryCount(maxLoginRetries)  <<<<-------
...
}

The bug in resty counts the original request as one of the retry attempts, so that a RetryCount of 1 will only make the first request and upon retry it exits because it has exhausted the RetryCount.

Enhance support of Pagination

• We need to enhance pagination support similar to Python SDK

• The pagination for list output can be handled better without exposing startRow and endRow to the user.

• The idea here is to eliminate startRow and endRow from the SDK so that the users needs not worry about the specifying those parameters explicitly and also avoid dealing with those parameters.

• Instead, we can expose the pagination functionality in a simpler way with only two parameters:

1. limit (This is typically page size which returns the first N entries).
2. from_id (This is the typically the last id retrieved from the previous get(limit=N) response.

Please refer to the example in Python SDK:
https://hpe-storage.github.io/nimble-python-sdk/get_started/using/index.html#pagination