ibm_power_hmc 0.8.8 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ac3d35b91cddabaaf7767cbdbbb91a975c68ecb2ff857db6c888af131f9d281
-  data.tar.gz: cfd224e53a20e2dd76672daa631f008fff3019ad363ecf270fe1c8b802bd6145
+  metadata.gz: 669594ada9babea18977e0e3870c6ea0e27305cd74660dbe2d3bbc70551ed4b4
+  data.tar.gz: 76304c4b431924825adfc32dc14ff31c0951f0c6aae294010331c82a54ca384d
 SHA512:
-  metadata.gz: b48e94a5e7208e40de8e488a6456e89c2e63151976cafa36b2e74d25b0f6d51bd40afcf0356c68079e9478db940ceb84b2350f3ee13399aad83e467dcd8c0e03
-  data.tar.gz: 53a6000d74d4dfef6dfe3d29aa949a7185108f281214d94020ac514d2843161469cf5f14024c2f2662be2b814e30ff33ab240a808052a7fae842181e8cfc059f
+  metadata.gz: 620c2c717f08248e38b1fec9ddec4dc4bea48537ba59a2ad5071cb16b04c93a35fdd05be492eb62de0c67b170881c3c0e7fe57bedfd7c91e92069ac51961bc06
+  data.tar.gz: c79795ef430594a26709e8eb71f96ffca4689cf1e362ff7b8531e15e36d9e2fd73c396387a11634c6eea7f29d2bbc82267f952053a3fe40a0a909f36107a3451

data/.rubocop_local.yml

@@ -9,3 +9,5 @@ Style/OptionalBooleanParameter:
   Enabled: false
 Style/StringConcatenation:
   Enabled: false
+Style/RescueModifier:
+  Enabled: false

data/lib/ibm_power_hmc/connection.rb

@@ -157,7 +157,7 @@ module IbmPowerHmc
     # @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 }
+      modify_object_attributes(method_url, {:name => new_name})
     end
 
     ##
@@ -388,9 +388,10 @@ module IbmPowerHmc
     ##
     # @!method templates_summary
     # Retrieve the list of partition template summaries.
+    # @param draft [Boolean] Retrieve draft templates as well
     # @return [Array<IbmPowerHmc::PartitionTemplateSummary>] The list of partition template summaries.
-    def templates_summary
-      method_url = "/rest/api/templates/PartitionTemplate"
+    def templates_summary(draft = false)
+      method_url = "/rest/api/templates/PartitionTemplate#{'?draft=false' unless draft}"
       response = request(:get, method_url)
       FeedParser.new(response.body).objects(:PartitionTemplateSummary)
     end
@@ -398,9 +399,10 @@ module IbmPowerHmc
     ##
     # @!method templates
     # Retrieve the list of partition templates.
+    # @param draft [Boolean] Retrieve draft templates as well
     # @return [Array<IbmPowerHmc::PartitionTemplate>] The list of partition templates.
-    def templates
-      method_url = "/rest/api/templates/PartitionTemplate?detail=full"
+    def templates(draft = false)
+      method_url = "/rest/api/templates/PartitionTemplate?detail=full#{'&draft=false' unless draft}"
       response = request(:get, method_url)
       FeedParser.new(response.body).objects(:PartitionTemplate)
     end
@@ -439,6 +441,94 @@ module IbmPowerHmc
       job
     end
 
+    ##
+    # @!method template_check(template_uuid, target_sys_uuid, sync = true)
+    # Start Template Check job (first of three steps to deploy an LPAR from a Template).
+    # @param template_uuid [String] The UUID of the Template to deploy an LPAR from.
+    # @param target_sys_uuid [String] The UUID of the Managed System to deploy the LPAR on.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def template_check(template_uuid, target_sys_uuid, 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/#{template_uuid}/do/check"
+      params = {
+        "TargetUuid"              => target_sys_uuid,
+        "K_X_API_SESSION_MEMENTO" => @api_session_token
+      }
+      job = HmcJob.new(self, method_url, "Check", "PartitionTemplate", params)
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method template_transform(draft_template_uuid, target_sys_uuid, sync = true)
+    # Start Template Transform job (second of three steps to deploy an LPAR from a Template).
+    # @param draft_template_uuid [String] The UUID of the Draft Template created by the Template Check job.
+    # @param target_sys_uuid [String] The UUID of the Managed System to deploy the LPAR on.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def template_transform(draft_template_uuid, target_sys_uuid, 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/#{draft_template_uuid}/do/transform"
+      params = {
+        "TargetUuid"              => target_sys_uuid,
+        "K_X_API_SESSION_MEMENTO" => @api_session_token
+      }
+      job = HmcJob.new(self, method_url, "Transform", "PartitionTemplate", params)
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method template_deploy(draft_template_uuid, target_sys_uuid, sync = true)
+    # Start Template Deploy job (last of three steps to deploy an LPAR from a Template).
+    # @param draft_template_uuid [String] The UUID of the Draft Template created by the Template Check job.
+    # @param target_sys_uuid [String] The UUID of the Managed System to deploy the LPAR on.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def template_deploy(draft_template_uuid, target_sys_uuid, 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/#{draft_template_uuid}/do/deploy"
+      params = {
+        "TargetUuid"              => target_sys_uuid,
+        "TemplateUuid"            => draft_template_uuid,
+        "K_X_API_SESSION_MEMENTO" => @api_session_token
+      }
+      job = HmcJob.new(self, method_url, "Deploy", "PartitionTemplate", params)
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method template_provision(template_uuid, target_sys_uuid, changes)
+    # Deploy Logical Partition from a Template (performs Check, Transform and Deploy steps in a single method).
+    # @param template_uuid [String] The UUID of the Template to deploy an LPAR from.
+    # @param target_sys_uuid [String] The UUID of the Managed System to deploy the LPAR on.
+    # @param changes [Hash] Modifications to apply to the Template before deploying Logical Partition.
+    # @return [String] The UUID of the deployed Logical Partition.
+    def template_provision(template_uuid, target_sys_uuid, changes)
+      # Need to include session token in payload so make sure we are logged in
+      logon if @api_session_token.nil?
+      draft_uuid = template_check(template_uuid, target_sys_uuid).results["TEMPLATE_UUID"]
+      template_transform(draft_uuid, target_sys_uuid)
+      template_modify(draft_uuid, changes)
+      template_deploy(draft_uuid, target_sys_uuid).results["PartitionUuid"]
+    end
+
+    ##
+    # @!method template(template_uuid, changes)
+    # modify_object_attributes wrapper for templates.
+    # @param template_uuid [String] UUID of the partition template to modify.
+    # @param changes [Hash] Hash of changes to make.
+    # @return [IbmPowerHmc::PartitionTemplate] The partition template.
+    def template_modify(template_uuid, changes)
+      method_url = "/rest/api/templates/PartitionTemplate/#{template_uuid}"
+      modify_object_attributes(method_url, changes)
+    end
+
     ##
     # @!method poweron_lpar(lpar_uuid, params = {}, sync = true)
     # Power on a logical partition.
@@ -701,6 +791,22 @@ module IbmPowerHmc
       end
     end
 
+    # @!method modify_object_attributes(method_url, headers = {}, attempts = 5)
+    # Modify an object at a specified URI.
+    # @param method_url [String] The URL of the object to modify.
+    # @param changes [Hash] Hash of changes to make. Key is the attribute modify/create (as defined in the AbstractNonRest subclass). A value of nil removes the attribute.
+    # @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_attributes(method_url, changes, headers = {}, attempts = 5)
+      modify_object(method_url, headers, attempts) do |obj|
+        changes.each do |key, value|
+          obj.send("#{key}=", value)
+        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.

data/lib/ibm_power_hmc/job.rb

@@ -5,6 +5,16 @@ module IbmPowerHmc
   # HMC Job for long running operations.
   class HmcJob
     class JobNotStarted < StandardError; end
+    class JobFailed < StandardError
+      def initialize(job)
+        super
+        @job = job
+      end
+
+      def to_s
+        "id=\"#{@job.id}\" operation=\"#{@job.group}/#{@job.operation}\" status=\"#{@job.status}\" message=\"#{@job.message}\" exception_text=\"#{@job.results['ExceptionText']}\""
+      end
+    end
 
     ##
     # @!method initialize(conn, method_url, operation, group, params = {})
@@ -52,7 +62,7 @@ module IbmPowerHmc
     end
 
     # @return [Hash] The job results returned by the HMC.
-    attr_reader :results
+    attr_reader :results, :last_status
 
     ##
     # @!method status
@@ -65,9 +75,9 @@ module IbmPowerHmc
         :content_type => "application/vnd.ibm.powervm.web+xml; type=JobRequest"
       }
       response = @conn.request(:get, @href, headers)
-      jobresp = Parser.new(response.body).object(:JobResponse)
-      @results = jobresp.results
-      jobresp.status
+      @last_status = Parser.new(response.body).object(:JobResponse)
+      @results = @last_status.results
+      @last_status.status
     end
 
     ##
@@ -99,6 +109,7 @@ module IbmPowerHmc
     def run(timeout = 120, poll_interval = 0)
       start
       wait(timeout, poll_interval)
+      raise JobFailed.new(@last_status) unless @last_status.status.eql?("COMPLETED_OK")
     ensure
       delete if defined?(@href)
     end

data/lib/ibm_power_hmc/parser.rb

@@ -34,7 +34,7 @@ module IbmPowerHmc
       content = entry.elements["content[@type]"]
       return if content.nil?
 
-      type = content.attributes["type"].split("=").last
+      type = content.attributes["type"].split("=")[1] || filter_type.to_s
       return unless filter_type.nil? || filter_type.to_s == type
 
       Module.const_get("IbmPowerHmc::#{type}").new(entry)
@@ -95,10 +95,35 @@ module IbmPowerHmc
     def define_attr(varname, xpath)
       value = singleton(xpath)
       self.class.__send__(:attr_reader, varname)
+      self.class.__send__(:define_method, "#{varname}=") do |v|
+        if v.nil?
+          xml.elements.delete(xpath)
+        else
+          create_element(xpath) if xml.elements[xpath].nil?
+          xml.elements[xpath].text = v
+        end
+        instance_variable_set("@#{varname}", v)
+      end
       instance_variable_set("@#{varname}", value)
     end
     private :define_attr
 
+    ##
+    # @!method create_element(xpath)
+    # Create a new XML element.
+    # @param xpath [String] The XPath of the XML element to create.
+    def create_element(xpath)
+      cur = xml
+      xpath.split("/").each do |el|
+        p = cur.elements[el]
+        if p.nil?
+          cur = cur.add_element(el)
+        else
+          cur = p
+        end
+      end
+    end
+
     ##
     # @!method singleton(xpath, attr = nil)
     # Get the text (or the value of a specified attribute) of an XML element.
@@ -135,7 +160,7 @@ module IbmPowerHmc
 
     def collection_of(name, type)
       objtype = Module.const_get("IbmPowerHmc::#{type}")
-      xml.get_elements("#{name}/#{type}").map do |elem|
+      xml.get_elements([name, type].compact.join("/")).map do |elem|
         objtype.new(elem)
       end
     rescue
@@ -327,13 +352,6 @@ module IbmPowerHmc
     def sriov_elp_uuids
       uuids_from_links("SRIOVEthernetLogicalPorts")
     end
-
-    # Setters
-
-    def name=(name)
-      xml.elements[ATTRS[:name]].text = name
-      @name = name
-    end
   end
 
   # Logical Partition information
@@ -430,6 +448,15 @@ module IbmPowerHmc
     }.freeze
   end
 
+  # SharedFileSystemFile information
+  class SharedFileSystemFile < VirtualSCSIStorage
+    ATTRS = {
+      :name => "SharedFileSystemFileName",
+      :path => "SharedFileSystemFilePath",
+      :udid => "UniqueDeviceID"
+    }.freeze
+  end
+
   # Virtual Media Repository information
   class VirtualMediaRepository < AbstractNonRest
     ATTRS = {
@@ -573,11 +600,12 @@ module IbmPowerHmc
 
     def storage
       # Possible storage types are:
-      # LogicalUnit, PhysicalVolume, VirtualDisk, VirtualOpticalMedia
+      # LogicalUnit, PhysicalVolume, VirtualDisk, VirtualOpticalMedia,
+      # SharedFileSystemFile
       elem = xml.elements["Storage/*[1]"]
       begin
         Module.const_get("IbmPowerHmc::#{elem.name}").new(elem) unless elem.nil?
-      rescue
+      rescue NameError
         nil
       end
     end
@@ -585,9 +613,14 @@ module IbmPowerHmc
     def device
       # Possible backing device types are:
       # LogicalVolumeVirtualTargetDevice, PhysicalVolumeVirtualTargetDevice,
-      # SharedStoragePoolLogicalUnitVirtualTargetDevice, VirtualOpticalTargetDevice
+      # SharedStoragePoolLogicalUnitVirtualTargetDevice, VirtualOpticalTargetDevice,
+      # SharedFileSystemFileVirtualTargetDevice
       elem = xml.elements["TargetDevice/*[1]"]
-      Module.const_get("IbmPowerHmc::#{elem.name}").new(elem) unless elem.nil?
+      begin
+        Module.const_get("IbmPowerHmc::#{elem.name}").new(elem) unless elem.nil?
+      rescue NameError
+        nil
+      end
     end
   end
 
@@ -653,6 +686,9 @@ module IbmPowerHmc
     end
   end
 
+  # SharedFileSystemFile backing device information
+  class SharedFileSystemFileVirtualTargetDevice < VirtualTargetDevice; end
+
   # VFC mapping information
   class VirtualFibreChannelMapping < AbstractNonRest
     def lpar_uuid
@@ -864,6 +900,8 @@ module IbmPowerHmc
     ATTRS = {
       :name         => "partitionTemplateName",
       :description  => "description",
+      :lpar_name    => "logicalPartitionConfig/partitionName",
+      :lpar_id      => "logicalPartitionConfig/partitionId",
       :os           => "logicalPartitionConfig/osVersion",
       :memory       => "logicalPartitionConfig/memoryConfiguration/currMemory",
       :dedicated    => "logicalPartitionConfig/processorConfiguration/hasDedicatedProcessors",
@@ -872,6 +910,87 @@ module IbmPowerHmc
       :proc_units   => "logicalPartitionConfig/processorConfiguration/sharedProcessorConfiguration/desiredProcessingUnits",
       :procs        => "logicalPartitionConfig/processorConfiguration/dedicatedProcessorConfiguration/desiredProcessors"
     }.freeze
+
+    def vscsi
+      REXML::XPath.match(xml, 'logicalPartitionConfig/virtualSCSIClientAdapters/VirtualSCSIClientAdapter').map do |adap|
+        {
+          :vios     => adap.elements['connectingPartitionName']&.text,
+          :physvol  => adap.elements['associatedPhysicalVolume/PhysicalVolume/name']&.text,
+        }
+      end
+    end
+
+    def vscsi=(list = [])
+      adaps = REXML::Element.new('virtualSCSIClientAdapters')
+      adaps.add_attribute('schemaVersion', 'V1_5_0')
+      list.each do |vlan|
+        adaps.add_element('VirtualSCSIClientAdapter', {'schemaVersion' => 'V1_5_0'}).tap do |v|
+          v.add_element('associatedLogicalUnits', {'schemaVersion' => 'V1_5_0'})
+          v.add_element('associatedPhysicalVolume', {'schemaVersion' => 'V1_5_0'}).tap do |e|
+            e.add_element('PhysicalVolume', {'schemaVersion' => 'V1_5_0'}).add_element('name').text = vlan[:physvol] if vlan[:physvol]
+          end
+          v.add_element('connectingPartitionName').text = vlan[:vios]
+          v.add_element('AssociatedTargetDevices', {'schemaVersion' => 'V1_5_0'})
+          v.add_element('associatedVirtualOpticalMedia', {'schemaVersion' => 'V1_5_0'})
+        end
+      end
+      if xml.elements['logicalPartitionConfig/virtualSCSIClientAdapters']
+        xml.elements['logicalPartitionConfig/virtualSCSIClientAdapters'] = adaps
+      else
+        xml.elements['logicalPartitionConfig'].add_element(adaps)
+      end
+    end
+
+    def vfc
+      REXML::XPath.match(xml, 'logicalPartitionConfig/virtualFibreChannelClientAdapters/VirtualFibreChannelClientAdapter').map do |adap|
+        {
+          :vios => adap.elements['connectingPartitionName']&.text,
+          :port => adap.elements['portName']&.text
+        }
+      end
+    end
+
+    def vfc=(list = [])
+      adaps = REXML::Element.new('virtualFibreChannelClientAdapters')
+      adaps.add_attribute('schemaVersion', 'V1_5_0')
+      list.each do |vlan|
+        adaps.add_element('VirtualFibreChannelClientAdapter', {'schemaVersion' => 'V1_5_0'}).tap do |v|
+          v.add_element('connectingPartitionName').text = vlan[:vios]
+          v.add_element('portName').text                = vlan[:port]
+        end
+      end
+      if xml.elements['logicalPartitionConfig/virtualFibreChannelClientAdapters']
+        xml.elements['logicalPartitionConfig/virtualFibreChannelClientAdapters'] = adaps
+      else
+        xml.elements['logicalPartitionConfig'].add_element(adaps)
+      end
+    end
+
+    def vlans
+      REXML::XPath.match(xml, 'logicalPartitionConfig/clientNetworkAdapters/ClientNetworkAdapter/clientVirtualNetworks/ClientVirtualNetwork').map do |vlan|
+        {
+          :name    => vlan.elements['name']&.text,
+          :vlan_id => vlan.elements['vlanId']&.text,
+          :switch  => vlan.elements['associatedSwitchName']&.text
+        }
+      end
+    end
+
+    def vlans=(list = [])
+      adaps = REXML::Element.new('clientNetworkAdapters')
+      adaps.add_attribute('schemaVersion', 'V1_5_0')
+      list.each do |vlan|
+        adaps.add_element('ClientNetworkAdapter',  {'schemaVersion' => 'V1_5_0'}).
+              add_element('clientVirtualNetworks', {'schemaVersion' => 'V1_5_0'}).
+              add_element('ClientVirtualNetwork',  {'schemaVersion' => 'V1_5_0'}).
+              tap do |v|
+          v.add_element('name').text                 = vlan[:name]
+          v.add_element('vlanId').text               = vlan[:vlan_id]
+          v.add_element('associatedSwitchName').text = vlan[:switch]
+        end
+      end
+      xml.elements['logicalPartitionConfig/clientNetworkAdapters'] = adaps
+    end
   end
 
   # HMC Event
@@ -899,9 +1018,11 @@ module IbmPowerHmc
   # Job Response
   class JobResponse < AbstractRest
     ATTRS = {
-      :id      => "JobID",
-      :status  => "Status",
-      :message => "ResponseException/Message"
+      :id        => "JobID",
+      :status    => "Status",
+      :operation => "JobRequestInstance/RequestedOperation/OperationName",
+      :group     => "JobRequestInstance/RequestedOperation/GroupName",
+      :message   => "ResponseException/Message"
     }.freeze
 
     def results
@@ -914,4 +1035,31 @@ module IbmPowerHmc
       results
     end
   end
+
+  class ManagementConsolePcmPreference < AbstractRest
+    ATTRS = {
+      :max_ltm                     => "MaximumManagedSystemsForLongTermMonitor",
+      :max_compute_ltm             => "MaximumManagedSystemsForComputeLTM",
+      :max_aggregation             => "MaximumManagedSystemsForAggregation",
+      :max_stm                     => "MaximumManagedSystemsForShortTermMonitor",
+      :max_em                      => "MaximumManagedSystemsForEnergyMonitor",
+      :aggregated_storage_duration => "AggregatedMetricsStorageDuration"
+    }.freeze
+
+    def managed_system_preferences
+      collection_of(nil, "ManagedSystemPcmPreference")
+    end
+  end
+
+  class ManagedSystemPcmPreference < AbstractNonRest
+    ATTRS = {
+      :id                 => "Metadata/Atom/AtomID",
+      :name               => "SystemName",
+      :long_term_monitor  => "LongTermMonitorEnabled",
+      :aggregation        => "AggregationEnabled",
+      :short_term_monitor => "ShortTermMonitorEnabled",
+      :compute_ltm        => "ComputeLTMEnabled",
+      :energy_monitor     => "EnergyMonitorEnabled"
+    }.freeze
+  end
 end

data/lib/ibm_power_hmc/pcm.rb

@@ -5,11 +5,24 @@ require 'uri'
 
 module IbmPowerHmc
   class Connection
+    ##
+    # @!method pcm_preferences
+    # Retrieve global Performance and Capacity Monitor preferences for the HMC.
+    # @return [Array<IbmPowerHmc::ManagementConsolePcmPreference>] The PCM preferences for the HMC.
     def pcm_preferences
       method_url = "/rest/api/pcm/preferences"
 
       response = request(:get, method_url)
-      REXML::Document.new(response.body)
+      FeedParser.new(response.body).objects(:ManagementConsolePcmPreference)
+    end
+
+    ##
+    # @!method managed_system_pcm_preferences
+    # Return Performance and Capacity Monitor preferences for a Managed System.
+    # @param sys_uuid [String] The managed system UUID.
+    # @return [IbmPowerHmc::ManagedSystemPcmPreference] The PCM preferences for the Managed System.
+    def managed_system_pcm_preferences(sys_uuid)
+      pcm_preferences.first.managed_system_preferences.find { |p| p.id.eql?(sys_uuid) }
     end
 
     ##

data/lib/ibm_power_hmc/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ibm_power_hmc
 version: !ruby/object:Gem::Version
-  version: 0.8.8
+  version: 0.11.0
 platform: ruby
 authors:
 - IBM Power
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-07 00:00:00.000000000 Z
+date: 2022-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -84,7 +84,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.