It’s tough to beat PowerShell for automating administrative tasks, or simply providing an elegant and powerful command line based alternative to the Nimble Web UI. With the introduction of NimbleOS 2.3, we made the Nimble REST API available for those interested in building scripts or software that integrated with our arrays. While it’s possible to use PowerShell to invoke the REST API (I blogged about exactly that HERE), there’s admittedly a learning curve to picking up the nuances of working with REST if all you really want to do is execute some cmdlets to help in administering your Nimble environment.

 

With that in mind, we are pleased to announce the availability of the Nimble PowerShell Toolkit 1.0.  It is available for immediate download via InfoSight.  You can get it from this page.

 

The toolkit makes the functionality we’ve exposed through the API easier to consume via native PowerShell cmdlets. Let’s look at the prerequisites, install the toolkit, see what's included, and walk through some examples.

 

Prerequisites

Host OS

 

Essentially, the toolkit requires PowerShell version 3 or higher. So basically whether you're running Windows Server 2012, 2012R2, or Windows 7/8/10, just make sure your PowerShell version is 3 or greater. You can check your version by inspecting the $PSVersionTable variable and noting the value for PSVersion:

 

PS C:\> $PSVersionTable

 

Name                          Value

----                          -----

PSVersion                      3.0

WSManStackVersion              3.0

SerializationVersion           1.1.0.1

CLRVersion                     4.0.30319.42000ee

BuildVersion                   6.2.9200.16398

PSCompatibleVersions           {1.0, 2.0, 3.0}

PSRemotingProtocolVersion      2.2

NimbleOS

 

As mentioned earlier, the Nimble PowerShell Toolkit is built on the REST API and as such it requires a NimbleOS version which provides this API.  That means NimbleOS 2.3.x at a minimum.  NimbleOS 3.x is also supported.

 

Installation

 

The toolkit is downloaded as a zip file.  Once you have it on your system, installation is a simple matter of unzipping the contents of the file and placing them into the appropriate location.

 

To install for all users, copy the NimblePowerShellToolkit folder into the C:\Windows\system32\WindowsPowerShell\v1.0\Modules directory.

 

To install for the current user only, copy the NimblePowerShellToolkit folder into $env:HOMEDRIVE\users\<user>\Documents\WindowsPowerShell\Modules

 

Cmdlets

 

The following cmdlets are available as part of the toolkit. The readme file included with the download goes into a bit more detail describing the purpose of each cmdlet, so I won't reproduce that here.  Additionally, most of the cmdlets proivide example usage within the help file.

 

Connect-NSGroup

Connect-NSGroup

Disconnect-NSGroup

Get-NSAccessControlRecord

Get-NSArray

Get-NSAuditLog

Get-NSChapUser

Get-NSFibreChannelPort

Get-NSGroup

Get-NSInitiator

Get-NSInitiatorGroup

Get-NSJob

Get-NSNetworkConfig

Get-NSNetworkInterface

Get-NSPerformancePolicy

Get-NSPool

Get-NSProtectionSchedule

Get-NSProtectionTemplate

Get-NSReplicationPartner

Get-NSRole

Get-NSSnapshot

Get-NSSnapshotCksum

Get-NSSnapshotCollection

Get-NSSoftwareVersion

Get-NSSubnet

Get-NSToken

Get-NSUser

Get-NSVolume

Get-NSVolumeCollection

Get-NSVolumeFamily

Invoke-NSVolumeCollectionDemote

Invoke-NSVolumeCollectionPromote

Merge-NSPool

New-NSAccessControlRecord

New-NSChapUser

New-NSClone

New-NSDebugLog

New-NSInitiator

New-NSInitiatorGroup

New-NSNetworkConfig

New-NSPerformancePolicy

New-NSPool

New-NSProtectionSchedule

New-NSProtectionTemplate

New-NSReplicationPartner

New-NSSnapshot

New-NSSnapshotCollection

New-NSToken

New-NSUser

New-NSVolume

New-NSVolumeCollection

Remove-NSAccessControlRecord

Remove-NSChapUser

Remove-NSInitiator

Remove-NSInitiatorGroup

Remove-NSNetworkConfig

Remove-NSPerformancePolicy

Remove-NSPool

Remove-NSProtectionSchedule

Remove-NSProtectionTemplate

Remove-NSReplicationPartner

Remove-NSSnapshot

Remove-NSSnapshotCollection

Remove-NSToken

Remove-NSUser

Remove-NSVolume

Remove-NSVolumeCollection

Restore-NSVolume

Set-NSChapUser

Set-NSInitiatorGroup

Set-NSNetworkConfig

Set-NSPerformancePolicy

Set-NSPool

Set-NSProtectionSchedule

Set-NSProtectionTemplate

Set-NSReplicationPartner

Set-NSSnapshot

Set-NSSnapshotCollection

Set-NSUser

Set-NSVolume

Set-NSVolumeCollection

 

Examples

 

Connecting to an array/group

 

First we'll import the NimblePowerShellToolKit module, then connect to an array so that we can run further commands.  The Connect-NSGroup takes a PSCredential object as an argument.  If you forget to provide one, it will prompt you for one:

 


PS C:\Users\jcates> ipmo NimblePowerShellToolKit

PS C:\Users\jcates> $cred = Get-Credential

PS C:\Users\jcates> Connect-NSGroup -group myarray.nimble.com -credential $cred


 

Group        : myarray

ManagementIP : 1.2.3.4

User         : admin

Model        : AF7000

SerialNo     : AC-123456

Version      : 3.3.0.0-346604-opt


 

 

Create a Volume

 

Here we'll create a very simple volume.  It's possible to specify many more options to the command, but we'll accept the defaults for now.  Feel free to experiment!

 


PS C:\Users\jcates> New-NSVolume -name newvol -size 10240

 

access_control_records        :

agent_type                    : none

app_category                  : Other

app_uuid                      :

base_snap_id                  :

base_snap_name                :

block_size                    : 4096

cache_needed_for_pin          : 10737418240

cache_pinned                  : False

cache_policy                  : normal

caching_enabled               :

clone                         : False

creation_time                 : 4/29/2016 1:55:07 PM

dedupe_enabled                : False

description                   :

dest_pool_id                  :

dest_pool_name                :

encryption_cipher             : none

fc_sessions                   :

folder_id                     :

folder_name                   :

full_name                     :

id                            : 06239f8bea1874ff06000000000000000000000095

iscsi_sessions                :

last_modified                 : 4/29/2016 1:55:07 PM

limit                         : 100

metadata                      :

move_aborting                 : False

move_bytes_migrated           : 0

move_bytes_remaining          : 0

move_est_compl_time           : 0

move_start_time               : 0

multi_initiator               : True

name                          : newvol

num_connections               : 0

num_fc_connections            : 0

num_iscsi_connections         : 0

num_snaps                     : 0

offline_reason                :

online                        : True

online_snaps                  :

owned_by_group                : group-rtp-afa8

owned_by_group_id             : 00239f8bea1874ff06000000000000000000000001

parent_vol_id                 :

parent_vol_name               :

perfpolicy_id                 : 03239f8bea1874ff06000000000000000000000001

perfpolicy_name               : default

pinned_cache_size             : 0

pool_id                       : 0a239f8bea1874ff06000000000000000000000001

pool_name                     : default

previously_deduped            : False

projected_num_snaps           : 0

read_only                     : False

reserve                       : 0

search_name                   : newvol

serial_number                 : 38129d49930fc4d46c9ce900ec74eb3b

size                          : 10240

snap_limit                    : 9223372036854775807

snap_reserve                  : 0

snap_usage_compressed_bytes   : 0

snap_usage_populated_bytes    : 0

snap_usage_uncompressed_bytes : 0

snap_warn_level               : 0

target_name                   :

thinly_provisioned            : True

upstream_cache_pinned         : False

usage_valid                   : True

vol_state                     : online

vol_usage_compressed_bytes    : 0

vol_usage_uncompressed_bytes  : 0

volcoll_id                    :

volcoll_name                  :

vpd_ieee0                     : 38129d49930fc4d4

vpd_ieee1                     : 6c9ce900ec74eb3b

vpd_t10                       : Nimble  38129d49930fc4d46c9ce900ec74eb3b

warn_level                    : 80


 

Wow, volumes sure do have a lot of attributes!  It sure would be nice to focus on only the most important attributes, but still have access to all of the attributes if and when we need them.  The Nimble PS toolkit has been designed to be configurable in this regard.  You may have noticed an included JSON file when you installed the toolkit.  This file determines which fields will be displayed by default and which fields will be hidden (but still part of the  resulting PS object. You can edit this JSON file to customize the output for your environment, and the changes will take effect once the module has been unloaded/reloaded.  Let's take a look at an example of these in action.

 

Viewing Volumes

 


PS C:\Users\jcates> $myvols = Get-NSVolume -name newvol


PS C:\Users\jcates> $myvols

 

name            : newvol

size            : 10240

perfpolicy_name : default

vol_state       : online

iscsi_sessions  :

num_connections : 0

pool_name       : default

volcoll_name    :

target_name     : iqn.2007-11.com.nimblestorage:newvol-v18609ac9edd6a7e6.00000932.f5b63d2f

agent_type      : none

 

 

PS C:\Users\jcates> $myvols | select *

 

access_control_records        :

agent_type                    : none

app_uuid                      :

base_snap_id                  :

base_snap_name                :

block_size                    : 4096

cache_needed_for_pin          : 10737418240

cache_pinned                  : False

cache_policy                  : normal

caching_enabled               : True

clone                         : False

creation_time                 : 4/29/2016 2:03:22 PM

description                   :

dest_pool_id                  :

dest_pool_name                :

encryption_cipher             : none

fc_sessions                   :

full_name                     :

id                            : 0618609ac9edd6a7e6000000000000000000000932

iscsi_sessions                :

last_modified                 : 4/29/2016 2:03:22 PM

limit                         : 100

metadata                      :

move_aborting                 : False

move_bytes_migrated           : 0

move_bytes_remaining          : 0

move_start_time               : 0

multi_initiator               : False

name                          : newvol

num_connections               : 0

num_fc_connections            : 0

num_iscsi_connections         : 0

num_snaps                     : 0

offline_reason                :

online                        : True

online_snaps                  :

owned_by_group                : mktg-cs02

parent_vol_id                 :

parent_vol_name               :

perfpolicy_id                 : 0318609ac9edd6a7e6000000000000000000000001

perfpolicy_name               : default

pinned_cache_size             : 0

pool_id                       : 0a18609ac9edd6a7e6000000000000000000000001

pool_name                     : default

projected_num_snaps           : 0

read_only                     : False

reserve                       : 0

search_name                   : newvol

serial_number                 : 1b3023950c91c8056c9ce9002f3db6f5

size                          : 10240

snap_limit                    : 9223372036854775807

snap_reserve                  : 0

snap_usage_compressed_bytes   : 0

snap_usage_populated_bytes    : 0

snap_usage_uncompressed_bytes : 0

snap_warn_level               : 0

target_name                   : iqn.2007-11.com.nimblestorage:newvol-v18609ac9edd6a7e6.00000932.f5b63d2f

thinly_provisioned            : True

upstream_cache_pinned         : False

usage_valid                   : True

vol_state                     : online

vol_usage_compressed_bytes    : 0

vol_usage_uncompressed_bytes  : 0

volcoll_id                    :

volcoll_name                  :

warn_level                    : 80

 

Alright, as you can see the object still has all of the fields, but will only display the hidden fields if you tell it to. Cool!

 

Create a Snapshot

 

This one is a little more nuanced. The underlying API requires a volume id, so we need to provide that to the Get-NSsnapshot cmdlet instead of a volume name.  No problem, though.  We can grab the volume id from Get-NSVolume.

 


PS C:\Users\jcates> New-NSSnapshot -name mysnapshot -vol_id $(Get-NSVolume -name newvol).id

 

access_control_records      :

app_uuid                    :

creation_time               : 4/29/2016 3:04:06 PM

description                 :

id                          : 0418609ac9edd6a7e60000000000000a000005211c

is_replica                  : False

is_unmanaged                : True

last_modified               : 4/29/2016 3:04:06 PM

metadata                    :

name                        : mysnapshot

new_data_compressed_bytes   : 0

new_data_uncompressed_bytes : 0

new_data_valid              : False

offline_reason              : user

online                      : False

origin_name                 : myarray

replication_status          :

schedule_name               :

serial_number               : 581dea4c5692478a6c9ce9002f3db6f5

size                        : 10737418240

snap_collection_id          : 0518609ac9edd6a7e600000000000000000005211c

snap_collection_name        : 113671168983149651921554878598198852288510378691027866640113

target_name                 : iqn.2007-11.com.nimblestorage:newvol-mysnapshot-v18609ac9edd6a7e6.00000932.f5b63d2f.s18609ac9edd6a7e6.00000a00.0005211c

vol_id                      : 0618609ac9edd6a7e6000000000000000000000932

vol_name                    : newvol

writable                    : False

 

 

Get a List of Snapshots

 

The one thing you need to be aware of with Get-NSsnapshot is that, like the API, it requires a volume to be specified.  (If you really need ALL of the snapshots on the array, a foreach loop through each of the volumes should do the trick.)  Here we can specify the volume by name.

 


PS C:\Users\jcates> Get-NSSnapshot -vol_name newvol

 

name                                                                                                id

----                                                                                                --

mysnapshot                                                                                          0418609ac9edd6a7e60000000000000a000005211c

If we want to dig into the details of each snapshot, we can query by snapshot id and select all of the hidden fields.

 


PS C:\Users\jcates> Get-NSSnapshot -id 0418609ac9edd6a7e60000000000000a000005211c | select *

 

access_control_records      :

app_uuid                    :

creation_time               : 4/29/2016 3:04:06 PM

description                 :

id                          : 0418609ac9edd6a7e60000000000000a000005211c

is_replica                  : False

is_unmanaged                : True

last_modified               : 4/29/2016 3:10:22 PM

metadata                    :

name                        : mysnapshot

new_data_compressed_bytes   : 0

new_data_uncompressed_bytes : 0

new_data_valid              : True

offline_reason              : user

online                      : False

origin_name                 : mktg-cs02

replication_status          :

schedule_name               :

serial_number               : 581dea4c5692478a6c9ce9002f3db6f5

size                        : 10737418240

snap_collection_id          : 0518609ac9edd6a7e600000000000000000005211c

snap_collection_name        : 113671168983149651921554878598198852288510378691027866640113

target_name                 : iqn.2007-11.com.nimblestorage:newvol-mysnapshot-v18609ac9edd6a7e6.00000932.f5b63d2f.s18609ac9edd6a7e6.00000a00.0005211c

vol_id                      : 0618609ac9edd6a7e6000000000000000000000932

vol_name                    : newvol

writable                    : False

Clone a Volume

 

Now that we have a snapshot in place, we could create a Nimble Zero-Copy Clone volume from it.

 


PS C:\Users\jcates> New-NSClone -name myclone -base_snap_id 0418609ac9edd6a7e60000000000000a000005211c -clone $true

 

access_control_records        :

agent_type                    : none

app_uuid                      :

base_snap_id                  : 0418609ac9edd6a7e60000000000000a000005211c

base_snap_name                : mysnapshot

block_size                    : 4096

cache_needed_for_pin          : 21474836480

cache_pinned                  : False

cache_policy                  : normal

caching_enabled               : True

clone                         : True

creation_time                 : 4/29/2016 3:24:42 PM

description                   :

dest_pool_id                  :

dest_pool_name                :

encryption_cipher             : none

fc_sessions                   :

full_name                     :

id                            : 0618609ac9edd6a7e6000000000000000000000933

iscsi_sessions                :

last_modified                 : 4/29/2016 3:24:42 PM

limit                         : 100

metadata                      :

move_aborting                 : False

move_bytes_migrated           : 0

move_bytes_remaining          : 0

move_start_time               : 0

multi_initiator               : False

name                          : myclone

num_connections               : 0

num_fc_connections            : 0

num_iscsi_connections         : 0

num_snaps                     : 0

offline_reason                : user

online                        : False

online_snaps                  :

owned_by_group                : myarray

parent_vol_id                 : 0618609ac9edd6a7e6000000000000000000000932

parent_vol_name               : newvol

perfpolicy_id                 : 0318609ac9edd6a7e6000000000000000000000001

perfpolicy_name               : default

pinned_cache_size             : 0

pool_id                       : 0a18609ac9edd6a7e6000000000000000000000001

pool_name                     : default

projected_num_snaps           : 0

read_only                     : False

reserve                       : 0

search_name                   : myclone

serial_number                 : 7e527c1b273f93ee6c9ce9002f3db6f5

size                          : 10240

snap_limit                    : 9223372036854775807

snap_reserve                  : 0

snap_usage_compressed_bytes   : 0

snap_usage_populated_bytes    : 0

snap_usage_uncompressed_bytes : 0

snap_warn_level               : 0

target_name                   : iqn.2007-11.com.nimblestorage:myclone-v18609ac9edd6a7e6.00000933.f5b63d2f

thinly_provisioned            : True

upstream_cache_pinned         : False

usage_valid                   : True

vol_state                     : offline

vol_usage_compressed_bytes    : 0

vol_usage_uncompressed_bytes  : 0

volcoll_id                    :

volcoll_name                  :

warn_level                    : 80

 

Delete a Volume

 

Once a volume has served its purpose, we can delete it. We need to first set it offline with the Set-NSvolume cmdlet, then we can delete it from the array with Remove-NSVolume.

 

 

PS C:\Users\jcates> Set-NSVolume -name myclone -online $false

PS C:\Users\jcates> Remove-NSVolume -name myclone

 

Once again, we have merely scratched the surface of what's possible through PowerShell.  I encourage you to download the toolkit and give it a spin.  As always, we'd love to see the cool things you create with it.  Feel free to share them here on Nimble Connect!