forked from PureStorage-Connect/PowerShellSDK2
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.txt
171 lines (100 loc) · 8.47 KB
/
readme.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
// README.TXT FOR PURE STORAGE FLASHARRAY POWERSHELL SDK VERSION 2.2
Please refer to the RELEASE_NOTES.TXT file for the latest revision and release information.
// Creating a PowerShell Session with FlashArray
There are two ways to create a PowerShell Session with FlashArray Purity API version 2.2 and later, through API Token or through OAUTH2 Token.
*FlashArray Purity version 2.0 and 2.1 only allow for OAuth2 authentication.
To view which API versions are available on an array, open a browser and go to https://<FQDN or IP Address of Array>/api/api_version
## API Token
To create a PowerShell Session using API Token use the following command:
$Array = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Credential (Get-Credential) -IgnoreCertificateError
You need to define `$ArrayEndpoint` with the FlashArray IP or Name. You will also be prompted for the username and password for the FlashArray.
## OAUTH2 Token
To create a PowerShell Session using OAUTH2, follow the 2 steps bellow:
1. An API Client registration on the array, and an RSA key pair (certificates).
*If you already have an API Client you can proceed to step 2.
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 CLI commands (See `pureapiclient` command on the CLI for details), or using Pure Storage PowerShell SDK 2 REST session.
There are two ways to create an API Client using Pure Storage PowerShell SDK 2: `New-Pfa2ApiClient` or `New-Pfa2ArrayAuth`.
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:
$ApiClient = New-Pfa2ApiClient -Array $Array -MaxRole $MaxRole -Issuer $ArrayIssuer -PublicKey $Certificate -Name $ClientName
Where,
- `$Array` is the PureArray object returned by the `Connect-Pfa2Array` command.
- `$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`.
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
- `$Certificate` is the API Client's PEM formatted (Base64 encoded) RSA public key.
- `$ClientName` is the unique name to be used for this API Client.
API Clients created using `New-Pfa2ApiClient` are disabled by default. To enable the API Client use the command `Update-Pfa2ApiClient`:
Update-Pfa2ApiClient -Array $Array -Name $ClientName -Enabled $true
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.
$ApiClientAuthInfo = New-Pfa2ArrayAuth -Endpoint $ArrayEndpoint -ApiClientName $Clientname -Issuer $ArrayIssuer -Username $ArrayUsername -Password $ArrayPassword -Force
Where,
- `$ArrayEndpoint` is the FlashArray IP or Name.
- `$ClientName` is the unique name for this API Client.
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
- `$ArrayUsername` is the FlashArray username.
- `$ArrayPassword` is the FlashArray Password (SecureString).
2. Create OAUTH2 session using the an API client KeyID and ClientID:
To create an OAUTH2 session you will need the following information from the API Client: `$clientID`, `$keyId`, and `$privateKeyFile`.
This information can be retrieved from the response of the `New-Pfa2ArrayAuth` command:
$clientId = $ApiClientAuthInfo.PureClientApiClientInfo.clientId
$keyId = $ApiClientAuthInfo.PureClientApiClientInfo.KeyId
$privateKeyFile = $ApiClientAuthInfo.pureCertInfo.privateKeyFile
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:
$clientId = $ApiClient.Id
$keyId = $ApiClient.KeyId
A third option is to use the command `pureapiclient list`, on the Purity CLI, to list all existing API Clients.
Finally, use the following command to create the OAUTH2 session:
$oauth = Connect-Pfa2Array -Endpoint $ArrayEndpoint -Username $ArrayUsername -Issuer $ArrayIssuer -ApiClientName $Clientname -ClientId $clientId -KeyId $keyId -PrivateKeyFile $privateKeyFile -PrivateKeyPassword $privateKeyPassword -IgnoreCertificateError
Where,
- `$ArrayEndpoint` is the FlashArray IP or Name.
- `$ArrayUsername` is the FlashArray username.
- `$ArrayIssuer` is the name of the identity provider that will be issuing ID Tokens for this API client.
- `$ClientName` is the unique name for this API Client.
- `$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.
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 the -Array parameter. The cmdlets will retrieve the FlashArray authentication information from PowerShell session variable.
// PowerShell Pipeline
Pure Storage PowerShell SDK 2 supports PowerShell Pipeline starting from 2.x version
## Examples
* Remove all of the hosts
Get-Pfa2Host -Array $Array | Remove-Pfa2Host -Array $Array
* Remove all of the hosts containing "test" in name
(Get-Pfa2host -Array $Array) | Where-Object {$_.name -like '*test*'} | Remove-Pfa2Host -Array $Array
// SSH Passthrough
Using Pure Storage PowerShell SDK 2 cmdlet 'Invoke-Pfa2CLICommand' SSH cli commands can be run on FlashArray.
$Password = ConvertTo-SecureString -String $ArrayPassword -AsPlainText -Force
$CommandText = "purevol create --size 10G test-volume-name"
Invoke-Pfa2CLICommand -EndPoint $ArrayEndpoint -Username $ArrayUsername -Password $Password -CommandText $CommandText"
// Sorting
See `-Sort` option for the Pure Storage PowerShell SDK 2 cmdlet.
## Examples
* Sort the list of volumes by name in ascending order
$Result = Get-Pfa2Volume -Array $Array -Sort "name"
* Sort the list of volumes by name in descending order
$Result = Get-Pfa2Volume -Array $Array -Sort "name-"
* Sort the list of volumes by name and then by provisioned
$Result = Get-Pfa2Volume -Array $Array -Sort "name,provisioned"
// Limit and Offset
See `-Limit` and `-Offset` options for Pure Storage PowerShell SDK 2 cmdlet
## Examples
* Get a limited set of volumes from FlashArray defined by `$Limit` (See `-Offset`)
$Volumes = Get-Pfa2Volume -Array $Array -Limit $Limit
* Get all volumes from offset `$Limit` (See `-Limit`)
$RemainingVolumes = Get-Pfa2Volume -Array $Array -Offset $Limit
// Filtering (Purity)
Please run `Help About_Pfa2Filtering` from PowerShell terminal or refer to the about_Pfa2Filtering.Help.txt file.
// Logging
## FlashArray Phonehome Logging
By default, PowerShell SDK activity is logged to a log file on the FlashArray is enabled.
To disable this logging, use the `-DisableVerbosePhoneHomeLogging` flag while creating connection to the array (see example below) :
$Array = Connect-Pfa2Array -Endpoint $ArrayName -Credential (Get-Credential) -DisableVerbosePhoneHomeLogging
Logs can be found in the array at /var/log/purity/external_rest.log-*
// Local logging
Very detailed logging on the internal and network operations is available in two forms.
1. For any *-Pfa2 Cmdlet you may add the `-Verbose` option.
Detailed log messages will be output on the PowerShell Verbose stream (stream 4) for this
command.
PowerShell also has Preference Variables that set the default logging level for all cmdlets.
See `$VerbosePreference` in `Get-Help About_Preference_Variables`
2. You can record detailed logs for all SDK operations to a log file.
Using the `Set-Pfa2Logging` cmdlet you provide a named file for the log to be output to.
Logging stops when you set the `-LogFilename` to empty.
// END OF FILE