ibm_power_hmc 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e42aa4d6eaa8915b8c37ce96aab995801533b81d8fa70b1e351bc550cc6eaa02
-  data.tar.gz: 6022fb088c67eeb0c20e8435c20567ef62fb34e365419cfa20f6fb9bc1e769f5
+  metadata.gz: c19305b95374164ab2a6e6168a4a292ea0666065cbcbe8f05dea30483b622055
+  data.tar.gz: be50d67e7c462cc17f20be3f643c6029e4f2ba7d43f872f1821bbe428f0e11fe
 SHA512:
-  metadata.gz: 7ca0280aaeff1a1a0ce0cf5c53c40b6f0ddfc94725536e53d19031b1b107de4c8b44919580eaf1716e60f302bf339363508597b9188634412511bcc7869e4f83
-  data.tar.gz: b0251d621a729e2b7d97c7655709fd68bd1e796466967f2021924ab7658a12c2dc13c34dfe71597f96f6ed2114e24c405362232c4dab2e88b653afbe2b7d679a
+  metadata.gz: 1191f64dd2f5c550d25a372b4a0502dd4e7b5a8e779a2dacdf079a22f3a8b8092af6e4ddff514b0e06dddf8239985033034959e385f951f2f535f092866cbd12
+  data.tar.gz: d6af992547d99624f59e6eb5ec3404768c91d1b9c9809e9542966fee15b4a350e8b8803e6fd25a597c48699b630171b7cae8327108f0ec6616e2329c5441bf1c

data/.rubocop_local.yml

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

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,14 @@ 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 +197,26 @@ module IbmPowerHmc
       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
+
     ##
     # @!method poweron_lpar(lpar_uuid, params = {}, sync = true)
     # Power on a logical partition.
@@ -219,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"
@@ -249,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"
@@ -279,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"
@@ -325,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.
@@ -418,6 +451,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 +466,34 @@ 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_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/parser.rb

@@ -4,16 +4,26 @@ require 'time'
 require 'uri'
 
 module IbmPowerHmc
-  # Parser for HMC feeds and entries.
+  ##
+  # 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
@@ -21,19 +31,28 @@ module IbmPowerHmc
     def self.to_obj(entry, filter_type = nil)
       return if entry.nil?
 
-      content = entry.elements["content"]
+      content = entry.elements["content[@type]"]
       return if content.nil?
 
-      type = content.attributes["type"]
-      return if type.nil?
-
-      type = type.split("=").last
+      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 = []
@@ -43,6 +62,11 @@ module IbmPowerHmc
       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)
@@ -53,34 +77,76 @@ module IbmPowerHmc
   private_constant :Parser
   private_constant :FeedParser
 
-  # HMC generic XML entry
+  ##
+  # 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, :published, :etag, :xml
+    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
-      type = self.class.name.split("::").last
-      @xml = doc.elements["content/#{type}:#{type}"]
+      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 = text_element(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
 
-    def text_element(xpath)
-      xml.elements[xpath]&.text&.strip
+    ##
+    # @!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)
@@ -136,7 +202,6 @@ module IbmPowerHmc
   # Common class for LPAR and VIOS
   class BasePartition < AbstractRest
     ATTRS = {
-      :os => "OperatingSystemVersion",
       :name => "PartitionName",
       :id => "PartitionID",
       :state => "PartitionState",
@@ -145,13 +210,25 @@ module IbmPowerHmc
       :dedicated => "PartitionProcessorConfiguration/HasDedicatedProcessors",
       :rmc_state => "ResourceMonitoringControlState",
       :rmc_ipaddr => "ResourceMonitoringIPAddress",
+      :os => "OperatingSystemVersion",
       :ref_code => "ReferenceCode"
     }.freeze
 
     def sys_uuid
-      sys_href = xml.elements["AssociatedManagedSystem"].attributes["href"]
+      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
@@ -162,6 +239,19 @@ module IbmPowerHmc
   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 = {
@@ -172,6 +262,15 @@ module IbmPowerHmc
     }.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 = {
@@ -192,9 +291,9 @@ module IbmPowerHmc
 
     def results
       results = {}
-      xml.each_element("Results/JobParameter") do |result|
-        name = result.elements["ParameterName"]&.text&.strip
-        value = result.elements["ParameterValue"]&.text&.strip
+      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

data/lib/ibm_power_hmc/version.rb

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

data/lib/ibm_power_hmc.rb

@@ -7,8 +7,8 @@ require "ibm_power_hmc/version"
 
 # Module for IBM HMC Rest API Client
 module IbmPowerHmc
-  require_relative "./ibm_power_hmc/parser.rb"
-  require_relative "./ibm_power_hmc/job.rb"
-  require_relative "./ibm_power_hmc/connection.rb"
-  require_relative "./ibm_power_hmc/pcm.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.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - IBM Power
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-15 00:00:00.000000000 Z
+date: 2021-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.1'
 description: A Ruby gem for interacting with the IBM Hardware Management Console (HMC).
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -55,7 +55,7 @@ metadata:
   homepage_uri: http://github.com/IBM/ibm_power_hmc_sdk_ruby
   source_code_uri: http://github.com/IBM/ibm_power_hmc_sdk_ruby
   changelog_uri: http://github.com/IBM/ibm_power_hmc_sdk_ruby/blob/master/CHANGELOG.md
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,8 +70,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.1.4
+signing_key:
 specification_version: 4
 summary: IBM Power HMC Ruby gem.
 test_files: []