ibm_power_hmc 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a067e3697998766bac04fad91eafee2e1563a5203c9bdcd9570cccea7b8cf3d
-  data.tar.gz: 0152c5e104b2fe95acb8a232e448708c3e44fd59cf2754a743da35a2856cc3a8
+  metadata.gz: 49c35a3e54753bb8c31a1eafc7c6e98e0ad2a662d4d24c284e873ec3d30aa144
+  data.tar.gz: 8429c8a52729102cfcdd2294fc25a2a27dd3f01b0ba9f3f0e46ebbea931903ac
 SHA512:
-  metadata.gz: dc1d8e450a39902ea9aaee7765b2bd8c8850a9d7dc99abca96ee320287852d0d3fb7738fd4820edd3827c00030e66edaada481aab2de9e3850a9d8b32c98e2c1
-  data.tar.gz: 01c46f3e296b808afccfcf37e4a3f259b51b807fc051929965e4f2d5eba0cd3f4e14e0432819c9626b36647128d0fb59e9a1e1b0b6c740e839662308991f3079
+  metadata.gz: 7b0cdb3f5348b221cd5fd147e63d391719b06324a49eec554fd1820d90f8000fb4000e005d5e638e6445be0608f7ea30a3a1db1d1345ac1cbf32526fd428f01f
+  data.tar.gz: 06d590cf0b6f2d92fbdd685d511ebd499597a285a248807cbe2814e5d569ad237753c7b2196c03b40d9f4be25d08071f990dc3d9d3fad0b20e4f5a8ef7a64438

data/CHANGELOG.md

@@ -1,2 +1,85 @@
-= 0.1.0
+## v0.20.0
+* Add permissive option (`ignoreError=true`) for cluster APIs
+* Fix `modify_object` method when URI has a query part
+* Add `chcomgmt` method
+* Add `grow_lu` method
+* Add `shared_memory_pool` method
+* Improve schema definitions for CPU and memory
+* Add schema definition for shared memory pool
+## v0.19.0
+* Major code refactoring
+* Add `serviceable_events` method
+* Add schema definitions for serviceable events
+* Add `lpar_delete` method
+* Add HttpNotFound exception for 404 errors
+## v0.18.0
+* Remove deprecated `rename_lpar` method (replaced by `modify_object`)
+* Add schema definition for SEA
+* Add schema definition for trunk adapters
+* Add schema definition for IPInterface
+## v0.17.0
+* Add extended group attributes to lpars and vioses methods
+* Add `lpars_quick` and `vioses_quick` methods
+## v0.16.0
+* Add timeout parameter for `IbmPowerHmc::Connection`
+* Export `modify_object` method
+* Add more attributes to ManagementConsole schema definition
+* Add schema definitions for more IOAdapters
+## v0.15.0
+* Add `managed_systems_quick` and `managed_system_quick` methods
+## v0.14.0
+* Make search parameter a string instead of a hash
+* Add `is_classic_hmc_mgmt` and `is_hmc_mgmt_master` to schema definitions
+## v0.13.0
+* Add `lpar_migrate_validate` and `lpar_migrate` methods
+* Add `vscsi_client_adapter` and `vfc_client_adapter` methods
+* Add schema definition for SharedProcessorPool
+## 0.12.0
+* Add permissive parameter to vioses method
+* Add draft parameter to templates and `templates_summary` methods
+* Add `template_copy` method
+* Add `sys_uuid` parameter to `managed_system_pcm_preferences` method
+## v0.11.0
+* Add `template_check`, `template_transform` and `template_provision` methods
+* Add JobFailed exception
+* Add vfc, vlans, vscsi setters to schema definition for templates
+## v0.10.0
+* Add `managed_system_pcm_preferences` method
+* Add schema definitions for PCM
+## v0.9.0
+* Add groups method
+* Add SSH public keys to ManagementConsole schema definition
+* Add schema definitions for groups
+* Add schema definition for SharedFileSystemFile
+* Fix parsing of unknown backing devices
+## v0.8.0
+* Add templates method
+## v0.7.0
+* Add cluster, SSP and tier methods
+* Add template methods
+* Add `capture_lpar` method
+* Add usertask method
+* Add schema definition for IOAdapter
+* Add schema definitions for disks
+* Add schema definitions for VSCSI and VFC
+* Add schema definitions for cluster, SSP and tier
+* Add schema definitions for templates
+## v0.6.0
+* Add SRIOV and VNIC methods
+* Add schema definitions for SRIOVEthernetLogicalPort and VirtualNICDedicated
+## v0.5.0
+* Add `virtual_networks` method for VLANs
+* Add schema definitions for VirtualNetwork, VirtualIOAdapter, VirtualEthernetAdapter
+## v0.4.0
+* Add `network_adapter_lpar` and `network_adapter_vios` methods
+* Add `virtual_switches` and `virtual_switch` methods
+* Add schema definitions for VirtualSwitch and ClientNetworkAdapter
+## v0.3.0
+* Add `rename_lpar` method
+* Add `remove_connection` method
+## v0.2.0
+* Add rubocop local overrides
+* Add PCM APIs
+* Add search parameter
+## v0.1.0
 * Initial release

data/README.md

@@ -70,7 +70,21 @@ Shutting down a logical partition:
 hc.poweroff_lpar(lpar_uuid, { "operation" => "shutdown" })
 ```
 
-Processing events:
+Setting the memory of a logical partition to 32GB:
+
+```ruby
+hc.modify_object do
+  hc.lpar(lpar_uuid).tap { |lpar| lpar.desired_memory = 32_768 }
+end
+```
+
+Listing serviceable events:
+
+```ruby
+puts hc.serviceable_events
+```
+
+Processing HMC events:
 
 ```ruby
 loop do

data/lib/ibm_power_hmc/apis/connection.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# Module for IBM HMC Rest API Client
+module IbmPowerHmc
+  class Error < StandardError; end
+
+  ##
+  # HMC REST Client connection.
+  class Connection
+    ##
+    # @!method initialize(host:, password:, username: "hscroot", port: 12_443, validate_ssl: true, timeout: 60)
+    # Create a new HMC connection.
+    #
+    # @param host [String] Hostname of the HMC.
+    # @param password [String] Password.
+    # @param username [String] User name.
+    # @param port [Integer] TCP port number.
+    # @param validate_ssl [Boolean] Verify SSL certificates.
+    # @param timeout [Integer] The default HTTP timeout in seconds.
+    def initialize(host:, password:, username: "hscroot", port: 12_443, validate_ssl: true, timeout: 60)
+      @hostname = "#{host}:#{port}"
+      @username = username
+      @password = password
+      @verify_ssl = validate_ssl
+      @api_session_token = nil
+      @timeout = timeout
+    end
+
+    ##
+    # @!method logon
+    # Establish a trusted session with the Web Services APIs.
+    # @return [String] The X-API-Session token.
+    def logon
+      method_url = "/rest/api/web/Logon"
+      headers = {
+        :content_type => "application/vnd.ibm.powervm.web+xml; type=LogonRequest"
+      }
+      doc = REXML::Document.new("")
+      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
+
+      @api_session_token = ""
+      response = request(:put, method_url, headers, doc.to_s)
+      doc = REXML::Document.new(response.body)
+      elem = doc.elements["LogonResponse/X-API-Session"]
+      raise Error, "LogonResponse/X-API-Session not found" if elem.nil?
+
+      @api_session_token = elem.text
+    end
+
+    ##
+    # @!method logoff
+    # Close the session.
+    def logoff
+      # Don't want to trigger automatic logon here!
+      return if @api_session_token.nil?
+
+      method_url = "/rest/api/web/Logon"
+      begin
+        request(:delete, method_url)
+      rescue
+        # Ignore exceptions as this is best effort attempt to log off.
+      end
+      @api_session_token = nil
+    end
+
+    ##
+    # @!method usertask(uuid = true)
+    # Retrieve details of an event of type "user task".
+    # @param uuid [String] UUID of user task.
+    # @return [Hash] Hash of user task attributes.
+    def usertask(uuid)
+      method_url = "/rest/api/ui/UserTask/#{uuid}"
+      response = request(:get, method_url)
+      j = JSON.parse(response.body)
+      if j['status'].eql?("Completed")
+        case j['key']
+        when "TEMPLATE_PARTITION_SAVE", "TEMPLATE_PARTITION_SAVE_AS", "TEMPLATE_PARTITION_CAPTURE"
+          j['template_uuid'] = templates_summary.find { |t| t.name.eql?(j['labelParams'].first) }&.uuid
+        end
+      end
+      j
+    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, :original_exception
+
+      ##
+      # @!method initialize(err)
+      # Create a new HttpError exception.
+      # @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.
+        unless err.response.nil?
+          begin
+            resp = Parser.new(err.response.body).object(:HttpErrorResponse)
+            @uri = resp.uri
+            @reason = resp.reason
+            @message = resp.message
+          rescue
+            # not an XML body
+          end
+        end
+      end
+
+      def to_s
+        "msg=\"#{@message}\" status=\"#{@status}\" reason=\"#{@reason}\" uri=#{@uri}"
+      end
+    end
+
+    class HttpNotFound < HttpError; end
+
+    ##
+    # @!method request(method, url, headers = {}, payload = nil)
+    # Perform a REST API request.
+    # @param method [String] The HTTP method.
+    # @param url [String] The method URL.
+    # @param headers [Hash] HTTP headers.
+    # @param payload [String] HTTP request payload.
+    # @return [RestClient::Response] The response from the HMC.
+    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)
+        RestClient::Request.execute(
+          :method => method,
+          :url => url,
+          :verify_ssl => @verify_ssl,
+          :payload => payload,
+          :headers => headers,
+          :timeout => @timeout
+        )
+      rescue RestClient::Exception => e
+        raise HttpNotFound.new(e), "Not found" if e.http_code == 404
+
+        # Do not retry on failed logon attempts.
+        if e.http_code == 401 && @api_session_token != "" && !reauth
+          # Try to reauth.
+          reauth = true
+          logon
+          retry
+        end
+        raise HttpError.new(e), "REST request failed"
+      end
+    end
+
+    # @!method modify_object(headers = {}, attempts = 5)
+    # Post an IbmPowerHmc::AbstractRest object iteratively using ETag.
+    # @param headers [Hash] HTTP headers.
+    # @param attempts [Integer] Maximum number of retries.
+    # @yieldreturn [IbmPowerHmc::AbstractRest] The object to modify.
+    def modify_object(headers = {}, attempts = 5, &block)
+      modify_object_url(nil, headers, attempts, &block)
+    end
+
+    private
+
+    def modify_object_url(method_url = nil, headers = {}, attempts = 5)
+      while attempts > 0
+        obj = yield
+        raise "object has no href" if method_url.nil? && (!obj.kind_of?(AbstractRest) || obj.href.nil?)
+
+        # 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.nil? ? obj.href.to_s : 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
+  end
+end

data/lib/ibm_power_hmc/apis/sem.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+##
+# Serviceable Events Manager.
+
+module IbmPowerHmc
+  class Connection
+    ##
+    # @!method serviceable_events(status = nil)
+    # Retrieve serviceable events from the HMC.
+    # @param status [String] Query only events in that state.
+    # @return [Array<IbmPowerHmc::ServiceableEvent>] The list of serviceable events.
+    def serviceable_events(status = nil)
+      method_url = "/rest/api/sem/ServiceableEvent"
+      method_url += "?status=#{status}" unless status.nil?
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:ServiceableEvent)
+    end
+  end
+end

data/lib/ibm_power_hmc/apis/templates.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module IbmPowerHmc
+  class Connection
+    ##
+    # @!method templates_summary(draft = false)
+    # 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(draft = false)
+      method_url = "/rest/api/templates/PartitionTemplate#{'?draft=false' unless draft}"
+      response = request(:get, method_url)
+      FeedParser.new(response.body).objects(:PartitionTemplateSummary)
+    end
+
+    ##
+    # @!method templates(draft = false)
+    # 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(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
+
+    ##
+    # @!method template(template_uuid)
+    # Retrieve details for a particular partition template.
+    # @param template_uuid [String] UUID of the partition template.
+    # @return [IbmPowerHmc::PartitionTemplate] The partition template.
+    def template(template_uuid)
+      method_url = "/rest/api/templates/PartitionTemplate/#{template_uuid}"
+      response = request(:get, method_url)
+      Parser.new(response.body).object(:PartitionTemplate)
+    end
+
+    ##
+    # @!method capture_lpar(lpar_uuid, sys_uuid, template_name, sync = true)
+    # Capture partition configuration as template.
+    # @param lpar_uuid [String] The UUID of the logical partition.
+    # @param sys_uuid [String] The UUID of the managed system.
+    # @param template_name [String] The name to be given for the new template.
+    # @param sync [Boolean] Start the job and wait for its completion.
+    # @return [IbmPowerHmc::HmcJob] The HMC job.
+    def capture_lpar(lpar_uuid, sys_uuid, template_name, sync = true)
+      # Need to include session token in payload so make sure we are logged in
+      logon if @api_session_token.nil?
+      method_url = "/rest/api/templates/PartitionTemplate/do/capture"
+      params = {
+        "TargetUuid"              => lpar_uuid,
+        "NewTemplateName"         => template_name,
+        "ManagedSystemUuid"       => sys_uuid,
+        "K_X_API_SESSION_MEMENTO" => @api_session_token
+      }
+      job = HmcJob.new(self, method_url, "Capture", "PartitionTemplate", params)
+      job.run if sync
+      job
+    end
+
+    ##
+    # @!method 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)
+      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_modify(template_uuid, changes)
+    # Modify a template.
+    # @param template_uuid [String] UUID of the partition template to modify.
+    # @param changes [Hash] Hash of changes to make.
+    def template_modify(template_uuid, changes)
+      method_url = "/rest/api/templates/PartitionTemplate/#{template_uuid}"
+
+      # Templates have no href so need to use modify_object_url.
+      modify_object_url(method_url) do
+        template(template_uuid).tap do |obj|
+          changes.each do |key, value|
+            obj.send("#{key}=", value)
+          end
+        end
+      end
+    end
+
+    ##
+    # @!method template_copy(template_uuid, new_name)
+    # Copy existing template to a new one.
+    # @param template_uuid [String] UUID of the partition template to copy.
+    # @param new_name [String] Name of the new template.
+    # @return [IbmPowerHmc::PartitionTemplate] The new partition template.
+    def template_copy(template_uuid, new_name)
+      method_url = "/rest/api/templates/PartitionTemplate"
+      headers = {
+        :content_type => "application/vnd.ibm.powervm.templates+xml;type=PartitionTemplate"
+      }
+      original = template(template_uuid)
+      original.name = new_name
+      response = request(:put, method_url, headers, original.xml.to_s)
+      Parser.new(response.body).object(:PartitionTemplate)
+    end
+  end
+end