ibm_power_hmc 0.1.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 214dfa7f9a89d236f1f9bc4ee927b619596a0fabe59c2f596359637e891601ab
-  data.tar.gz: 2affd160febc3952014ab522bb9b0f89b0ebef6d785720d2d8d2a875cd1df918
+  metadata.gz: c19305b95374164ab2a6e6168a4a292ea0666065cbcbe8f05dea30483b622055
+  data.tar.gz: be50d67e7c462cc17f20be3f643c6029e4f2ba7d43f872f1821bbe428f0e11fe
 SHA512:
-  metadata.gz: 3e6e6ae8b4c7d84eea70e3328ea44834a5b95ecd98fbe6a31c045e575951b6c17751ca7d6517d3ad58647b5c8b7e1321470c368c48018c31a450a28ba40463e5
-  data.tar.gz: f9139f2ea1a83d0abedc3c73832450e20fa4fcf7c56cc65c50ec5b14750bb5bb2eb17d7948ffc22d5887984d0f412ae8213a237892350e55f0cd55a49af80f30
+  metadata.gz: 1191f64dd2f5c550d25a372b4a0502dd4e7b5a8e779a2dacdf079a22f3a8b8092af6e4ddff514b0e06dddf8239985033034959e385f951f2f535f092866cbd12
+  data.tar.gz: d6af992547d99624f59e6eb5ec3404768c91d1b9c9809e9542966fee15b4a350e8b8803e6fd25a597c48699b630171b7cae8327108f0ec6616e2329c5441bf1c

data/.gitignore

@@ -1,3 +1,4 @@
+/Gemfile.lock
 /.bundle/
 /.yardoc
 /_yardoc/

data/.rubocop_local.yml

@@ -2,6 +2,8 @@ AllCops:
   Exclude:
   - '*.gemspec'
 Layout/HashAlignment:
-  EnforcedHashRocketStyle: key
+  Enabled: false
 Style/ConditionalAssignment:
-  EnforcedStyle: assign_inside_condition
+  Enabled: false
+Style/OptionalBooleanParameter:
+  Enabled: false

data/README.md

@@ -42,6 +42,12 @@ puts hmc.name
 puts hmc.version
 ```
 
+Retrieving managed systems that are powered on:
+
+```ruby
+hc.managed_systems("State" => "operating")
+```
+
 Listing the logical partitions and virtual I/O servers of each managed system:
 
 ```ruby

data/lib/ibm_power_hmc/connection.rb

@@ -2,24 +2,21 @@
 
 # Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  require_relative 'pcm.rb'
-
   class Error < StandardError; end
 
   ##
   # 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)
-      # Damien: use URI::HTTPS
+    def initialize(host:, password:, username: "hscroot", port: 12_443, validate_ssl: true)
       @hostname = "#{host}:#{port}"
       @username = username
       @password = password
@@ -37,10 +34,8 @@ module IbmPowerHmc
         :content_type => "application/vnd.ibm.powervm.web+xml; type=LogonRequest"
       }
       doc = REXML::Document.new("")
-      doc.add_element("LogonRequest", {
-                        "xmlns" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "schemaVersion" => "V1_1_0"
-                      })
+      doc.add_element("LogonRequest", "schemaVersion" => "V1_1_0")
+      doc.root.add_namespace("http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
       doc.root.add_element("UserID").text = @username
       doc.root.add_element("Password").text = @password
 
@@ -69,15 +64,6 @@ module IbmPowerHmc
       @api_session_token = nil
     end
 
-    def parse_feed(doc, myclass)
-      objs = []
-      doc.each_element("feed/entry") do |entry|
-        objs << myclass.new(entry)
-      end
-      objs
-    end
-    private :parse_feed
-
     ##
     # @!method management_console
     # Retrieve information about the management console.
@@ -85,20 +71,20 @@ module IbmPowerHmc
     def management_console
       method_url = "/rest/api/uom/ManagementConsole"
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
       # This request returns a feed with a single entry.
-      parse_feed(doc, ManagementConsole).first
+      FeedParser.new(response.body).objects(:ManagementConsole).first
     end
 
     ##
-    # @!method managed_systems
+    # @!method managed_systems(search = {})
     # Retrieve the list of systems managed by the HMC.
+    # @param search [Hash] The optional property name and value to match.
     # @return [Array<IbmPowerHmc::ManagedSystem>] The list of managed systems.
-    def managed_systems
+    def managed_systems(search = {})
       method_url = "/rest/api/uom/ManagedSystem"
+      search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      parse_feed(doc, ManagedSystem)
+      FeedParser.new(response.body).objects(:ManagedSystem)
     end
 
     ##
@@ -106,31 +92,30 @@ module IbmPowerHmc
     # Retrieve information about a managed system.
     # @param sys_uuid [String] The UUID of the managed system.
     # @param group_name [String] The extended group attributes.
-    # @return [IbmPowerHmc::ManagedSystem] The logical partition.
+    # @return [IbmPowerHmc::ManagedSystem] The managed system.
     def managed_system(sys_uuid, group_name = nil)
       method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}"
       method_url += "?group=#{group_name}" unless group_name.nil?
 
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      entry = doc.elements["entry"]
-      ManagedSystem.new(entry)
+      Parser.new(response.body).object(:ManagedSystem)
     end
 
     ##
-    # @!method lpars(sys_uuid = nil)
+    # @!method lpars(sys_uuid = nil, search = {})
     # Retrieve the list of logical partitions managed by the HMC.
     # @param sys_uuid [String] The UUID of the managed system.
+    # @param search [Hash] The optional property name and value to match.
     # @return [Array<IbmPowerHmc::LogicalPartition>] The list of logical partitions.
-    def lpars(sys_uuid = nil)
+    def lpars(sys_uuid = nil, search = {})
       if sys_uuid.nil?
         method_url = "/rest/api/uom/LogicalPartition"
+        search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       else
         method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/LogicalPartition"
       end
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      parse_feed(doc, LogicalPartition)
+      FeedParser.new(response.body).objects(:LogicalPartition)
     end
 
     ##
@@ -149,15 +134,14 @@ module IbmPowerHmc
       method_url += "?group=#{group_name}" unless group_name.nil?
 
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      entry = doc.elements["entry"]
-      LogicalPartition.new(entry)
+      Parser.new(response.body).object(:LogicalPartition)
     end
 
     ##
     # @!method lpar_quick_property(lpar_uuid, property_name)
     # Retrieve a quick property of a logical partition.
     # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param property_name [String] The quick property name.
     # @return [String] The quick property value.
     def lpar_quick_property(lpar_uuid, property_name)
       method_url = "/rest/api/uom/LogicalPartition/#{lpar_uuid}/quick/#{property_name}"
@@ -167,19 +151,31 @@ module IbmPowerHmc
     end
 
     ##
-    # @!method vioses(sys_uuid = nil)
+    # @!method rename_lpar(lpar_uuid, new_name)
+    # Rename a logical partition.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @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}"
+
+      modify_object(method_url) { |lpar| lpar.name = new_name }
+    end
+
+    ##
+    # @!method vioses(sys_uuid = nil, search = {})
     # Retrieve the list of virtual I/O servers managed by the HMC.
     # @param sys_uuid [String] The UUID of the managed system.
+    # @param search [Hash] The optional property name and value to match.
     # @return [Array<IbmPowerHmc::VirtualIOServer>] The list of virtual I/O servers.
-    def vioses(sys_uuid = nil)
+    def vioses(sys_uuid = nil, search = {})
       if sys_uuid.nil?
         method_url = "/rest/api/uom/VirtualIOServer"
+        search.each { |key, value| method_url += "/search/(#{key}==#{value})" }
       else
         method_url = "/rest/api/uom/ManagedSystem/#{sys_uuid}/VirtualIOServer"
       end
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      parse_feed(doc, VirtualIOServer)
+      FeedParser.new(response.body).objects(:VirtualIOServer)
     end
 
     ##
@@ -198,9 +194,27 @@ module IbmPowerHmc
       method_url += "?group=#{group_name}" unless group_name.nil?
 
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      entry = doc.elements["entry"]
-      VirtualIOServer.new(entry)
+      Parser.new(response.body).object(:VirtualIOServer)
+    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>] 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>] The list of network adapters.
+    def network_adapter_vios(vios_uuid, netadap_uuid = nil)
+      network_adapter("VirtualIOServer", vios_uuid, netadap_uuid)
     end
 
     ##
@@ -221,9 +235,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"
@@ -251,9 +263,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"
@@ -281,9 +291,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"
@@ -293,6 +301,21 @@ module IbmPowerHmc
       job
     end
 
+    ##
+    # @!method remove_connection(hmc_uuid, sys_uuid, sync = true)
+    # Remove a managed system from the management console.
+    # @param hmc_uuid [String] The UUID of the management console.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def remove_connection(hmc_uuid, sys_uuid, sync = true)
+      method_url = "/rest/api/uom/ManagementConsole/#{hmc_uuid}/ManagedSystem/#{sys_uuid}/do/RemoveConnection"
+
+      job = HmcJob.new(self, method_url, "RemoveConnection", "ManagedSystem")
+      job.run if sync
+      job
+    end
+
     ##
     # @!method cli_run(hmc_uuid, cmd, sync = true)
     # Run a CLI command on the HMC as a job.
@@ -312,6 +335,29 @@ module IbmPowerHmc
       job
     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 next_events(wait = true)
     # Retrieve a list of events that occured since last call.
@@ -326,12 +372,22 @@ module IbmPowerHmc
         # No need to sleep as the HMC already waits a bit before returning 204
         break if response.code != 204 || !wait
       end
-      doc = REXML::Document.new(response.body)
-      parse_feed(doc, Event)
+      FeedParser.new(response.body).objects(:Event)
+    end
+
+    ##
+    # @!method schema(type)
+    # Retrieve the XML schema file for a given object type.
+    # @param type [String] The object type (e.g. "LogicalPartition", "inc/Types")
+    # @return [REXML::Document] The XML schema file.
+    def schema(type)
+      method_url = "/rest/api/web/schema/#{type}.xsd"
+      response = request(:get, method_url)
+      REXML::Document.new(response.body)
     end
 
     class HttpError < Error
-      attr_reader :status, :uri, :reason, :message
+      attr_reader :status, :uri, :reason, :message, :original_exception
 
       ##
       # @!method initialize(err)
@@ -339,18 +395,24 @@ module IbmPowerHmc
       # @param err [RestClient::Exception] The REST client exception.
       def initialize(err)
         super
+        @original_exception = err
         @status = err.http_code
+        @message = err.message
 
         # Try to parse body as an HttpErrorResponse
-        doc = REXML::Document.new(err.response.body)
-        entry = doc.elements["entry"]
-        unless entry.nil?
-          resp = HttpErrorResponse.new(entry)
-          @uri = resp.uri
-          @reason = resp.reason
-          @message = resp.message
+        unless err.response.nil?
+          resp = Parser.new(err.response.body).object(:HttpErrorResponse)
+          unless resp.nil?
+            @uri = resp.uri
+            @reason = resp.reason
+            @message = resp.message
+          end
         end
       end
+
+      def to_s
+        "msg=\"#{@message}\" status=\"#{@status}\" reason=\"#{@reason}\" uri=#{@uri}"
+      end
     end
 
     ##
@@ -364,11 +426,13 @@ module IbmPowerHmc
     def request(method, url, headers = {}, payload = nil)
       logon if @api_session_token.nil?
       reauth = false
+      # Check for relative URLs
+      url = "https://#{@hostname}#{url}" if url.start_with?("/")
       begin
-        headers = headers.merge({"X-API-Session" => @api_session_token})
+        headers = headers.merge("X-API-Session" => @api_session_token)
         RestClient::Request.execute(
           :method => method,
-          :url => "https://" + @hostname + url,
+          :url => url,
           :verify_ssl => @verify_ssl,
           :payload => payload,
           :headers => headers
@@ -384,5 +448,52 @@ module IbmPowerHmc
         raise HttpError.new(e), "REST request failed"
       end
     end
+
+    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)
+        obj = Parser.new(response.body).object
+
+        yield obj
+
+        # Use ETag to ensure object has not changed.
+        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
+          raise if e.status != 412 || attempts == 0
+        end
+      end
+    end
+
+    ##
+    # @!method network_adapter_lpar(lpar_uuid, netadap_uuid = nil)
+    # Retrieve one or all virtual ethernet network adapters attached to a Logical Partition or a Virtual I/O Server.
+    # @param vm_type [String] "Logical Partition" 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>] 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"
+      else
+        method_url = "/rest/api/uom/#{vm_type}/#{lpar_uuid}/ClientNetworkAdapter/#{netadap_uuid}"
+      end
+
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:ClientNetworkAdapter)
+    end
   end
 end

data/lib/ibm_power_hmc/job.rb

@@ -24,7 +24,7 @@ module IbmPowerHmc
     end
 
     ##
-    # @!method status
+    # @!method start
     # Start the job asynchronously.
     # @return [String] The ID of the job.
     def start
@@ -32,25 +32,22 @@ module IbmPowerHmc
         :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
       doc = REXML::Document.new("")
-      doc.add_element("JobRequest:JobRequest", {
-                        "xmlns:JobRequest" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "xmlns" => "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/",
-                        "schemaVersion" => "V1_1_0"
-                      })
-      op = doc.root.add_element("RequestedOperation", {"schemaVersion" => "V1_1_0"})
+      doc.add_element("JobRequest:JobRequest", "schemaVersion" => "V1_1_0")
+      doc.root.add_namespace("http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
+      doc.root.add_namespace("JobRequest", "http://www.ibm.com/xmlns/systems/power/firmware/web/mc/2012_10/")
+      op = doc.root.add_element("RequestedOperation", "schemaVersion" => "V1_1_0")
       op.add_element("OperationName").text = @operation
       op.add_element("GroupName").text = @group
-      # Damien: ProgressType?
-      jobparams = doc.root.add_element("JobParameters", {"schemaVersion" => "V1_1_0"})
+
+      jobparams = doc.root.add_element("JobParameters", "schemaVersion" => "V1_1_0")
       @params.each do |key, value|
-        jobparam = jobparams.add_element("JobParameter", {"schemaVersion" => "V1_1_0"})
+        jobparam = jobparams.add_element("JobParameter", "schemaVersion" => "V1_1_0")
         jobparam.add_element("ParameterName").text = key
         jobparam.add_element("ParameterValue").text = value
       end
       response = @conn.request(:put, @method_url, headers, doc.to_s)
-      doc = REXML::Document.new(response.body)
-      info = doc.root.elements["content/JobResponse:JobResponse"]
-      @id = info.elements["JobID"].text
+      jobresp = Parser.new(response.body).object(:JobResponse)
+      @id = jobresp.id
     end
 
     # @return [Hash] The job results returned by the HMC.
@@ -68,20 +65,9 @@ module IbmPowerHmc
         :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
       response = @conn.request(:get, method_url, headers)
-      doc = REXML::Document.new(response.body)
-      info = doc.root.elements["content/JobResponse:JobResponse"]
-      status = info.elements["Status"].text
-      # Damien: also retrieve "ResponseException/Message"?
-
-      # Gather Job results returned by the HMC.
-      @results = {}
-      info.each_element("Results/JobParameter") do |result|
-        name = result.elements["ParameterName"].text.strip
-        value = result.elements["ParameterValue"].text.strip
-        @results[name] = value
-      end
-
-      status
+      jobresp = Parser.new(response.body).object(:JobResponse)
+      @results = jobresp.results
+      jobresp.status
     end
 
     ##
@@ -112,8 +98,7 @@ module IbmPowerHmc
     # @return [String] The status of the job.
     def run(timeout = 120, poll_interval = 0)
       start
-      status = wait(timeout, poll_interval)
-      status
+      wait(timeout, poll_interval)
     ensure
       delete if defined?(@id)
     end

data/lib/ibm_power_hmc/parser.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'uri'
+
+module IbmPowerHmc
+  ##
+  # Generic parser for HMC K2 XML responses.
+  class Parser
+    def initialize(body)
+      @doc = REXML::Document.new(body)
+    end
+
+    ##
+    # @!method entry
+    # Return the first K2 entry element in the response.
+    # @return [REXML::Element, nil] The first entry element.
+    def entry
+      @doc.elements["entry"]
+    end
+
+    ##
+    # @!method object(filter_type = nil)
+    # Parse the first K2 entry element into an object.
+    # @param filter_type [String] Entry type must match the specified type.
+    # @return [IbmPowerHmc::AbstractRest, nil] The parsed object.
+    def object(filter_type = nil)
+      self.class.to_obj(entry, filter_type)
+    end
+
+    def self.to_obj(entry, filter_type = nil)
+      return if entry.nil?
+
+      content = entry.elements["content[@type]"]
+      return if content.nil?
+
+      type = content.attributes["type"].split("=").last
+      return unless filter_type.nil? || filter_type.to_s == type
+
+      Module.const_get("IbmPowerHmc::#{type}").new(entry)
+    end
+  end
+
+  ##
+  # Parser for HMC K2 feeds.
+  # A feed encapsulates a list of entries like this:
+  # <feed>
+  #   <entry>
+  #     <!-- entry #1 -->
+  #   </entry>
+  #   <entry>
+  #     <!-- entry #2 -->
+  #   </entry>
+  #   ...
+  # </feed>
+  class FeedParser < Parser
+    def entries
+      objs = []
+      @doc.each_element("feed/entry") do |entry|
+        objs << yield(entry)
+      end
+      objs
+    end
+
+    ##
+    # @!method objects(filter_type = nil)
+    # Parse feed entries into objects.
+    # @param filter_type [String] Filter entries based on content type.
+    # @return [Array<IbmPowerHmc::AbstractRest>] The list of objects.
+    def objects(filter_type = nil)
+      entries do |entry|
+        self.class.to_obj(entry, filter_type)
+      end.compact
+    end
+  end
+
+  private_constant :Parser
+  private_constant :FeedParser
+
+  ##
+  # HMC generic K2 XML entry.
+  # Encapsulate data for a single object.
+  # The XML looks like this:
+  # <entry>
+  #   <id>uuid</id>
+  #   <published>timestamp</published>
+  #   <etag:etag>ETag</etag:etag>
+  #   <content type="type">
+  #     <!-- actual content here -->
+  #   </content>
+  # </entry>
+  #
+  # @abstract
+  # @attr_reader [String] uuid The UUID of the object contained in the entry.
+  # @attr_reader [URI::HTTPS] href The URL of the object itself.
+  # @attr_reader [Time] published The time at which the entry was published.
+  # @attr_reader [String] etag The entity tag of the entry.
+  # @attr_reader [String] content_type The content type of the object contained in the entry.
+  # @attr_reader [REXML::Document] xml The XML document representing this object.
+  class AbstractRest
+    ATTRS = {}.freeze
+    attr_reader :uuid, :href, :published, :etag, :content_type, :xml
+
+    def initialize(doc)
+      @uuid = doc.elements["id"]&.text
+      link = doc.elements["link[@rel='SELF']"]
+      @href = URI(link.attributes["href"]) unless link.nil?
+      @published = Time.xmlschema(doc.elements["published"]&.text)
+      @etag = doc.elements["etag:etag"]&.text&.strip
+      content = doc.elements["content"]
+      @content_type = content.attributes["type"]
+      @xml = content.elements.first
+      define_attrs(self.class::ATTRS)
+    end
+
+    ##
+    # @!method define_attr(varname, xpath)
+    # Define an instance variable using the text of an XML element as value.
+    # @param varname [String] The name of the instance variable.
+    # @param xpath [String] The XPath of the XML element containing the text.
+    def define_attr(varname, xpath)
+      value = singleton(xpath)
+      self.class.__send__(:attr_reader, varname)
+      instance_variable_set("@#{varname}", value)
+    end
+
+    ##
+    # @!method define_attrs(hash)
+    # Define instance variables using the texts of XML elements as values.
+    # @param hash [Hash] The name of the instance variables and the XPaths
+    #   of the XML elements containing the values.
+    def define_attrs(hash)
+      hash.each do |key, value|
+        define_attr(key, value)
+      end
+    end
+
+    ##
+    # @!method singleton(xpath, attr = nil)
+    # Get the text (or the value of a specified attribute) of an XML element.
+    # @param xpath [String] The XPath of the XML element.
+    # @param attr [String] The name of the attribute.
+    # @return [String, nil] The text or attribute value of the XML element or nil.
+    # @example lpar.singleton("PartitionProcessorConfiguration/*/MaximumVirtualProcessors").to_i
+    def singleton(xpath, attr = nil)
+      elem = xml.elements[xpath]
+      return if elem.nil?
+
+      attr.nil? ? elem.text&.strip : elem.attributes[attr]
+    end
+
+    def extract_uuid_from_href(href)
+      URI(href).path.split('/').last
+    end
+  end
+
+  # HMC information
+  class ManagementConsole < AbstractRest
+    ATTRS = {
+      :name => "ManagementConsoleName",
+      :build_level => "VersionInfo/BuildLevel",
+      :version => "BaseVersion"
+    }.freeze
+
+    def managed_systems_uuids
+      xml.get_elements("ManagedSystems/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+  end
+
+  # Managed System information
+  class ManagedSystem < AbstractRest
+    ATTRS = {
+      :name => "SystemName",
+      :state => "State",
+      :hostname => "Hostname",
+      :ipaddr => "PrimaryIPAddress",
+      :fwversion => "SystemFirmware",
+      :memory => "AssociatedSystemMemoryConfiguration/InstalledSystemMemory",
+      :avail_mem => "AssociatedSystemMemoryConfiguration/CurrentAvailableSystemMemory",
+      :cpus => "AssociatedSystemProcessorConfiguration/InstalledSystemProcessorUnits",
+      :avail_cpus => "AssociatedSystemProcessorConfiguration/CurrentAvailableSystemProcessorUnits",
+      :mtype => "MachineTypeModelAndSerialNumber/MachineType",
+      :model => "MachineTypeModelAndSerialNumber/Model",
+      :serial => "MachineTypeModelAndSerialNumber/SerialNumber"
+    }.freeze
+
+    def lpars_uuids
+      xml.get_elements("AssociatedLogicalPartitions/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+
+    def vioses_uuids
+      xml.get_elements("AssociatedVirtualIOServers/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end.compact
+    end
+  end
+
+  # Common class for LPAR and VIOS
+  class BasePartition < AbstractRest
+    ATTRS = {
+      :name => "PartitionName",
+      :id => "PartitionID",
+      :state => "PartitionState",
+      :type => "PartitionType",
+      :memory => "PartitionMemoryConfiguration/CurrentMemory",
+      :dedicated => "PartitionProcessorConfiguration/HasDedicatedProcessors",
+      :rmc_state => "ResourceMonitoringControlState",
+      :rmc_ipaddr => "ResourceMonitoringIPAddress",
+      :os => "OperatingSystemVersion",
+      :ref_code => "ReferenceCode"
+    }.freeze
+
+    def sys_uuid
+      sys_href = singleton("AssociatedManagedSystem", "href")
+      extract_uuid_from_href(sys_href)
+    end
+
+    def net_adap_uuids
+      xml.get_elements("ClientNetworkAdapters/link").map do |link|
+        extract_uuid_from_href(link.attributes["href"])
+      end
+    end
+
+    def name=(name)
+      xml.elements[ATTRS[:name]].text = name
+      @name = name
+    end
+  end
+
+  # Logical Partition information
+  class LogicalPartition < BasePartition
+  end
+
+  # VIOS information
+  class VirtualIOServer < BasePartition
+  end
+
+  # Virtual Switch information
+  class VirtualSwitch < AbstractRest
+    ATTRS = {
+      :id   => "SwitchID",
+      :mode => "SwitchMode",
+      :name => "SwitchName"
+    }.freeze
+
+    def sys_uuid
+      href.path.split('/')[-3]
+    end
+  end
+
+  # HMC Event
+  class Event < AbstractRest
+    ATTRS = {
+      :id     => "EventID",
+      :type   => "EventType",
+      :data   => "EventData",
+      :detail => "EventDetail"
+    }.freeze
+  end
+
+  # Network adapter information
+  class ClientNetworkAdapter < AbstractRest
+    ATTRS = {
+      :macaddr      => "MACAddress",
+      :vswitch_id   => "VirtualSwitchID",
+      :vlan_id      => "PortVLANID"
+    }.freeze
+  end
+
+  # Error response from HMC
+  class HttpErrorResponse < AbstractRest
+    ATTRS = {
+      :status  => "HTTPStatus",
+      :uri     => "RequestURI",
+      :reason  => "ReasonCode",
+      :message => "Message"
+    }.freeze
+  end
+
+  # Job Response
+  class JobResponse < AbstractRest
+    ATTRS = {
+      :id      => "JobID",
+      :status  => "Status",
+      :message => "ResponseException/Message"
+    }.freeze
+
+    def results
+      results = {}
+      xml.each_element("Results/JobParameter") do |jobparam|
+        name = jobparam.elements["ParameterName"]&.text&.strip
+        value = jobparam.elements["ParameterValue"]&.text&.strip
+        results[name] = value unless name.nil?
+      end
+      results
+    end
+  end
+end

data/lib/ibm_power_hmc/pcm.rb

@@ -5,26 +5,62 @@ require 'uri'
 
 module IbmPowerHmc
   class Connection
+    def pcm_preferences
+      method_url = "/rest/api/pcm/preferences"
+
+      response = request(:get, method_url)
+      REXML::Document.new(response.body)
+    end
+
+    ##
+    # @!method phyp_metrics(sys_uuid:, start_ts: nil, end_ts: nil, short_term: false)
+    # Retrieve PowerVM metrics for a given managed system.
+    # @param sys_uuid [String] The managed system UUID.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
+    # @param short_term [Boolean] Retrieve short term monitor metrics (default to long term).
+    # @return [Array<Hash>] The PowerVM metrics for the managed system.
+    def phyp_metrics(sys_uuid:, start_ts: nil, end_ts: nil, short_term: false)
+      type = short_term ? "ShortTermMonitor" : "LongTermMonitor"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/RawMetrics/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
+
+      response = request(:get, method_url)
+      FeedParser.new(response.body).entries do |entry|
+        link = entry.elements["link"]
+        next if link.nil?
+
+        href = link.attributes["href"]
+        next if href.nil?
+
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
     ##
-    # @!method managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil)
+    # @!method managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
     # Retrieve metrics for a managed system.
     # @param sys_uuid [String] The managed system UUID.
-    # @param start_ts [String] Start timestamp.
-    # @param end_ts [String] End timestamp.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
     # @param no_samples [Integer] Number of samples.
-    # @return [Array<Hash>] The processed metrics for the managed system.
-    def managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil)
-      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/ProcessedMetrics"
-      query = []
-      query << "StartTS=#{start_ts}" unless start_ts.nil?
-      query << "EndTS=#{end_ts}" unless end_ts.nil?
-      query << "NoOfSamples=#{no_samples}" unless no_samples.nil?
-      method_url += "?" + query.compact.join('&') unless query.empty?
+    # @param aggregated [Boolean] Retrieve aggregated metrics (default to Processed).
+    # @return [Array<Hash>] The metrics for the managed system.
+    def managed_system_metrics(sys_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+      type = aggregated ? "AggregatedMetrics" : "ProcessedMetrics"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      query["NoOfSamples"] = no_samples unless no_samples.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
 
       response = request(:get, method_url)
-      doc = REXML::Document.new(response.body)
-      metrics = []
-      doc.each_element("feed/entry") do |entry|
+      FeedParser.new(response.body).entries do |entry|
         category = entry.elements["category"]
         next if category.nil?
 
@@ -37,19 +73,50 @@ module IbmPowerHmc
         href = link.attributes["href"]
         next if href.nil?
 
-        # Validate URI
-        begin
-          href = URI(href)
-        rescue
-          next
-        end
-        # Remove https://hostname:port prefix.
-        href.scheme = href.host = href.port = nil
-
-        response = request(:get, href.to_s)
-        metrics << JSON.parse(response.body)
-      end
-      metrics
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
+    ##
+    # @!method lpar_metrics(sys_uuid:, lpar_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+    # Retrieve metrics for a logical partition.
+    # @param sys_uuid [String] The managed system UUID.
+    # @param lpar_uuid [String] The logical partition UUID.
+    # @param start_ts [Time] Start timestamp.
+    # @param end_ts [Time] End timestamp.
+    # @param no_samples [Integer] Number of samples.
+    # @param aggregated [Boolean] Retrieve aggregated metrics (default to Processed).
+    # @return [Array<Hash>] The metrics for the logical partition.
+    def lpar_metrics(sys_uuid:, lpar_uuid:, start_ts: nil, end_ts: nil, no_samples: nil, aggregated: false)
+      type = aggregated ? "AggregatedMetrics" : "ProcessedMetrics"
+      method_url = "/rest/api/pcm/ManagedSystem/#{sys_uuid}/LogicalPartition/#{lpar_uuid}/#{type}"
+      query = {}
+      query["StartTS"] = self.class.format_time(start_ts) unless start_ts.nil?
+      query["EndTS"] = self.class.format_time(end_ts) unless end_ts.nil?
+      query["NoOfSamples"] = no_samples unless no_samples.nil?
+      method_url += "?" + query.map { |h| h.join("=") }.join("&") unless query.empty?
+
+      response = request(:get, method_url)
+      FeedParser(response.body).entries do |entry|
+        link = entry.elements["link"]
+        next if link.nil?
+
+        href = link.attributes["href"]
+        next if href.nil?
+
+        response = request(:get, href)
+        JSON.parse(response.body)
+      end.compact
+    end
+
+    ##
+    # @!method format_time(time)
+    # Convert ruby time to HMC time format.
+    # @param time [Time] The ruby time to convert.
+    # @return [String] The time in HMC format.
+    def self.format_time(time)
+      time.utc.xmlschema
     end
   end
 end

data/lib/ibm_power_hmc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IbmPowerHmc
-  VERSION = "0.1.1"
+  VERSION = "0.4.0"
 end

data/lib/ibm_power_hmc.rb

@@ -7,7 +7,8 @@ require "ibm_power_hmc/version"
 
 # Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  require_relative "./ibm_power_hmc/objects.rb"
-  require_relative "./ibm_power_hmc/job.rb"
-  require_relative "./ibm_power_hmc/connection.rb"
+  require_relative "./ibm_power_hmc/parser"
+  require_relative "./ibm_power_hmc/job"
+  require_relative "./ibm_power_hmc/connection"
+  require_relative "./ibm_power_hmc/pcm"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ibm_power_hmc
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.4.0
 platform: ruby
 authors:
 - IBM Power
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-28 00:00:00.000000000 Z
+date: 2021-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -35,7 +35,6 @@ files:
 - ".rubocop_local.yml"
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - LICENSE
 - README.md
 - Rakefile
@@ -45,7 +44,7 @@ files:
 - lib/ibm_power_hmc.rb
 - lib/ibm_power_hmc/connection.rb
 - lib/ibm_power_hmc/job.rb
-- lib/ibm_power_hmc/objects.rb
+- lib/ibm_power_hmc/parser.rb
 - lib/ibm_power_hmc/pcm.rb
 - lib/ibm_power_hmc/version.rb
 homepage: http://github.com/IBM/ibm_power_hmc_sdk_ruby
@@ -71,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: IBM Power HMC Ruby gem.

data/Gemfile.lock

@@ -1,37 +0,0 @@
-PATH
-  remote: .
-  specs:
-    ibm_power_hmc (0.1.0)
-      rest-client (~> 2.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    domain_name (0.5.20190701)
-      unf (>= 0.0.5, < 1.0.0)
-    http-accept (1.7.0)
-    http-cookie (1.0.4)
-      domain_name (~> 0.5)
-    mime-types (3.3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2021.0704)
-    netrc (0.11.0)
-    rake (12.3.3)
-    rest-client (2.1.0)
-      http-accept (>= 1.7.0, < 2.0)
-      http-cookie (>= 1.0.2, < 2.0)
-      mime-types (>= 1.16, < 4.0)
-      netrc (~> 0.8)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.7.7)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  ibm_power_hmc!
-  rake (~> 12.0)
-
-BUNDLED WITH
-   2.1.4

data/lib/ibm_power_hmc/objects.rb

@@ -1,148 +0,0 @@
-# frozen_string_literal: true
-
-require 'uri'
-
-# Module for IBM HMC Rest API Client
-module IbmPowerHmc
-  # HMC generic object
-  class HmcObject
-    attr_reader :uuid
-
-    def initialize(doc)
-      @uuid = doc.elements["id"].text
-    end
-
-    def get_value(doc, xpath, varname)
-      value = doc.elements[xpath]
-      value = value.text unless value.nil?
-      value = value.strip unless value.nil?
-      self.class.__send__(:attr_reader, varname)
-      instance_variable_set("@#{varname}", value)
-    end
-
-    def get_values(doc, hash)
-      hash.each do |key, value|
-        get_value(doc, key, value)
-      end
-    end
-  end
-
-  # HMC information
-  class ManagementConsole < HmcObject
-    XMLMAP = {
-      "ManagementConsoleName" => "name",
-      "VersionInfo/BuildLevel" => "build_level",
-      "BaseVersion" => "version"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/ManagementConsole:ManagementConsole"]
-      get_values(info, XMLMAP)
-    end
-  end
-
-  # Managed System information
-  class ManagedSystem < HmcObject
-    XMLMAP = {
-      "SystemName" => "name",
-      "State" => "state",
-      "Hostname" => "hostname",
-      "PrimaryIPAddress" => "ipaddr",
-      "AssociatedSystemMemoryConfiguration/InstalledSystemMemory" => "memory",
-      "AssociatedSystemMemoryConfiguration/CurrentAvailableSystemMemory" => "avail_mem",
-      "AssociatedSystemProcessorConfiguration/InstalledSystemProcessorUnits" => "cpus",
-      "AssociatedSystemProcessorConfiguration/CurrentAvailableSystemProcessorUnits" => "avail_cpus",
-      "MachineTypeModelAndSerialNumber/MachineType" => "mtype",
-      "MachineTypeModelAndSerialNumber/Model" => "model",
-      "MachineTypeModelAndSerialNumber/SerialNumber" => "serial",
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/ManagedSystem:ManagedSystem"]
-      get_values(info, XMLMAP)
-    end
-  end
-
-  # Logical Partition information
-  class LogicalPartition < HmcObject
-    attr_reader :sys_uuid
-
-    XMLMAP = {
-      "PartitionName" => "name",
-      "PartitionID" => "id",
-      "PartitionState" => "state",
-      "PartitionType" => "type",
-      "PartitionMemoryConfiguration/CurrentMemory" => "memory",
-      "PartitionProcessorConfiguration/HasDedicatedProcessors" => "dedicated",
-      "ResourceMonitoringControlState" => "rmc_state",
-      "ResourceMonitoringIPAddress" => "rmc_ipaddr"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/LogicalPartition:LogicalPartition"]
-      sys_href = info.elements["AssociatedManagedSystem"].attributes["href"]
-      @sys_uuid = URI(sys_href).path.split('/').last
-      get_values(info, XMLMAP)
-    end
-  end
-
-  # VIOS information
-  class VirtualIOServer < HmcObject
-    attr_reader :sys_uuid
-
-    XMLMAP = {
-      "PartitionName" => "name",
-      "PartitionID" => "id",
-      "PartitionState" => "state",
-      "PartitionType" => "type",
-      "PartitionMemoryConfiguration/CurrentMemory" => "memory",
-      "PartitionProcessorConfiguration/HasDedicatedProcessors" => "dedicated"
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/VirtualIOServer:VirtualIOServer"]
-      sys_href = info.elements["AssociatedManagedSystem"].attributes["href"]
-      @sys_uuid = URI(sys_href).path.split('/').last
-      get_values(info, XMLMAP)
-    end
-  end
-
-  # HMC Event
-  class Event < HmcObject
-    attr_reader :published
-
-    XMLMAP = {
-      "EventID" => "id",
-      "EventType" => "type",
-      "EventData" => "data",
-      "EventDetail" => "detail",
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      @published = doc.elements["published"].text
-      info = doc.elements["content/Event:Event"]
-      get_values(info, XMLMAP)
-    end
-  end
-
-  # Error response from HMC
-  class HttpErrorResponse < HmcObject
-    XMLMAP = {
-      "HTTPStatus" => "status",
-      "RequestURI" => "uri",
-      "ReasonCode" => "reason",
-      "Message" => "message",
-    }.freeze
-
-    def initialize(doc)
-      super(doc)
-      info = doc.elements["content/HttpErrorResponse:HttpErrorResponse"]
-      get_values(info, XMLMAP)
-    end
-  end
-end