ibm_power_hmc 0.3.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e42aa4d6eaa8915b8c37ce96aab995801533b81d8fa70b1e351bc550cc6eaa02
-  data.tar.gz: 6022fb088c67eeb0c20e8435c20567ef62fb34e365419cfa20f6fb9bc1e769f5
+  metadata.gz: 128d1d4297c8885e438de247ccf25a143c856a3cdff5e2894f49c0541b475a6e
+  data.tar.gz: ee5304a78bf10231755750641b3ea5fc11064bea52753db4c8c42456461bbd3f
 SHA512:
-  metadata.gz: 7ca0280aaeff1a1a0ce0cf5c53c40b6f0ddfc94725536e53d19031b1b107de4c8b44919580eaf1716e60f302bf339363508597b9188634412511bcc7869e4f83
-  data.tar.gz: b0251d621a729e2b7d97c7655709fd68bd1e796466967f2021924ab7658a12c2dc13c34dfe71597f96f6ed2114e24c405362232c4dab2e88b653afbe2b7d679a
+  metadata.gz: 7924966345897965a3789b26ef307ae3df5e5dccbdf316e0d59ed665d57a2ceaaf51128f225cd08a2544b6c77d54ae634b5f75d25bfa766c3672480f01fc72da
+  data.tar.gz: '078600454867693aaf410ca0a898eb5464f24b4dd40db56c61caa5145fbc54685f0819f576862f6065649f4a2d46dab2d5f838938b207fc376e563cfc724c56f'

data/.rubocop_local.yml

@@ -5,3 +5,5 @@ Layout/HashAlignment:
   Enabled: false
 Style/ConditionalAssignment:
   Enabled: false
+Style/OptionalBooleanParameter:
+  Enabled: false

data/README.md

@@ -52,9 +52,9 @@ Listing the logical partitions and virtual I/O servers of each managed system:
 
 ```ruby
 hc.managed_systems.each do |sys|
-  puts sys
-  puts hc.lpars(sys.uuid)
-  puts hc.vioses(sys.uuid)
+  puts sys.name
+  hc.lpars(sys.uuid).each { |lpar| puts lpar.name }
+  hc.vioses(sys.uuid).each { |vios| puts vios.name }
 end
 ```
 
@@ -73,9 +73,9 @@ hc.poweroff_lpar(lpar_uuid, { "operation" => "shutdown" })
 Processing events:
 
 ```ruby
-loop
+loop do
   hc.next_events.each do |event|
-    puts event
+    puts event.type
   end
 end
 ```

data/lib/ibm_power_hmc/connection.rb

@@ -8,15 +8,15 @@ module IbmPowerHmc
   # HMC REST Client connection.
   class Connection
     ##
-    # @!method initialize(host:, username: "hscroot", password:, port: 12_443, validate_ssl: true)
+    # @!method initialize(host:, password:, username: "hscroot", port: 12_443, validate_ssl: true)
     # Create a new HMC connection.
     #
     # @param host [String] Hostname of the HMC.
-    # @param username [String] User name.
     # @param password [String] Password.
+    # @param username [String] User name.
     # @param port [Integer] TCP port number.
     # @param validate_ssl [Boolean] Verify SSL certificates.
-    def initialize(host:, username: "hscroot", password:, port: 12_443, validate_ssl: true)
+    def initialize(host:, password:, username: "hscroot", port: 12_443, validate_ssl: true)
       @hostname = "#{host}:#{port}"
       @username = username
       @password = password
@@ -151,18 +151,13 @@ module IbmPowerHmc
     end
 
     ##
-    # @!method rename_lpar(lpar_uuid, newname)
+    # @!method rename_lpar(lpar_uuid, new_name)
     # Rename a logical partition.
     # @param lpar_uuid [String] The UUID of the logical partition.
-    # @param newname [String] The new name of the logical partition.
-    def rename_lpar(lpar_uuid, newname)
+    # @param new_name [String] The new name of the logical partition.
+    def rename_lpar(lpar_uuid, new_name)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}"
-      headers = {
-        :content_type => "application/vnd.ibm.powervm.uom+xml; type=LogicalPartition",
-      }
-      modify_object(method_url, headers) do |lpar|
-        lpar.xml.elements["PartitionName"].text = newname
-      end
+      modify_object(method_url) { |lpar| lpar.name = new_name }
     end
 
     ##
@@ -201,6 +196,227 @@ module IbmPowerHmc
       Parser.new(response.body).object(:VirtualIOServer)
     end
 
+    ##
+    # @!method virtual_switches(sys_uuid)
+    # Retrieve the list of virtual switches from a specified managed system.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @return [Array<IbmPowerHmc::VirtualSwitch>] The list of virtual switches.
+    def virtual_switches(sys_uuid)
+      method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualSwitch"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:VirtualSwitch)
+    end
+
+    ##
+    # @!method virtual_switch(vswitch_uuid, sys_uuid)
+    # Retrieve information about a virtual switch.
+    # @param vswitch_uuid [String] The UUID of the virtual switch.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @return [IbmPowerHmc::VirtualSwitch] The virtual switch.
+    def virtual_switch(vswitch_uuid, sys_uuid)
+      method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualSwitch/#{vswitch_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:VirtualSwitch)
+    end
+
+    ##
+    # @!method virtual_networks(sys_uuid)
+    # Retrieve the list of virtual networks from a specified managed system.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @return [Array<IbmPowerHmc::VirtualNetwork>] The list of virtual networks.
+    def virtual_networks(sys_uuid)
+      method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualNetwork"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:VirtualNetwork)
+    end
+
+    ##
+    # @!method virtual_network(vnet_uuid, sys_uuid)
+    # Retrieve information about a virtual network.
+    # @param vnet_uuid [String] The UUID of the virtual network.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @return [IbmPowerHmc::VirtualNetwork] The virtual network.
+    def virtual_network(vnet_uuid, sys_uuid)
+      method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualNetwork/#{vnet_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:VirtualNetwork)
+    end
+
+    ##
+    # @!method network_adapter_lpar(lpar_uuid, netadap_uuid = nil)
+    # Retrieve one or all virtual ethernet network adapters attached to a logical partition.
+    # @param lpar_uuid [String] UUID of the logical partition.
+    # @param netadap_uuid [String] UUID of the adapter to match (returns all adapters if omitted).
+    # @return [Array<IbmPowerHmc::ClientNetworkAdapter>, IbmPowerHmc::ClientNetworkAdapter] The list of network adapters.
+    def network_adapter_lpar(lpar_uuid, netadap_uuid = nil)
+      network_adapter("LogicalPartition", lpar_uuid, netadap_uuid)
+    end
+
+    ##
+    # @!method network_adapter_vios(vios_uuid, netadap_uuid = nil)
+    # Retrieve one or all virtual ethernet network adapters attached to a Virtual I/O Server.
+    # @param vios_uuid [String] UUID of the Virtual I/O Server.
+    # @param netadap_uuid [String] UUID of the adapter to match (returns all adapters if omitted).
+    # @return [Array<IbmPowerHmc::ClientNetworkAdapter>, IbmPowerHmc::ClientNetworkAdapter] The list of network adapters.
+    def network_adapter_vios(vios_uuid, netadap_uuid = nil)
+      network_adapter("VirtualIOServer", vios_uuid, netadap_uuid)
+    end
+
+    ##
+    # @!method sriov_elp_lpar(lpar_uuid, sriov_elp_uuid = nil)
+    # Retrieve one or all SR-IOV ethernet logical ports attached to a logical partition.
+    # @param lpar_uuid [String] UUID of the logical partition.
+    # @param sriov_elp_uuid [String] UUID of the port to match (returns all ports if omitted).
+    # @return [Array<IbmPowerHmc::SRIOVEthernetLogicalPort>, IbmPowerHmc::SRIOVEthernetLogicalPort] The list of ports.
+    def sriov_elp_lpar(lpar_uuid, sriov_elp_uuid = nil)
+      sriov_ethernet_port("LogicalPartition", lpar_uuid, sriov_elp_uuid)
+    end
+
+    ##
+    # @!method network_adapter_vios(vios_uuid, sriov_elp_uuid = nil)
+    # Retrieve one or all SR-IOV ethernet logical ports attached to a Virtual I/O Server.
+    # @param vios_uuid [String] UUID of the Virtual I/O Server.
+    # @param sriov_elp_uuid [String] UUID of the port to match (returns all ports if omitted).
+    # @return [Array<IbmPowerHmc::SRIOVEthernetLogicalPort>, IbmPowerHmc::SRIOVEthernetLogicalPort] The list of ports.
+    def sriov_elp_vios(vios_uuid, sriov_elp_uuid = nil)
+      sriov_ethernet_port("VirtualIOServer", vios_uuid, sriov_elp_uuid)
+    end
+
+    ##
+    # @!method vnic_dedicated(lpar_uuid, vnic_uuid = nil)
+    # Retrieve one or all dedicated virtual network interface controller (vNIC) attached to a logical partition.
+    # @param lpar_uuid [String] UUID of the logical partition.
+    # @param vnic_uuid [String] UUID of the vNIC to match (returns all vNICs if omitted).
+    # @return [Array<IbmPowerHmc::VirtualNICDedicated>, IbmPowerHmc::VirtualNICDedicated] The list of vNICs.
+    def vnic_dedicated(lpar_uuid, vnic_uuid = nil)
+      if vnic_uuid.nil?
+        method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/VirtualNICDedicated"
+        response = request(:get, method_url)
+        FeedParser.new(response.body).objects(:VirtualNICDedicated)
+      else
+        method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/VirtualNICDedicated/#{vnic_uuid}"
+        response = request(:get, method_url)
+        Parser.new(response.body).object(:VirtualNICDedicated)
+      end
+    end
+
+    ##
+    # @!method clusters
+    # Retrieve the list of clusters managed by the HMC.
+    # @return [Array<IbmPowerHmc::Cluster>] The list of clusters.
+    def clusters
+      method_url = "/rest/api/uom/Cluster"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:Cluster)
+    end
+
+    ##
+    # @!method cluster(cl_uuid)
+    # Retrieve information about a cluster.
+    # @param cl_uuid [String] The UUID of the cluster.
+    # @return [IbmPowerHmc::Cluster] The cluster.
+    def cluster(cl_uuid)
+      method_url = "/rest/api/uom/Cluster/#{cl_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:Cluster)
+    end
+
+    ##
+    # @!method ssps
+    # Retrieve the list of shared storage pools managed by the HMC.
+    # @return [Array<IbmPowerHmc::SharedStoragePool>] The list of shared storage pools.
+    def ssps
+      method_url = "/rest/api/uom/SharedStoragePool"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:SharedStoragePool)
+    end
+
+    ##
+    # @!method ssp(ssp_uuid)
+    # Retrieve information about a shared storage pool.
+    # @param ssp_uuid [String] The UUID of the shared storage pool.
+    # @return [IbmPowerHmc::SharedStoragePool] The shared storage pool.
+    def ssp(ssp_uuid)
+      method_url = "/rest/api/uom/SharedStoragePool/#{ssp_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:SharedStoragePool)
+    end
+
+    ##
+    # @!method tiers(group_name = nil)
+    # Retrieve the list of tiers that are part of shared storage pools managed by the HMC.
+    # @param group_name [String] The extended group attributes.
+    # @return [Array<IbmPowerHmc::Tier>] The list of tiers.
+    def tiers(group_name = nil)
+      method_url = "/rest/api/uom/Tier"
+      method_url += "?group=#{group_name}" unless group_name.nil?
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:Tier)
+    end
+
+    ##
+    # @!method tier(tier_uuid, ssp_uuid = nil, group_name = nil)
+    # Retrieve information about a tier.
+    # @param tier_uuid [String] The UUID of the tier.
+    # @param ssp_uuid [String] The UUID of the shared storage pool.
+    # @param group_name [String] The extended group attributes.
+    # @return [IbmPowerHmc::Tier] The tier.
+    def tier(tier_uuid, ssp_uuid = nil, group_name = nil)
+      if ssp_uuid.nil?
+        method_url = "/rest/api/uom/Tier/#{tier_uuid}"
+      else
+        method_url = "/rest/api/uom/SharedStoragePool/#{ssp_uuid}/Tier/#{tier_uuid}"
+      end
+      method_url += "?group=#{group_name}" unless group_name.nil?
+
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:Tier)
+    end
+
+    ##
+    # @!method templates_summary
+    # Retrieve the list of partition template summaries.
+    # @return [Array<IbmPowerHmc::PartitionTemplateSummary>] The list of partition template summaries.
+    def templates_summary
+      method_url = "/rest/api/templates/PartitionTemplate"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:PartitionTemplateSummary)
+    end
+
+    ##
+    # @!method template(template_uuid)
+    # Retrieve details for a particular partition template.
+    # @param template_uuid [String] UUID of the partition template.
+    # @return [IbmPowerHmc::PartitionTemplate] The partition template.
+    def template(template_uuid)
+      method_url = "/rest/api/templates/PartitionTemplate/#{template_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:PartitionTemplate)
+    end
+
+    ##
+    # @!method capture_lpar(lpar_uuid, sys_uuid, template_name, sync = true)
+    # Capture partition configuration as template.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param template_name [String] The name to be given for the new template.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def capture_lpar(lpar_uuid, sys_uuid, template_name, sync = true)
+      # Need to include session token in payload so make sure we are logged in
+      logon if @api_session_token.nil?
+      method_url = "/rest/api/templates/PartitionTemplate/do/capture"
+      params = {
+        "TargetUuid"              => lpar_uuid,
+        "NewTemplateName"         => template_name,
+        "ManagedSystemUuid"       => sys_uuid,
+        "K_X_API_SESSION_MEMENTO" => @api_session_token
+      }
+      job = HmcJob.new(self, method_url, "Capture", "PartitionTemplate", params)
+      job.run if sync
+      job
+    end
+
     ##
     # @!method poweron_lpar(lpar_uuid, params = {}, sync = true)
     # Power on a logical partition.
@@ -219,9 +435,7 @@ module IbmPowerHmc
     ##
     # @!method poweroff_lpar(lpar_uuid, params = {}, sync = true)
     # Power off a logical partition.
-    # @param lpar_uuid [String] The UUID of the logical partition.
-    # @param params [Hash] Job parameters.
-    # @param sync [Boolean] Start the job and wait for its completion.
+    # @param (see #poweron_lpar)
     # @return [IbmPowerHmc::HmcJob] The HMC job.
     def poweroff_lpar(lpar_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/do/PowerOff"
@@ -249,9 +463,7 @@ module IbmPowerHmc
     ##
     # @!method poweroff_vios(vios_uuid, params = {}, sync = true)
     # Power off a virtual I/O server.
-    # @param vios_uuid [String] The UUID of the virtual I/O server.
-    # @param params [Hash] Job parameters.
-    # @param sync [Boolean] Start the job and wait for its completion.
+    # @param (see #poweron_vios)
     # @return [IbmPowerHmc::HmcJob] The HMC job.
     def poweroff_vios(vios_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/VirtualIOServer/#{vios_uuid}/do/PowerOff"
@@ -279,9 +491,7 @@ module IbmPowerHmc
     ##
     # @!method poweroff_managed_system(sys_uuid, params = {}, sync = true)
     # Power off a managed system.
-    # @param sys_uuid [String] The UUID of the managed system.
-    # @param params [Hash] Job parameters.
-    # @param sync [Boolean] Start the job and wait for its completion.
+    # @param (see #poweron_managed_system)
     # @return [IbmPowerHmc::HmcJob] The HMC job.
     def poweroff_managed_system(sys_uuid, params = {}, sync = true)
       method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/do/PowerOff"
@@ -339,7 +549,24 @@ module IbmPowerHmc
         # No need to sleep as the HMC already waits a bit before returning 204
         break if response.code != 204 || !wait
       end
-      FeedParser.new(response.body).objects(:Event)
+      FeedParser.new(response.body).objects(:Event).map do |e|
+        data = e.data.split("/")
+        if data[-2].eql?("UserTask")
+          e.usertask = usertask(data.last)
+        end
+        e
+      end.compact
+    end
+
+    ##
+    # @!method usertask(uuid = true)
+    # Retrieve details of an event of type "user task".
+    # @param uuid [String] UUID of user task.
+    # @return [Hash] Hash of user task attributes.
+    def usertask(uuid)
+      method_url = "/rest/api/ui/UserTask/#{uuid}"
+      response = request(:get, method_url)
+      JSON.parse(response.body)
     end
 
     ##
@@ -418,6 +645,13 @@ module IbmPowerHmc
 
     private
 
+    # @!method modify_object(method_url, headers = {}, attempts = 5)
+    # Modify an object at a specified URI.
+    # @param method_url [String] The URL of the object to modify.
+    # @param headers [Hash] HTTP headers.
+    # @param attempts [Integer] Maximum number of retries.
+    # @yield [obj] The object to modify.
+    # @yieldparam obj [IbmPowerHmc::AbstractRest] The object to modify.
     def modify_object(method_url, headers = {}, attempts = 5)
       while attempts > 0
         response = request(:get, method_url)
@@ -426,16 +660,54 @@ module IbmPowerHmc
         yield obj
 
         # Use ETag to ensure object has not changed.
-        headers = headers.merge("If-Match" => obj.etag)
+        headers = headers.merge("If-Match" => obj.etag, :content_type => obj.content_type)
         begin
           request(:post, method_url, headers, obj.xml.to_s)
           break
         rescue HttpError => e
           attempts -= 1
-          # Will get 412 ("Precondition Failed" if ETag mismatches)
+          # Will get 412 ("Precondition Failed") if ETag mismatches
           raise if e.status != 412 || attempts == 0
         end
       end
     end
+
+    ##
+    # @!method network_adapter(vm_type, lpar_uuid, netadap_uuid)
+    # Retrieve one or all virtual ethernet network adapters attached to a Logical Partition or a Virtual I/O Server.
+    # @param vm_type [String] "LogicalPartition" or "VirtualIOServer".
+    # @param lpar_uuid [String] UUID of the Logical Partition or the Virtual I/O Server.
+    # @param netadap_uuid [String] UUID of the adapter to match (returns all adapters if nil).
+    # @return [Array<IbmPowerHmc::ClientNetworkAdapter>, IbmPowerHmc::ClientNetworkAdapter] The list of network adapters.
+    def network_adapter(vm_type, lpar_uuid, netadap_uuid)
+      if netadap_uuid.nil?
+        method_url = "/rest/api/uom/#{vm_type}/#{lpar_uuid}/ClientNetworkAdapter"
+        response = request(:get, method_url)
+        FeedParser.new(response.body).objects(:ClientNetworkAdapter)
+      else
+        method_url = "/rest/api/uom/#{vm_type}/#{lpar_uuid}/ClientNetworkAdapter/#{netadap_uuid}"
+        response = request(:get, method_url)
+        Parser.new(response.body).object(:ClientNetworkAdapter)
+      end
+    end
+
+    ##
+    # @!method sriov_ethernet_port(vm_type, lpar_uuid, sriov_elp_uuid)
+    # Retrieve one or all SR-IOV Ethernet loical ports attached to a Logical Partition or a Virtual I/O Server.
+    # @param vm_type [String] "LogicalPartition" or "VirtualIOServer".
+    # @param lpar_uuid [String] UUID of the Logical Partition or the Virtual I/O Server.
+    # @param sriov_elp_uuid [String] UUID of the port to match (returns all ports if nil).
+    # @return [Array<IbmPowerHmc::SRIOVEthernetLogicalPort>, IbmPowerHmc::SRIOVEthernetLogicalPort] The list of ports.
+    def sriov_ethernet_port(vm_type, lpar_uuid, sriov_elp_uuid)
+      if sriov_elp_uuid.nil?
+        method_url = "/rest/api/uom/#{vm_type}/#{lpar_uuid}/SRIOVEthernetLogicalPort"
+        response = request(:get, method_url)
+        FeedParser.new(response.body).objects(:SRIOVEthernetLogicalPort)
+      else
+        method_url = "/rest/api/uom/#{vm_type}/#{lpar_uuid}/SRIOVEthernetLogicalPort/#{sriov_elp_uuid}"
+        response = request(:get, method_url)
+        Parser.new(response.body).object(:SRIOVEthernetLogicalPort)
+      end
+    end
   end
 end

data/lib/ibm_power_hmc/job.rb

@@ -26,7 +26,7 @@ module IbmPowerHmc
     ##
     # @!method start
     # Start the job asynchronously.
-    # @return [String] The ID of the job.
+    # @return [String] The URL of the job.
     def start
       headers = {
         :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
@@ -47,7 +47,8 @@ module IbmPowerHmc
       end
       response = @conn.request(:put, @method_url, headers, doc.to_s)
       jobresp = Parser.new(response.body).object(:JobResponse)
-      @id = jobresp.id
+      # Save the URL of the job (JobID is not sufficient as not all jobs are in uom).
+      @href = jobresp.href.path
     end
 
     # @return [Hash] The job results returned by the HMC.
@@ -58,13 +59,12 @@ module IbmPowerHmc
     # Return the status of the job.
     # @return [String] The status of the job.
     def status
-      raise JobNotStarted unless defined?(@id)
+      raise JobNotStarted unless defined?(@href)
 
-      method_url = "/rest/api/uom/jobs/#{@id}"
       headers = {
         :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
-      response = @conn.request(:get, method_url, headers)
+      response = @conn.request(:get, @href, headers)
       jobresp = Parser.new(response.body).object(:JobResponse)
       @results = jobresp.results
       jobresp.status
@@ -100,17 +100,16 @@ module IbmPowerHmc
       start
       wait(timeout, poll_interval)
     ensure
-      delete if defined?(@id)
+      delete if defined?(@href)
     end
 
     ##
     # @!method delete
     # Delete the job from the HMC.
     def delete
-      raise JobNotStarted unless defined?(@id)
+      raise JobNotStarted unless defined?(@href)
 
-      method_url = "/rest/api/uom/jobs/#{@id}"
-      @conn.request(:delete, method_url)
+      @conn.request(:delete, @href)
       # Returns HTTP 204 if ok
     end
   end