Skip to content

Commit 3269e2c

Browse files
mikenelson-iomikenelson-io
committed
updated files
1 parent 259563d commit 3269e2c

File tree

6 files changed

+2191
-8
lines changed

6 files changed

+2191
-8
lines changed

‎EUA.rtf‎

Lines changed: 1528 additions & 0 deletions
Large diffs are not rendered by default.

‎MSI Installer/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
The Pure Storage PowerShell SDK MSI Installer
3+
4+
For details on installation, see this article at purestorage.com:
5+
https://support.purestorage.com/Solutions/Microsoft_Platform_Guide/a_Windows_PowerShell/aa2_Install_PowerShell_SDK_using_Microsoft_Installer_Package_-_MSI
6+

‎README.md‎

Lines changed: 161 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,164 @@
1-
# Pure Storage PowerShell SDK 2.2 Readme
1+
# Creating a PowerShell Session with FlashArray
2+
There are two ways to create a PowerShell Session with FlashArray, through API Token or through OAUTH2 Token.
23

3-
The Pure Storage PowerShell SDK 2.2 provides support for REST 2.0, 2.1 and 2.2. REST 2.0 was introduced in Purity 5.3. The SDK provides the ability to automate tasks with the FlashArray that are implemented as PowerShell cmdlets based on the REST API endpoints.
4+
## API Token
5+
To create a PowerShell Session using API Token use the following command:
6+
```powershell
7+
$Array = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Credential (Get-Credential) -IgnoreCertificateError
8+
```
9+
You need to define `$ArrayEndpoint` with the FlashArray IP or Name. You will also be prompted for the username and password for the FlashArray.
410

5-
### DOWNLOADS
6-
* [Installation Package](https://github.com/PureStorage-Connect/PowerShellSDK2/blob/master/<placeholder>.msi)
7-
* [Pure Storage Support -- Programming Interfaces > PowerShell](https://support.purestorage.com/Solutions/Microsoft_Platform_Guide/<placeholder>)
8-
* [Quick Start Guide PowerShell SDK Examples (ZIP)](https://github.com/PureStorage-Connect/PowerShellSDK/blob/master<placeholder>.zip)
11+
## OAUTH2 Token
12+
To create a PowerShell Session using OAUTH2 follow the 2 steps bellow:
13+
14+
1. **An API Client registration on the array, and an RSA key pair (certificates).**
15+
16+
If you already have an API Client you can proceed to step 2.
17+
18+
To create a PowerShell Session using OAUTH2 you need an API Client on the FlashArray. You can create an API Client either using the Purity//FA CLI commands (See `pureapiclient` command on the CLI for details), or using Pure Storage PowerShell SDK 2 REST session.
19+
20+
There are two ways to create an API Client using Pure Storage PowerShell SDK 2: `New-Pfa2ApiClient` or `New-Pfa2ArrayAuth`.
21+
22+
a. If you want to use your existing RSA key pair, use `New-Pfa2ApiClient`. Note that you need to be already authenticated with the array, either with an existing API Client or using the API Token. If you are not authenticated yet, do so using the `Connect-Pfa2Array` command as shown before. Once authenticated use the following command:
23+
```powershell
24+
$ApiClient = New-Pfa2ApiClient -Array $Array -MaxRole $MaxRole -Issuer $ArrayIssuer -PublicKey $Certificate -Name $ClientName
25+
```
26+
Where,
27+
- `$Array` is the PureArray object returned by the `Connect-Pfa2Array` command.
28+
- `$MaxRole` is the maximum role allowed for ID Tokens issued by this API client. Valid values are `array_admin`, `storage_admin`, `ops_admin`, and `readonly`.
29+
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
30+
- `$Certificate` is the API Client's PEM formatted (Base64 encoded) RSA public key.
31+
- `$ClientName` is the unique name to be used for this API Client.
32+
33+
API Clients created using `New-Pfa2ApiClient` are disabled by default. To enable the API Client use the command `Update-Pfa2ApiClient`:
34+
```powershell
35+
Update-Pfa2ApiClient -Array $Array -Name $ClientName -Enabled $true
36+
```
37+
38+
b. If you do not want to use your own key pair, the `New-Pfa2ArrayAuth` command bellow will generate a key pair for you and store it under `%USERPROFILE%\.ssh\`, or Mac/Linux under `~/.ssh/*`. The command will also create the API Client on the FlashArray. Note that, if the API Client already exists, the command will just return the existing client.
39+
```powershell
40+
$ApiClientAuthInfo = New-Pfa2ArrayAuth -Endpoint $ArrayEndpoint -ApiClientName $Clientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword -Force
41+
```
42+
Where,
43+
- `$ArrayEndpoint` is the FlashArray IP or Name.
44+
- `$ClientName` is the unique name for this API Client.
45+
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
46+
- `$ArrayUsername` is the FlashArray username.
47+
- `$ArrayPassword` is the FlashArray Password (SecureString).
48+
49+
2. **Create OAUTH2 session using the an API client KeyID and ClientID:**
50+
To create an OAUTH2 session you will need the following information from the API Client: `$clientID`, `$keyId`, and `$privateKeyFile`.
51+
This information can be retrieved from the response of the `New-Pfa2ArrayAuth` command:
52+
```powershell
53+
$clientId = $ApiClientAuthInfo.PureClientApiClientInfo.clientId
54+
$keyId = $ApiClientAuthInfo.PureClientApiClientInfo.KeyId
55+
$privateKeyFile = $ApiClientAuthInfo.pureCertInfo.privateKeyFile
56+
```
57+
If you used the `New-Pfa2ApiClient` command, `$clientID` and `$keyId` can also be retrieved from the response of the `New-Pfa2ApiClient` command, and `$privateKeyFile` should be your private key file location:
58+
```powershell
59+
$clientId = $ApiClient.Id
60+
$keyId = $ApiClient.KeyId
61+
```
62+
A third option is to use the command `pureapiclient list`, on the Purity//FA CLI, to list all existing API Clients.
63+
64+
Finally, use the following command to create the OAUTH2 session:
65+
```powershell
66+
$oauth = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ApiClientName $Clientname -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPassword -IgnoreCertificateError
67+
```
68+
Where,
69+
- `$ArrayEndpoint` is the FlashArray IP or Name.
70+
- `$ArrayUsername` is the FlashArray username.
71+
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
72+
- `$ClientName` is the unique name for this API Client.
73+
- `$privateKeyPassword` is required if the private key was generated using a passphrase. If you created the API Client using the `New-Pfa2ArrayAuth` command there is no passphrase. This password should be a SecureString.
74+
75+
76+
Note: The `Connect-Pfa2Array` cmdlet caches authentication information for the duration of the PowerShell session. With this, subsequent SDK cmdlets do not need to explicitly provide -Array parameter. The cmdlets will retrieve the FlashArray authentication information from PowerShell session variable.
77+
78+
# PowerShell Pipeline
79+
Pure Storage PowerShell SDK 2 supports PowerShell Pipeline starting from 2.x version
80+
81+
## Examples
82+
* Remove all of the hosts
83+
```powershell
84+
Get-Pfa2Host -Array $Array | Remove-Pfa2Host -Array $Array
85+
```
86+
87+
* Remove all of the hosts containing "test" in name
88+
```powershell
89+
(Get-Pfa2host -Array $Array) | Where-Object {$_.name -like '*test*'} | Remove-Pfa2Host -Array $Array
90+
```
91+
92+
# SSH Passthrough
93+
Using Pure Storage PowerShell SDK 2 cmdlet 'Invoke-Pfa2CLICommand' SSH cli commands can be run on FlashArray.
94+
95+
```powershell
96+
$Password = ConvertTo-SecureString -String $ArrayPassword -AsPlainText -Force
97+
$CommandText = "purevol create --size 10G test-volume-name"
98+
Invoke-Pfa2CLICommand -EndPoint $ArrayEndpoint -Username $ArrayUsername -Password $Password -CommandText $CommandText"
99+
```
100+
101+
# Sorting
102+
See `-Sort` option for the Pure Storage PowerShell SDK 2 cmdlet.
103+
104+
## Examples
105+
* Sort the list of volumes by name in ascending order
106+
```powershell
107+
$Result = Get-Pfa2Volume -Array $Array -Sort "name"
108+
```
109+
110+
* Sort the list of volumes by name in descending order
111+
```powershell
112+
$Result = Get-Pfa2Volume -Array $Array -Sort "name-"
113+
```
114+
115+
* Sort the list of volumes by name and then by provisioned
116+
```powershell
117+
$Result = Get-Pfa2Volume -Array $Array -Sort "name,provisioned"
118+
```
119+
120+
# Limit and Offset
121+
See `-Limit` and `-Offset` options for Pure Storage PowerShell SDK 2 cmdlet
122+
123+
## Examples
124+
* Get a limited set of volumes from FlashArray defined by `$Limit` (See `-Offset`)
125+
```powershell
126+
$Volumes = Get-Pfa2Volume -Array $Array -Limit $Limit
127+
```
128+
129+
* Get all volumes from offset `$Limit` (See `-Limit`)
130+
```powershell
131+
$RemainingVolumes = Get-Pfa2Volume -Array $Array -Offset $Limit
132+
```
133+
134+
# Filtering (Purity)
135+
Please run `Help About_Pfa2Filtering` from PowerShell terminal
136+
137+
# Logging
138+
139+
## FlashArray Phonehome Logging
140+
141+
By default, PowerShell SDK activity is logged to a log file on the FlashArray is enabled.
142+
To disable this logging, use the `-DisableVerbosePhoneHomeLogging` flag while creating connection to the array (see example below) :
143+
```powershell
144+
$Array = Connect-Pfa2Array -Endpoint $ArrayName -Credential (Get-Credential) -DisableVerbosePhoneHomeLogging
145+
```
146+
147+
Logs can be found in the array at /var/log/purity/external_rest.log-*
148+
149+
150+
## Local logging
151+
152+
Very detailed logging on the internal and network operations is available in two forms.
153+
1. For any *-Pfa2 Cmdlet you may add the `-Verbose` option.
154+
155+
Detailed log messages will be output on the PowerShell Verbose stream (stream 4) for this
156+
command.
157+
158+
PowerShell also has Preference Variables that set the default logging level for all cmdlets.
159+
See `$VerbosePreference` in `Get-Help About_Preference_Variables`
160+
161+
2. You can record detailed logs for all SDK operations to a log file.
162+
Using the `Set-Pfa2Logging` cmdlet you provide a named file for the log to be output to.
163+
Logging stops when you set the `-LogFilename` to empty.
9164

10-
### RELEASE
11-
* [v2.2](https://github.com/PureStorage-Connect/PowerShellSDK/releases/tag/2.2)

‎about_Pfa2Filtering.help.txt‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
TOPIC
2+
about_Pfa2Filtering
3+
4+
SHORT DESCRIPTION
5+
Describes how PureStoragePowerShellSDK cmdlets support filtering to narrow down results.
6+
7+
LONG DESCRIPTION
8+
The PureStoragePowerShellSDK supports filtering for various methods that might return multiple objects. The filter query parameter narrows down the results of a request to only the response objects that satisfy the filter criteria. Cmdlets that support filtering expose the -Filter parameter that takes a string representing the filter criteria.
9+
10+
FILTERING WITH OPERATORS
11+
12+
PureStoragePowerShellSDK filter parameter support common comparison operators.
13+
14+
Syntax: -Filter <field_name> <operator> <field_value>
15+
16+
field_name
17+
Name of the field on which to create the filter. Field_name can be any of the fields in the response.
18+
19+
operator
20+
Type of filter match used to compare <field_name> to <field_value>.
21+
22+
field_value
23+
Search value (number, date, or string) that determines the fields to be included in or excluded from the response. Literal strings must be wrapped in quotes. To refine the filter, include the asterisk (*) symbol as a wildcard character in the field value to represent zero or more characters. Field_value can include multiple asterisks, and the asterisks can appear anywhere in the value. For example, the filter name='*cat*' lists all hosts with names that contain cat, including ones that begin or end with cat, such as cat, catnap, happycats, and lolcat. If the asterisks were not included, only the host named cat would be returned.
24+
25+
Filters support the following operators:
26+
=
27+
Example: Get a list of all volumes with volume names that include v1.
28+
Get-PfaVolumes $arr -Filter "name='*v1*'"
29+
!=
30+
Example: Get a list of all volumes with volume names that do not include v1.
31+
Get-PfaVolumes $arr -Filter "name!='*v1*'"
32+
<
33+
Example: Get a list of all volumes that are less than 100 gigabytes in size.
34+
Get-PfaVolumes $arr -Filter size<107374182400
35+
>
36+
Example: Get a list of all volumes that were created after 2016-04-25T23:02:23Z.
37+
Get-PfaVolumes $arr -Filter "created>'2016-04-25T23:02:23Z'"
38+
<=
39+
Example: Get a list of all volumes that were created on or before 2016-04-25T23:02:23Z.
40+
Get-PfaVolumes $arr -Filter "created<='2016-04-25T23:02:23Z'"
41+
>=
42+
Example: Get a list of all volumes that are greater than or equal to 100 gigabytes in size.
43+
Get-PfaVolumes $arr -Filter size>=107374182400
44+
45+
All comparison operators are case-insensitive
46+
47+
48+
FILTERING WITH FUNCTIONS
49+
50+
PureStoragePowerShellSDK filter parameter support the CONTAINS and NOT functions.
51+
52+
Syntax: -Filter function(parameters)
53+
54+
Filters support the following functions:
55+
56+
contains(<field_name<,<string>)
57+
Description: Contains the enclosed string. Takes exactly two parameters, where field_name represents the name of the field on which to create the filter, and string represents the string to search within field_name.
58+
Example: Get a list of all host groups with names that include cluster02.
59+
Get-PfaVolumes $arr -Filter "contains(hgroup,'cluster02')"
60+
61+
not(<expression>)
62+
Description: Inverse of the enclosed expression.
63+
Example: Get a list of all host groups with names that do not include cluster02.
64+
Get-PfaVolumes $arr -Filter "not(hgroup='cluster02')"
65+
66+
67+
FILTERING WITH EXISTENCE CHECKS
68+
69+
PureStoragePowerShellSDK filter parameter supports existence checks. For example, the operation Get-PfaVolumes $arr -Filter "source" returns volumes where the "source" exists for the volume.
70+
71+
EXAMPLES
72+
73+
Example 1: Get the volume with serial number 31F52075433543110001103F.
74+
Get-PfaVolumes $arr -Filter "serial='31F52075433543110001103F'"
75+
76+
Example 2: Get a list of hosts that are associated with host group ESXi-IT-Cluster02-hg2.
77+
Get-PfaHosts $arr -Filter "hgroup='ESXi-IT-Cluster02-hg2'"
78+
79+
Example 3: Get a list of all Fibre Channel ports on controller ct0.
80+
Get-PfaVolumes $arr -Filter "name='ct0.fc*'"
81+
82+
Example 4: Get a list of all volumes that have been destroyed and will be eradicated within the next 2 hours (7200 seconds).
83+
Get-PfaPendingDeleteVolumes $arr -Filter "time_remaining<=7200"
84+
85+
Example 5: Get a list of all hosts that are associated with host groups that include hg3 in the host group name.
86+
Get-PfaHosts $arr -Filter "contains(hgroup,'hg3')"
87+
88+
Example 6: Get a list of all volumes with names that do not include vol01.
89+
Get-PfaVolumes $arr -Filter "not(contains(name,'vol01'))"
90+
91+
Example 7: Get a list of all hosts that are associated with a host group.
92+
Get-PfaHosts $arr -Filter "hgroup"
93+
94+
Example 8: Get a list of all volumes that were not created from another source.
95+
Get-PfaVolumes $arr -Filter "not(source)"
96+
97+
KEYWORDS
98+
99+
100+
SEE ALSO
101+
See the "Sorting, Filtering, and Pagination" section of the FlashArray REST API guide.

0 commit comments

Comments
 (0)