restructed repository, added examples, updated Readme

Author: ffeldhaus

OnCommand-Insight-Tutorial.md

@@ -1,42 +1,46 @@
-OnCommand-Insight
-=================
+S3-Mgmt
+=======
 
-OnCommand-Insight PowerShell Module
+StorageGRID S3 Management PowerShell Module
 
 Installation
 ------------
 
-Extract OnCommand-Insight.zip either to your preferred PowerShell Module location (e.g. `$HOME\WindowsPowershell\Documents\WindowsPowerShell\Modules` or `C:\Windows\System32\WindowsPowerShell\v1.0\Modules`).
+Extract S3-Mgmt.zip either to your preferred PowerShell Module location (e.g. `$HOME\WindowsPowershell\Documents\WindowsPowerShell\Modules` or `C:\Windows\System32\WindowsPowerShell\v1.0\Modules`).
 
 Usage
 -----
 
-Check if OnCommand-Insight Module can be found by PowerShell
+Check if S3-Mgmt Module can be found by PowerShell
 
-    Get-Module -ListAvailable OnCommand-Insight
+    Get-Module -ListAvailable S3-Mgmt
 
 Import PowerShell Module
 
-    Import-Module OnCommand-Insight
+    Import-Module S3-Mgmt
 
-List all Cmdlets included in the OnCommand-Insight Module
+List all Cmdlets included in the S3-Mgmt Module
 
-    Get-Command -Module OnCommand-Insight
+    Get-Command -Module S3-Mgmt
 
-Show help for Cmdlet to connect to OnCommand-Insight Server
+Show help for Cmdlet to connect to StorageGRID Management Server
 
-    Get-Help Connect-OciServer -Detailed
+    Get-Help Connect-S3MgmtServer -Detailed
 
-Connect to OnCommand Insight Server using the `-Insecure` Switch to skip checking the certificate of the server
+Connect to StorageGRID Management Server (use the `-Insecure` switch to skip checking the certificate of the server)
 
     $Credential = Get-Credential
     Connect-OciServer -Name myserver.mydomain.tld -Credential $Credential -Insecure
 
-List all Storage Arrays
+List all S3 Accounts
 
-    Get-OciStorageArrays
+    Get-S3Accounts
+	
+Show Account Usage
+
+    Get-S3Accounts | Get-S3AccountUsage
 
-Trusting the Publisher of the OnCommand Insight Cmdlets
+Trusting the Publisher of the S3-Mgmt Cmdlets
 -------------------------------------------------------
 
 This PowerShell Module is signed with a code signing certificate issued by the *NetApp Corp Issuing CA 1*. If the PowerShell execution policy requires powershell scripts to be signed (see [about_Execution_Policies](technet.microsoft.com/library/hh847748.aspx) for details), two steps are required to run this PowerShell Module
@@ -54,26 +58,4 @@ This PowerShell Module is signed with a code signing certificate issued by the *
   10. Click Finish
   11. A *Security Warning* will be displayed. Click *Yes* to install the certificate. The *Thumbprint (sha1)* should be **9FFB6F1A 06BC0245 27368705 2E7309D3 6FF2CFD0**
   12. Click twice on *OK* to close the dialogs.
-2. When importing the PowerShell module via `Import-Module OnCommand-Insigh` a dialog is displayed asking if the publisher *CN=florianf-Florian-Feldhaus, OU=Users, OU=EMEA, OU=Sites, DC=hq, DC=netapp, DC=com* should be trusted. Select *[A] Always run* to permanently trust this publisher.
-
-	
-Changelog
----------
-
-### Version 0.3
-
-* Module is now signed
-* added instructions to trust the publisher of the Module
-* added ability for most cmdlets to accept pipeline input
-* streamlined usage of the parameter ID. All cmdlets accepting ID parameters now have named parameters like VolumeID or HostID and ID is an alias to these parameters (e.g. ID always works).
-* added formatting of OCI types
-
-### Version 0.2
-
-* improved Help and added Parameter Help
-* solved Namespace issues when changing server and introduced OCI namespace
-* improved build process
-
-### Version 0.1
-
-* First internal release with all Cmdlets implemented
+2. When importing the PowerShell module via `Import-Module S3-Mgmt` a dialog is displayed asking if the publisher *CN=florianf-Florian-Feldhaus, OU=Users, OU=EMEA, OU=Sites, DC=hq, DC=netapp, DC=com* should be trusted. Select *[A] Always run* to permanently trust this publisher.

README.md

@@ -0,0 +1,73 @@
+# StorageGRID S3 Management PowerShell Cmdlet Tutorial
+
+This tutorial will give an introduction to the StorageGRID S3 Management PowerShell Cmdlets
+
+## Discovering the available Cmdlets
+
+Load the S3-Mgmt Module
+
+```powershell
+Import-Module S3-Mgmt
+```
+
+Show all available Cmdlets from the S3-Mgmt Module
+
+```powershell
+Get-Command -Module S3-Mgmt
+```
+
+Show the syntax of all Cmdlets from the S3-Mgmt Module
+
+```powershell
+Get-Command -Module S3-Mgmt
+```
+
+To get detailed help including examples for a specific Cmdlet (e.g. for Connect-S3MgmtServer) run
+
+```powershell
+Get-Help Connect-S3MgmtServer -Detailed
+```
+
+## Connecting to a StorageGRID Management Server
+
+For data retrieval a connection to the StorageGRID Management Server is required. The Connect-S3MgmtServer Cmdlet expects the hostname or IP and the credentials for authentication
+
+```powershell
+$ServerName = 'nms.stroagegrid.example.com'
+$Credential = Get-Credential
+Connect-S3MgmtServer -Name $ServerName -Credential $Credential
+```
+
+If the login fails, it is often due to an untrusted certificate of the StorageGRID Management Server. You can ignore the certificate check with the `-Insecure` option
+
+```powershell
+Connect-S3MgmtServer -Name $ServerName -Credential $Credential -Insecure
+```
+
+By default the connection to the S3Mgmt server is established through HTTPS. If that doesn't work, HTTP will be tried. 
+
+To force connections via HTTPS use the `-HTTPS` switch
+
+```powershell
+Connect-S3MgmtServer -Name $ServerName -Credential $Credential -HTTPS
+```
+
+To force connections via HTTP use the `-HTTP` switch
+
+```powershell
+Connect-S3MgmtServer -Name $ServerName -Credential $Credential -HTTP
+```
+
+## Simple workflow for exporting S3 account usage to CSV
+
+In this simple workflow the S3 account usage data will be retrieved and exported as CSV to (C:\tmp\usage.csv).
+
+```powershell
+$Accounting = foreach ($Account in Get-S3Accounts) {
+    $Usage = Get-S3AccountUsage -id $Account.id
+    $Output = New-Object -TypeName PSCustomObject -Property @{Name=$Account.name;ID=$Account.id;"Calculation Time"=$Usage.calculationTime;"Object Count"=$Usage.objectCount;"Data Bytes used"=$Usage.dataBytes}
+    Write-Output $Output
+} 
+
+$Accounting | Export-Csv -Path C:\tmp\usage.csv -NoTypeInformation
+```

S3-Mgmt-Tutorial.md

@@ -4,7 +4,7 @@
 $Credential = Get-Credential
 
 # Connect to StorageGRID NMS
-Connect-S3Mgmt -Name cbc-sg-adm1.muccbc.hq.netapp.com -Credential $credential -Insecure
+Connect-S3MgmtServer -Name cbc-sg-adm1.muccbc.hq.netapp.com -Credential $credential -Insecure
 
 # retrieve all S3 Accounts
 Get-S3Accounts
@@ -20,4 +20,4 @@ $Accounting = foreach ($Account in Get-S3Accounts) {
     Write-Output $Output
 } 
 
-Export-Csv -Path C:\tmp\usage.csv -NoTypeInformation -InputObject $Accounting
+$Accounting | Export-Csv -Path C:\tmp\usage.csv -NoTypeInformation

src/S3-Mgmt-examples.ps1

@@ -145,21 +145,36 @@ function global:Connect-S3MgmtServer {
 #>
 function Global:Get-S3Accounts {
     [CmdletBinding()]
+
+    PARAM ()
+
+    Begin {
+        if (!$CurrentS3MgmtServer) {
+            Write-Error "No S3 management server found. Please run Connect-S3MgtServer to continue."
+        }
+        $Result = $null
+    }
 
-    $Uri = $CurrentS3MgmtServer.BaseURI + '/api/v1/service-provider/s3-accounts'
+    Process {
+        $Uri = $CurrentS3MgmtServer.BaseURI + '/api/v1/service-provider/s3-accounts'
+
+
 
-    try {
-        $Result = Invoke-RestMethod -Method GET -Uri $Uri -Headers $CurrentS3MgmtServer.Headers
-    }
-    catch {
-        $Response = $_.Exception.Response
-        $Result = $Response.GetResponseStream()
-        $Reader = New-Object System.IO.StreamReader($Result)
-        $responseBody = $reader.ReadToEnd()
-        Write-Error "GET to $Uri failed with response:`n$responseBody"
-    }
+        try {
+            $Result = Invoke-RestMethod -Method GET -Uri $Uri -Headers $CurrentS3MgmtServer.Headers
+        }
+        catch {
+            $Response = $_.Exception.Response
+            if ($Response) {
+                $Result = $Response.GetResponseStream()
+                $Reader = New-Object System.IO.StreamReader($Result)
+                $responseBody = $reader.ReadToEnd()
+            }
+            Write-Error "GET to $Uri failed with response:`n$responseBody"
+        }
 
-    Write-Output $Result.data
+        Write-Output $Result.data
+    }
 }
 
 <#
@@ -180,6 +195,9 @@ function Global:Get-S3Account {
     )
 
     Begin {
+        if (!$CurrentS3MgmtServer) {
+            Write-Error "No S3 management server found. Please run Connect-S3MgtServer to continue."
+        }
         $Result = $null
     }
 
@@ -193,9 +211,11 @@ function Global:Get-S3Account {
             }
             catch {
                 $Response = $_.Exception.Response
-                $Result = $Response.GetResponseStream()
-                $Reader = New-Object System.IO.StreamReader($Result)
-                $responseBody = $reader.ReadToEnd()
+                if ($Response) {
+                    $Result = $Response.GetResponseStream()
+                    $Reader = New-Object System.IO.StreamReader($Result)
+                    $responseBody = $reader.ReadToEnd()
+                }
                 Write-Error "GET to $Uri failed with response:`n$responseBody"
             }
 
@@ -222,6 +242,9 @@ function Global:Get-S3AccountUsage {
     )
 
     Begin {
+        if (!$CurrentS3MgmtServer) {
+            Write-Error "No S3 management server found. Please run Connect-S3MgtServer to continue."
+        }
         $Result = $null
     }
 
@@ -235,9 +258,11 @@ function Global:Get-S3AccountUsage {
             }
             catch {
                 $Response = $_.Exception.Response
-                $Result = $Response.GetResponseStream()
-                $Reader = New-Object System.IO.StreamReader($Result)
-                $responseBody = $reader.ReadToEnd()
+                if ($Response) {
+                    $Result = $Response.GetResponseStream()
+                    $Reader = New-Object System.IO.StreamReader($Result)
+                    $responseBody = $reader.ReadToEnd()
+                }
                 Write-Error "GET to $Uri failed with response:`n$responseBody"
             }
 

src/S3-Mgmt.ps1 src/S3-Mgmt.psm1src/S3-Mgmt.ps1 renamed to src/S3-Mgmt.psm1

@@ -48,7 +48,7 @@ New-ModuleManifest `
     -Author $Author `
     -CompanyName $Company `
     -Copyright "(c) $((Get-Date).Year) $Company. All rights reserved." `
-    -Description 'OnCommand-Insight Powershell Cmdlet.' `
+    -Description 'StorageGRID S3 Management Powershell Cmdlet.' `
     -PowerShellVersion '3.0' `
     -DotNetFrameworkVersion '4.0' `
     -NestedModules (Get-ChildItem $src\*.psm1 | % { $_.Name }) `
@@ -75,7 +75,7 @@ Write-Host "Creating the release archive..."
 # Requires .NET 4.5
 [Reflection.Assembly]::LoadWithPartialName("System.IO.Compression.FileSystem") | Out-Null
 
-$zipFileName = Join-Path ([System.IO.Path]::GetDirectoryName($dst)) "$([System.IO.Path]::GetFileNameWithoutExtension($manifestFileName))-$ModuleVersion.zip"
+$zipFileName = Join-Path ([System.IO.Path]::GetDirectoryName($dst)) "$([System.IO.Path]::GetFileNameWithoutExtension($manifestFileName)).zip"
 
 # Overwrite the ZIP if it already exists.
 if (Test-Path $zipFileName) {