Skip to content

Commit bf96bef

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

File tree

2 files changed

+173
-160
lines changed

2 files changed

+173
-160
lines changed

‎README.md‎

Lines changed: 9 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,164 +1,13 @@
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.
1+
# Pure Storage PowerShell SDK v2.2 Readme
32

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.
3+
The Pure Storage PowerShell SDK provides integration with the Purity Operating Environment and FlashArray. It provides functionalities of Purity's REST API as PowerShell cmdlets.
104

11-
## OAUTH2 Token
12-
To create a PowerShell Session using OAUTH2 follow the 2 steps bellow:
5+
### DOWNLOADS
6+
* [Installation Package](https://github.com/PureStorage-Connect/PowerShellSDK2/blob/master/PurePowerShellSDKInstaller.msi)
7+
* [Pure Storage Support -- Programming Interfaces > PowerShell](https://support.purestorage.com/Solutions/Programming_Interfaces/PowerShell)
138

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.
9+
### LATEST RELEASE
10+
* [v2.2.267](https://github.com/PureStorage-Connect/PowerShellSDK/releases/tag/v2.2.267)
16411

12+
### HISTORY
13+
* [v2.2.267] Initial release

‎readme.txt‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
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.
3+
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.
10+
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.
164+

0 commit comments

Comments
 (0)