ibm_power_hmc 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebd50ae53571c98987372d364410261fa5a5440cf23e009c9cf8219eb2e052de
-  data.tar.gz: 7514545bd7a9be7e958597b7fdebc161f9ea253b20550165a798765930b09eec
+  metadata.gz: 669594ada9babea18977e0e3870c6ea0e27305cd74660dbe2d3bbc70551ed4b4
+  data.tar.gz: 76304c4b431924825adfc32dc14ff31c0951f0c6aae294010331c82a54ca384d
 SHA512:
-  metadata.gz: 41c1fd98ca6750bad69416b3c29986c432c77d8168d72ae485a90a6199b53716dd214c70f74b4c5971e03845d359f847c15a3958a616debd097effcfc0a5567b
-  data.tar.gz: 44f761a7d986716fe2338bceee413785add2fbfdece042022fec02edadcf60d02ea9deb49bad75d0752ea05b64fbe37b36a554d15f7a6e52bb09c62966ab3e9b
+  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

@@ -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.
@@ -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
@@ -882,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",
@@ -890,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
@@ -917,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

data/lib/ibm_power_hmc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IbmPowerHmc
-  VERSION = "0.10.0"
+  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.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - IBM Power
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-05-20 00:00:00.000000000 Z
+date: 2022-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.3'
 description: A Ruby gem for interacting with the IBM Hardware Management Console (HMC).
-email: 
+email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -69,7 +69,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
@@ -84,8 +84,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: []