purest 0.1.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0061492805748e646a06d9f5077446336d985ea40ff8ed76a3f9a5d8b60ff74d'
-  data.tar.gz: f58236ea14ff460b5698f0f348540c8c7fe87db762200fd37e8cb7ccfea3f505
+  metadata.gz: ab3ac73c9fc141dddadde6ec8435dcad4f40ff1011badec4ecdad573f0f2c166
+  data.tar.gz: b82e8f475af0b06238acd863ace402d9503acfb1d1d07f3e777a777934cafba9
 SHA512:
-  metadata.gz: e51d88129e1f4807334c14ee3f9787e79bbcce33254dc83fa21450d63d67f1cdf3a687b84210df13b5eb5fad51ee5d30de71a2149e7e59672243036e287f0cea
-  data.tar.gz: c5f9532c491299d10b1c8e7add8bcefe1905534ca6496f84a5cf7ac5450726e2175d7fa6bdf8530e6da5cf761e61447273c623b8562c09313546a5817314dcac
+  metadata.gz: ae3956cd6d9e11df30da2a7988fe5c4dbad2e91afff3913610d14775af84baef36104d327caf75cd4eb541d310554758d10389cf80e0b6740ec1f1e3d134e776
+  data.tar.gz: a21f3ca95452314c9e3ceeb283979a0903c8471a4fc468fdb69d9f2a91e3cffdecec42954de4dd4f114dee00eca5ae9540d8b84bf8b6af6393dd4f4b1efced7d

data/README.md

@@ -9,7 +9,7 @@ This started as sort of a labor of love/learning exercise, and sort of blossomed
 
 2) I am not affiliated with Pure Storage, beyond the fact that my company uses their product.
 
-3) This isn't done. What I think of as the 'core' functionality is there- you can manipulate volumes, hosts, and host groups, along with the array itself. I still need to add in classes for ProtectionGroups, Alerts/Messages, SNMP Manager Connections, SSL, Network Interfaces, Hardware, Apps, and Users.
+3) While all of the classes exist, currently only up to API version 1.11 is supported. 
 
 ## Requirements
 
@@ -34,8 +34,10 @@ end
 ```
 
 ## API options
-The various class methods of this gem turn the provided options into HTTP parameters, and are
-named accordingly. For instance, ```Purest::Volume.get({:snap => true})``` translates
+First: Authentication and session management is handled behind the scenes, you just need to supply your username/password in the configuration block (as shown in the example above). That's it.
+
+Second: The various class methods of this gem turn the provided options into HTTP parameters, and are
+named accordingly. For instance, ```Purest::Volume.get({:snap: true})``` translates
 to http://purehost.yourdomain.com/api/1.11/volume?snap=true. For a full list
 of options for a given class, Pure provides good documentation at:
 https://purehost.yourdomain.com/static/0/help/rest/.
@@ -43,79 +45,122 @@ https://purehost.yourdomain.com/static/0/help/rest/.
 Below I'll provide a large group of examples, but I won't be detailing every single method call with all of its possible options, for that I will again refer you to Pure's REST API docs.
 
 # Examples
-## Volumes
-Getting volumes:
+
+## Alerts
+Get information about alerts/alerting
 ```ruby
-# Get the full list of volumes
-Purest::Volume.get
+# List email recipients
+Purest::Alerts.get
 
-# Get a single volume
-Purest::Volume.get(:name => 'volume1')
+# List information about a specific email recipient
+Purest::Alerts.get(name: 'email@example.com')
+```
 
-# Get monitoring information about a volume
-Purest::Volume.get(:name => 'volume1', :action => 'monitor')
+Designate an email address to receive alerts
+```ruby
+Purest::Alerts.create(name: 'new-user@example.com')
+```
 
-# Get multiple volumes
-Purest::Volume.get(:names => ['volume1', 'volume2'])
+Updating/performing alert actions
+```ruby
+# Send a test alert
+Purest::Alerts.update(action: 'test')
 
-# Get a list of snapshots
-Purest::Volume.get(:snap => true)
+# Turn off alert sending for new-user@example.com
+Purest::Alerts.update(name: 'new-user@example.com', enabled: false)
+```
 
-# Get a single snapshot
-Purest::Volume.get(:name => 'volume1', :snap => true)
+Deleting an email address from list of addresses that receive alerts
+```ruby
+Purest::Alerts.delete(name: 'new-user@example.com')
+```
 
-# Get multiple snapshots
-Purest::Volume.get(:names => ['volume1', 'volume2'], :snap => true)
+## App
+```ruby
+# Teeny tiny class, can get apps or get apps and initiators
+Purest::App.get
+Purest::App.get(initiators: true)
+```
 
-# List block differences for the specified snapshot
-Purest::Volume.get(:name => 'volume1.snap', :show_diff => true, :block_size => 512, :length => '2G')
+## Cert
+List certificate attributes or export a certificate
+```ruby
+# Get certificate attributes
+Purest::Cert.get
 
-# List shared connections for a specified volume
-Purest::Volume.get(:name => 'volume1', :show_hgroup => true)
+# Export current certificate
+Purest::Cert.get(certificate: true)
 
-# List private connections for a specified volume
-Purest::Volume.get(:name => 'volume1', :show_host => true)
-```
+# Export current intermediate certificate
+Purest::Cert.get(intermediate_certificate: true)
 
-Creating volumes:
+# Get a CSR with current certificate attributes
+Purest::Cert.get(csr: true)
 
+# Get a CSR with current certificate attributes, but change the CN
+Purest::Cert.get(csr: true, common_name: 'host.example.com')
+```
+
+Create self signed certificate, or import one. If you're wondering why this
+is an update action and not a create action, I believe it comes down to the fact
+that the Pure Array already has a self signed cert from the get go so we're just updating in place.
 ```ruby
-# Creating a new volume
-Purest::Volume.create(:name => 'volume', :size => '10G')
+# Create a self signed certificate, using existing attributes
+Purest::Cert.update(self_signed: true)
 
-# Creating a new volume by copying another
-Purest::Volume.create(:name => 'volume, ':source => 'other_vol')
+# Create a self signed cert, using all existing attributes except the state
+Purest::Cert.update(self_signed: true, state: 'FL')
 
-# Overwriting a volume by copying another
-Purest::Volume.create(:name => 'volume', :source => 'other_vol', :overwrite => true)
+# Import a cert signed by a CA
+Purest::Cert.update(certificate: 'your_huge_certificate_string')
+```
 
-# Add a volume to a protection group
-Purest::Volume.create(:name => 'volume', :pgroup => 'protection-group')
+## Directory Service
+Get information about directory service
+```ruby
+Purest::DirectoryService.get
 ```
 
-Updating volumes
+Update information about a directory service
 ```ruby
-# Growing a volume
-Purest::Volume.update(:name => 'volume', :size => "15G")
+Purest::DirectoryService.update(bind_password: 'superpassword')
+```
 
-# Truncate (shrink) a volume
-Purest::Volume.update(:name => 'volume', :size => "10G", :truncate => true)
+## DNS
+Listing DNS attributes
+```ruby
+Purest::DNS.get
+```
 
-# Rename a volume
-Purest::Volume.update(:name => 'volume', :new_name => 'volume_renamed')
+Updating DNS attributes
+```ruby
+Purest::DNS.update(nameservers: ['newdns1', 'newdns2'])
 ```
 
-Deleting volumes
+## Drive information
+List flash modules, NVRAM modules, and their attributes
+```ruby
+Purest::Drive.get
 
+Purest::Drive.get(name: 'SH0.BAY0')
+```
+
+## Hardware
+List hardware components
 ```ruby
-# Delete a volume
-Purest::Volume.delete(:name => 'volume_to_delete')
+Purest::Hardware.get
 
-# Eradicating a volume
-Purest::Volume.delete(:name => 'volume_to_delete', :eradicate => true)
+# List a specific hardware component's attributes
+Purest::Hardware.get(name: 'SH0.BAY0')
+```
 
-# Deleting a volume from a protection group
-Purest::Volume.delete(:name => 'volume', :pgroup => 'pgroup1')
+Control visual identification of specified components
+```ruby
+# Turn the lights on
+Purest::Hardware.update(name: 'SH0.BAY0', identify: on)
+
+# Turn the lights off :(
+Purest::Hardware.update(name: 'SH0.BAY0', identify: off)
 ```
 
 ## Hosts
@@ -125,52 +170,151 @@ Getting hosts:
 Purest::Host.get
 
 # Get a list of hosts with performance data
-Purest::Host.get(:action => 'monitor')
+Purest::Host.get(action: 'monitor')
 
 # Get a single host on an array
-Purest::Host.get(:name => 'host123')
+Purest::Host.get(name: 'host123')
 
 # Get a list of hosts, by name, on an array
-Purest::Host.get(:names => ['host123', 'host456'])
+Purest::Host.get(names: ['host123', 'host456'])
+
+# Get volumes associated with specific host
+Purest::Host.get(name: 'hgroup1', show_volume: true)
 ```
 
 Creating hosts:
 ```ruby
 # Create a host
-Purest::Host.create({:name => 'host123'})
+Purest::Host.create(name: 'host123')
 
 # Create a host and set ISCSI IQNs
-Purest::Host.create(:name => 'host123', :iqnlist => ['iqnstuff-1', 'iqnstuff-2'])
+Purest::Host.create(name: 'host123', iqnlist: ['iqnstuff-1', 'iqnstuff-2'])
 
 # Add a host to a protection group
-Purest::Host.create(:name => 'host123', :protection_group => 'pgroup123')
+Purest::Host.create(name: 'host123', protection_group: 'pgroup123')
 
 # Connect a volume to a host
-Purest::Host.create(:name => 'host123', :volume => 'volume123')
+Purest::Host.create(name: 'host123', volume: 'volume123')
 ```
 
 Updating hosts:
 ```ruby
 # Rename a host
-Purest::Host.update(:name => 'host123', :new_name => 'host456')
+Purest::Host.update(name: 'host123', new_name: 'host456')
 
 # Set the host username/password for CHAP
-Purest::Host.update(:name => 'host123', :host_user => 'username', :host_password => 'supersecretpassword')
+Purest::Host.update(name: 'host123', host_user: 'username', host_password: 'supersecretpassword')
 ```
 
 Deleting hosts:
 ```ruby
 # Delete a host
-Purest::Host.delete(:name => 'host123')
+Purest::Host.delete(name: 'host123')
 
 # Remove a host from a protection group
-Purest::Host.delete(:name => 'host123', :protection_group => 'pgroup123')
+Purest::Host.delete(name: 'host123', protection_group: 'pgroup123')
 
 # Remove the connection between a host and a volume
-Purest::Host.delete(:name => 'host123', :volume => 'volume123')
+Purest::Host.delete(name: 'host123', volume: 'volume123')
+```
+
+## Host Groups
+Getting information about host groups
+```ruby
+# Get a list of host groups
+Purest::HostGroup.get
+
+# Get a single host group
+Purest::HostGroup.get(name: 'hgroup1')
+
+# Get a list of host groups, with monitoring information
+Purest::HostGroup.get(names: ['hgroup1', 'hgroup2'], action: 'monitor')
+
+# Get a list of volumes associated with a specified host
+Purest::HostGroup.get(name: 'hgroup1', show_volume: true)
+```
+
+Creating host groups
+```ruby
+# Create a host group with a specified name
+Purest::HostGroup.create(name: 'hgroup1')
+
+# Create a host group and supply its host members
+Purest::HostGroup.create(name: 'hgroup1', hostlist: ['host1', 'host2'])
+
+# Add a host group to a protection group
+Purest::HostGroup.create(name: 'hgroup1', protection_group: 'pgroup1')
+
+# Connect a volume to all hosts in a specified host group
+Purest::HostGroup.create(name: 'hgroup1', volume: 'v3')
 ```
 
-# Physical Arrays
+Updating host groups
+```ruby
+# Renaming a host group
+Purest::HostGroup.update(name: 'hgroup1', new_name: 'hgroup1-renamed')
+
+# Replace the list of member hosts
+Purest::HostGroup.update(name: 'hgroup1', hostlist: ['host1', 'host2'])
+
+# Add a list of hosts to existing host list
+Purest::HostGroup.update(name: 'hgroup1', addhostlist: ['host3', 'host4'])
+
+# Remove a list of hosts from a host list
+Purest::HostGroup.update(name: 'hgroup1', remhostlist: ['host1'])
+```
+
+Deleting host groups
+```ruby
+# Delete a host group
+Purest::HostGroup.delete(name: 'hgroup1')
+
+# Remove a host group member from a protection group
+Purest::HostGroup.delete(name: 'hgroup1', protection_group: 'pgroup1')
+
+# Break the connection between a host group and a volume
+Purest::HostGroup.delete(name: 'hgroup1', volume: 'volume1')
+```
+
+## Messages
+List alert events, audit records, etc
+```ruby
+Purest::Messages.get
+```
+
+Flag/unflag a message
+```ruby
+Purest::Messages.update(id: 2, flagged: true)
+```
+
+## Network
+List network interfaces
+```ruby
+# Get network interfaces and their statuses
+Purest::Network.get
+
+# Get attributes about a specific network component
+Purest::Network.get(name: 'ct0.eth0')
+```
+
+Create a VLAN interface
+```ruby
+# Create a vlan with a specified subnet
+Purest::Network.create(subnet: 'subnet10')
+```
+
+Perform network interface actions or update attributes
+```ruby
+# Set MTU
+Purest::Network.update(mtu: 2000)
+```
+
+Delete a VLAN interface
+```ruby
+Purest::Network.delete(name: 'ct0.eth0')
+```
+
+## Physical Arrays
 
 List the attributes on an array:
 ```ruby
@@ -178,83 +322,240 @@ List the attributes on an array:
 Purest::PhysicalArray.get
 
 # List connected arrays
-Purest::PhysicalArray.get(:connection => true)
+Purest::PhysicalArray.get(connection: true)
 ```
 
 Create a connection between two arrays:
 ```ruby
-Purest::PhysicalArray.create(:connection_key => '<key>', :management_address => 'hostname', :type => ['replication'])
+Purest::PhysicalArray.create(connection_key: '<key>', management_address: 'hostname', type: ['replication'])
 ```
 
 Update the attributes on an array:
 ```ruby
 # rename an array
-Purest::PhysicalArray.update(:new_name => 'new_name')
+Purest::PhysicalArray.update(new_name: 'new_name')
 ```
 
 Disconnect the current array from a specified array:
 ```ruby
 # Given that your pure is purehost.yourdomain.com, as defined in the config block above
 # Disconnect purehost2.yourdomain.com from yours
-Purest::PhysicalArray.delete(:name => 'purehost2.yourdomain.com')
+Purest::PhysicalArray.delete(name: 'purehost2.yourdomain.com')
 ```
 
-# Host Groups
-Getting information about host groups
+## Port
+Getting information about ports, 'cause that's all you get to do
 ```ruby
-# Get a list of host groups
-Purest::HostGroup.get
+# Get port information
+Purest::Port.get
 
-# Get a single host group
-Purest::HostGroup.get(:name => 'hgroup1')
+# Get port information + initiator information = winning
+Purest::Port.get(initiators: true)
+```
 
-# Get a list of host groups, with monitoring information
-Purest::HostGroup.get(:names => ['hgroup1', 'hgroup2'], :action => 'monitor')
+## Protection Groups
+Getting information about protection groups
+```ruby
+# Get a list of protection groups
+Purest::ProtectionGroup.get
 
-# Get a list of volumes associated with a specified host
-Purest::HostGroup.get(:name => 'hgroup1', :show_volumes => true)
+# Get a list of protection groups pending deletion
+Purest::ProtectionGroup.get(pending: true)
 ```
 
-Creating host groups
+Creating protection groups
 ```ruby
-# Create a host group with a specified name
-Purest::HostGroup.create(:name => 'hgroup1')
+# Create a protection group
+Purest::ProtectionGroup.create(name: 'pgroup1')
 
-# Create a host group and supply its host members
-Purest::HostGroup.create(:name => 'hgroup1', :hostlist => ['host1', 'host2'])
+# Create a protection group with a host list
+Purest::ProtectionGroup.create(name: 'pgroup1', hostlist: ['host1', 'host2'])
+```
 
-# Add a host group to a protection group
-Purest::HostGroup.create(:name => 'hgroup1', :protection_group => 'pgroup1')
+Updating protection groups
+```ruby
+# Renaming a protection group
+Purest::ProtectionGroup.update(name: 'pgroup1', new_name: 'pgroup1-renamed')
 
-# Connect a volume to all hosts in a specified host group
-Purest::HostGroup.create(:name => 'hgroup1', :volume => 'v3')
+# Add a list of hosts to an existing protection group's host list
+Purest::ProtectionGroup.update(name: 'pgroup1', addhostlist: ['host3', 'host4'])
 ```
 
-Updating host groups
+Deleting a protection group
 ```ruby
-# Renaming a host group
-Purest::HostGroup.update(:name => 'hgroup1', :new_name => 'hgroup1-renamed')
+# Delete it, but allow for it to remain during the 24 hour grace period
+Purest::ProtectionGroup.delete(name: 'pgroup1')
 
-# Replace the list of member hosts
-Purest::HostGroup.update(:name => 'hgroup1', :hostlist => ['host1', 'host2'])
+# Delete it, with extreme prejudice
+Purest::ProtectionGroup.delete(name: 'pgroup1', eradicate: true)
+```
 
-# Add a list of hosts to existing host list
-Purest::HostGroup.update(:name => 'hgroup1', :addhostlist => ['host3', 'host4'])
+## SNMP
+Getting SNMP information
+```ruby
+# Get a list of SNMP managers
+Purest::SNMP.get
 
-# Remove a list of hosts from a host list
-Purest::HostGroup.update(:name => 'hgroup1', :remhostlist => ['host1'])
+# List SNMP v3 engine ID
+Purest::SNMP.get(engine_id: true)
 ```
 
-Deleting host groups
+Creating an SNMP manager
 ```ruby
-# Delete a host group
-Purest::HostGroup.delete(:name => 'hgroup1')
+# Create an SNMP manager
+Purest::SNMP.create(name: 'snmp-manager1', host: 'snmp.yourdomain.com')
 
-# Remove a host group member from a protection group
-Purest::HostGroup.delete(:name => 'hgroup1', :protection_group => 'pgroup1')
+# Create an SNMP manager pointed at an IPv4 address with a custom port
+Purest::SNMP.create(name: 'snmp-manager1', host: '111.11.11.111:222')
 
-# Break the connection between a host group and a volume
-Purest::HostGroup.delete(:name => 'hgroup1', :volume => 'volume1')
+# For those brave few; the strong souls using IPv6 with a custom port
+Purest::SNMP.create(:name: 'snmp-manager1', :host: '[2001:db8:0:1]:222')
+```
+
+Updating an existing SNMP manager
+```ruby
+# Renaming an SNMP manager
+Purest::SNMP.update(name: 'snmp-manager1', new_name: 'snmp-manager-renamed')
+
+# For those not so brave; the weak souls who give up using IPv6 with a custom port
+Purest::SNMP.update(name: 'snmp-manager1', host: '111.11.11.111:222')
+```
+
+Deleting an SNMP manager
+```ruby
+# Delete an SNMP manager
+Purest::SNMP.delete(name: 'snmp-manager1')
+```
+
+## Subnet
+Getting information about subnets
+```ruby
+Purest::Subnet.get
+
+# Specify a subnet
+Purest::Subnet.get(name: 'subnet10')
+```
+
+Creating a subnet
+```ruby
+Purest::Subnet.create(name: 'subnet20', gateway: '11.11.11.1')
+```
+
+Updating a subnet
+```ruby
+# Rename a subnet
+Purest::Subnet.update(name: 'subnet20', new_name: 'subnet21')
+```
+
+Deleting a subnet
+```ruby
+Purest::Subnet.delete(name: 'subnet21')
+```
+
+## Users
+Getting information about users
+```ruby
+Purest::Users.get
+
+# Specific user information
+Purest::Users.get(name: 'paxton.fettle')
+
+# List the API token of a given user
+Purest::Users.get(name: 'paxton.fettle', api_token: true)
+```
+
+Create an API token for an existing user
+```ruby
+Purest::Users.create(name: 'paxton.fettle')
+```
+
+Updating user related stuff
+```ruby
+# Clear all user permission cache entries
+Purest::Users.update(clear: true)
+
+# Update a specific user's public key
+Purest::Users.update(name: 'paxton.fettle', publickey: 'hugepublickeystring')
+```
+
+Delete API token for a user
+```ruby
+Purest::Users.delete(name: 'paxton.fettle')
+```
+
+## Volumes
+Getting volumes:
+```ruby
+# Get the full list of volumes
+Purest::Volume.get
+
+# Get a single volume
+Purest::Volume.get(name: 'volume1')
+
+# Get monitoring information about a volume
+Purest::Volume.get(name: 'volume1', action: 'monitor')
+
+# Get multiple volumes
+Purest::Volume.get(names: ['volume1', 'volume2'])
+
+# Get a list of snapshots
+Purest::Volume.get(snap: true)
+
+# Get a single snapshot
+Purest::Volume.get(name: 'volume1', snap: true)
+
+# Get multiple snapshots
+Purest::Volume.get(names: ['volume1', 'volume2'], snap: true)
+
+# List block differences for the specified snapshot
+Purest::Volume.get(name: 'volume1.snap', show_diff: true, block_size: 512, length: '2G')
+
+# List shared connections for a specified volume
+Purest::Volume.get(name: 'volume1', show_hgroup: true)
+
+# List private connections for a specified volume
+Purest::Volume.get(:name: 'volume1', :show_host: true)
+```
+
+Creating volumes:
+
+```ruby
+# Creating a new volume
+Purest::Volume.create(name: 'volume', size: '10G')
+
+# Creating a new volume by copying another
+Purest::Volume.create(name: 'volume', source: 'other_vol')
+
+# Overwriting a volume by copying another
+Purest::Volume.create(name: 'volume', source: 'other_vol', overwrite: true)
+
+# Add a volume to a protection group
+Purest::Volume.create(name: 'volume', protection_group: 'protection-group')
+```
+
+Updating volumes
+```ruby
+# Growing a volume
+Purest::Volume.update(name: 'volume', size: "15G")
+
+# Truncate (shrink) a volume
+Purest::Volume.update(name: 'volume', size: "10G", truncate: true)
+
+# Rename a volume
+Purest::Volume.update(name: 'volume', new_name: 'volume_renamed')
+```
+
+Deleting volumes
+
+```ruby
+# Delete a volume
+Purest::Volume.delete(name: 'volume_to_delete')
+
+# Eradicating a volume
+Purest::Volume.delete(name: 'volume_to_delete', eradicate: true)
+
+# Deleting a volume from a protection group
+Purest::Volume.delete(name: 'volume', protection_group: 'pgroup1')
 ```
 
 # Specs
@@ -274,11 +575,20 @@ password: 'api-password'
 url: 'https://yoursuperawesomepurehost.com'
 ```
 
-Execute integration tests:
+There are a few ways you can execute the integration tests:
 ```
+# This will execute against the latest API version the gem is aware of, right now that is 1.11
 rspec -t integration
+
+# This will execute against a specific version
+API_VERSION=1.10 rspec -t integration
+
+# This will execute against all specified versions
+API_VERSION=1.1,1.2,1.5 rspec -t integration
+
+# And finally, if you wish to execute integration tests against every version
+ALL_VERSIONS=true rspec -t integration
 ```
 
-By default, this will run against version 1.1 to 1.11 of the API. This is useful for ensuring functionality added/subtracted to this project is programmatically tested against all versions of the API. I mostly did this as an exercise, that being said I think it provides a lot of usefulness and if it can be improved let me know (or submit a PR).
 
-It is worth mentioning, this generates a fair bit of work for your Pure array so...you've been warned.
+It is worth mentioning, this generates a fair bit of work for your Pure array so...you've been warned. All of that being said, the integration testing is somewhat sparse at the moment