foreman_openbolt 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6aae14c90bc7a4af6435767a84d174b69309e9f98ae59a221477067be2492b8
-  data.tar.gz: 2d3e9188b01cf3c03bc132440106271b541f8ab753df060984e559b624058631
+  metadata.gz: a7444805dbd4902da2b3b411388c28968cc4a893d00d244caacd8ed083cca78e
+  data.tar.gz: 90aab4b505c4347d212324094d7d5d73b8a1dcc9148eafa40a2be77e8fdee083
 SHA512:
-  metadata.gz: 4f2f8a142ca2e214836b36c5f22be10975c322b5df20830110edc09ef49ac6b1445bccb22ffbe7b6d3252efb140d9ce45b1fa11d12987df27270fbd014e497ca
-  data.tar.gz: b05c9442560d6acc1720c7495c30fe213f2b59ea72f5aefe37f3b7cab98b863b6c22add8fa3fd010b6b3803075b4c46ad130232c7b804d2dfffd6f4f118f17fe
+  metadata.gz: 40e72f42e822e1b4a488a71ef10b203db849ac69978fac1eb400c6be55e6d799262ed37f7dbfe039fded5cf4a2e18255c76bf24af6981d400ae63c6077019349
+  data.tar.gz: 05dca9f1a59475878cc3435a1fa8fd21dbc6aee16346bb204a60980eafc3a881b1f431a4ab3d4b9043f92b6a4c46bc5b71129872af1fae5293910f5458a05566

data/README.md

@@ -68,6 +68,7 @@ A handful of core/default Tasks & Plans are also included in the [OpenBolt rpm/d
 ## Documentation
 
 - [Usage](docs/usage.md): screenshots and walkthrough of the UI
+- [API](docs/api.md): REST API reference, authentication, and example requests
 - [Development](docs/development.md): linting, unit tests, acceptance tests, building packages
 - [Releasing](docs/releasing.md): version locations, release steps, RPM/DEB packaging
 - [Choria Testing](docs/choria-testing.md): setting up Choria on a Foreman install for transport testing

data/app/controllers/api/v2/openbolt_jobs_controller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Api
+  module V2
+    class OpenboltJobsController < Api::V2::BaseController
+      include Api::Version2
+      include ForemanOpenbolt::Jobs
+
+      resource_description do
+        resource_id 'openbolt_jobs'
+        api_version 'v2'
+        api_base_url '/api/v2/openbolt'
+      end
+
+      def resource_class
+        ForemanOpenbolt::TaskJob
+      end
+
+      def_param_group :job do
+        property :job_id, String, desc: N_('Proxy-issued job ID')
+        property :kind, %w[task], desc: N_("Job kind. Currently always 'task', and will include 'plan' at a later date.")
+        property :status, ForemanOpenbolt::TaskJob::STATUSES, desc: N_('Status of the job')
+        property :submitted_at, Time, desc: N_('When the job was submitted to the proxy')
+        property :completed_at, Time, allow_nil: true, desc: N_('When the job completed. Empty while the job is running.')
+        property :duration, Float, allow_nil: true, desc: N_('Job duration in seconds. Empty while the job is running.')
+        property :name, String, desc: N_('Name of the launched Bolt task (or later, plan)')
+        property :description, String, allow_nil: true, desc: N_('Description of the launched Bolt task (or later, plan)')
+        property :parameters, Hash, desc: N_('Parameters the job was launched with')
+        property :targets, Array, of: String, desc: N_('Target hosts the job was launched against for tasks')
+        property :smart_proxy, Hash, desc: N_('Smart proxy that executed the job') do
+          property :id, Integer, desc: N_('Smart proxy ID')
+          property :name, String, desc: N_('Smart proxy name')
+        end
+      end
+
+      api :GET, '/jobs', N_('List of OpenBolt jobs recorded in Foreman')
+      param_group :pagination, Api::V2::BaseController
+      returns code: 200, desc: N_('Paginated list of jobs') do
+        property :total, Integer, desc: N_('Total number of recorded jobs')
+        property :page, Integer, desc: N_('Current page number')
+        property :per_page, Integer, desc: N_('Number of jobs per page')
+        property :results, Array, desc: N_('Job objects for the requested page') do
+          param_group :job, ::Api::V2::OpenboltJobsController
+        end
+      end
+      def jobs
+        super
+      end
+
+      api :GET, '/jobs/:job_id/status', N_('Get the current status of an OpenBolt job')
+      param :job_id, :identifier, required: true, desc: N_('Proxy-issued job ID returned by /launch/task')
+      returns :job, code: 200, desc: N_('Current status of the job')
+      def job_status
+        super
+      end
+
+      api :GET, '/jobs/:job_id/result',
+        N_('Get the full result (command, OpenBolt result value, log) of a completed OpenBolt job')
+      param :job_id, :identifier, required: true, desc: N_('Proxy-issued job ID returned by /launch/task')
+      returns code: 200, desc: N_('Full result of the job') do
+        property :kind, %w[task], desc: N_("Job kind. Currently always 'task', and will include 'plan' at a later date.")
+        property :status, ForemanOpenbolt::TaskJob::STATUSES, desc: N_('Status of the job')
+        property :command, String, allow_nil: true,
+          desc: N_('The OpenBolt command the proxy ran, with sensitive option values scrubbed. ' \
+                   'Empty until the proxy reports the first status update.')
+        property :value, [Hash, String], allow_nil: true,
+          desc: N_('Run result as produced by the OpenBolt CLI, passed through unmodified. ' \
+                   'Its layout depends on the job kind and the OpenBolt Result format. ' \
+                   'On failure or exception, this may instead be a plain string holding the raw output.')
+        property :log, String, allow_nil: true, desc: N_('Output log of the run')
+      end
+      def job_result
+        super
+      end
+    end
+  end
+end

data/app/controllers/api/v2/openbolt_tasks_controller.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'foreman/logging'
+require 'proxy_api/openbolt'
+
+module Api
+  module V2
+    class OpenboltTasksController < Api::V2::BaseController
+      include Api::Version2
+      include ForemanOpenbolt::Tasks
+
+      resource_description do
+        resource_id 'openbolt_tasks'
+        api_version 'v2'
+        api_base_url '/api/v2/openbolt'
+      end
+
+      def_param_group :task_map do
+        property :task_name, Hash, required: false,
+          desc: N_('One entry per task, keyed by the task name. "task_name" is a placeholder, and the actual keys are the task names.') do
+          property :description, String, desc: N_('Description from the task metadata')
+          property :parameters, Hash,
+            desc: N_('Parameter definitions from the task metadata, keyed by parameter name')
+        end
+      end
+
+      api :GET, '/smart_proxies/:smart_proxy_id/tasks', N_('List Bolt tasks available on a smart proxy')
+      param :smart_proxy_id, Integer, required: true, desc: N_('ID of the smart proxy to query')
+      returns :task_map, code: 200, additional_properties: true,
+        desc: N_('Hash keyed by task name. task_name below is a placeholder, and the actual keys are the task names.')
+      def tasks
+        super
+      end
+
+      api :POST, '/smart_proxies/:smart_proxy_id/tasks/reload', N_("Reload the smart proxy's Bolt task cache")
+      param :smart_proxy_id, Integer, required: true, desc: N_('ID of the smart proxy to reload')
+      returns :task_map, code: 200, additional_properties: true,
+        desc: N_('The refreshed task list, in the same shape as the tasks endpoint response')
+      def reload_tasks
+        super
+      end
+
+      api :GET, '/smart_proxies/:smart_proxy_id/tasks/options',
+        N_('Get OpenBolt options metadata for a smart proxy, with Foreman setting defaults merged in')
+      param :smart_proxy_id, Integer, required: true, desc: N_('ID of the smart proxy to query')
+      returns code: 200, additional_properties: true,
+        desc: N_('Hash keyed by option name. "option_name" is a placeholder, and the actual keys are the option names.') do
+        property :option_name, Hash, required: false, desc: N_('One entry per option, keyed by the option name') do
+          property :type, [String, Array],
+            desc: N_("The option's value type, either a type name or an array of the allowed values")
+          property :transport, Array, of: String, desc: N_('Transports the option applies to')
+          property :sensitive, [true, false], desc: N_('Whether the value is scrubbed from recorded commands and logs')
+          property :description, String, desc: N_('Human readable description of the option')
+          property :default, [String, Integer, TrueClass, FalseClass], required: false,
+            desc: N_('Default value, from the smart proxy or a Foreman setting when one is set. ' \
+                     'If a Foreman setting is present and this is a sensitive type, the default value ' \
+                     'will read "[Use saved ecrypted default]".')
+        end
+      end
+      def task_options
+        super
+      end
+
+      api :POST, '/launch/task', N_('Launch a Bolt task on a smart proxy')
+      param :smart_proxy_id, Integer, required: true,
+        desc: N_('ID of the smart proxy that will execute the task')
+      param :task_name, String, required: true, desc: N_('Name of the Bolt task to run')
+      param :targets, String, required: true,
+        desc: N_('Comma-separated list of target hosts the task should run on')
+      param :parameters, Hash, required: false,
+        desc: N_('Task-specific parameters, keyed by parameter name')
+      param :options, Hash, required: false,
+        desc: N_('OpenBolt options (transport, user, run-as, etc.) as accepted by the bolt CLI')
+      returns code: 201, desc: N_('Job accepted by the smart proxy') do
+        property :job_id, String, desc: N_('Proxy-issued job ID, usable with the /jobs/:job_id endpoints')
+        property :kind, %w[task], desc: N_("Currently always 'task', and will include 'plan' at a later date.")
+      end
+      def launch_task
+        super
+      end
+    end
+  end
+end

data/app/controllers/concerns/foreman_openbolt/common.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'foreman/logging'
+require 'proxy_api/openbolt'
+
+module ForemanOpenbolt
+  module Common
+    extend ActiveSupport::Concern
+
+    ENCRYPTED_PLACEHOLDER = '[Use saved encrypted default]'
+    REDACTED_PLACEHOLDER = '*****'
+
+    class LaunchError < StandardError; end
+
+    # The caller sent the encrypted placeholder for an option with no saved setting.
+    class MissingEncryptedDefault < StandardError; end
+
+    # The proxy accepted the task but Foreman could not record or track it.
+    class PartialLaunchError < StandardError; end
+
+    included do
+      rescue_from ForemanOpenbolt::Common::LaunchError do |error|
+        logger.warn("OpenBolt #{openbolt_surface} launch failed: #{error.class}: #{error.message}")
+        render_json_error(error.message, :bad_request)
+      end
+
+      rescue_from ForemanOpenbolt::Common::PartialLaunchError do |error|
+        Foreman::Logging.exception("OpenBolt #{openbolt_surface} partial launch failure: #{error.message}", error)
+        render_json_error(error.message, :internal_server_error)
+      end
+
+      rescue_from ProxyAPI::ProxyException do |error|
+        Foreman::Logging.exception("OpenBolt #{openbolt_surface} proxy call failed", error)
+        render_json_error("Smart Proxy error: #{error.message}", :bad_gateway)
+      end
+
+      rescue_from ForemanOpenbolt::Common::MissingEncryptedDefault do |error|
+        logger.warn("OpenBolt #{openbolt_surface} missing encrypted default failure: #{error.message}")
+        render_json_error(error.message, :bad_request)
+      end
+    end
+
+    def openbolt_surface
+      self.class.name.start_with?('Api::') ? 'API' : 'UI'
+    end
+
+    def openbolt_settings
+      @openbolt_settings ||= Foreman.settings.category_settings(:openbolt).values
+    end
+
+    def merge_encrypted_defaults(options)
+      merged = options.dup
+      merged.each do |key, value|
+        next unless value == ENCRYPTED_PLACEHOLDER
+
+        saved = Setting["openbolt_#{key}"]
+        if saved.nil? || saved.to_s.empty?
+          raise MissingEncryptedDefault,
+            "No saved value for encrypted option '#{key}'. Configure it on the Foreman Settings page or provide a value."
+        end
+        merged[key] = saved
+      end
+      merged
+    end
+
+    def scrub_options_for_storage(options)
+      scrubbed = options.dup
+      openbolt_settings.select(&:encrypted?).each do |setting|
+        option_name = setting.name.sub(/^openbolt_/, '')
+        scrubbed[option_name] = REDACTED_PLACEHOLDER if scrubbed.key?(option_name)
+      end
+      scrubbed
+    end
+
+    def openbolt_options_with_defaults
+      options = @openbolt_api.openbolt_options
+
+      defaults = {}
+      openbolt_settings.each do |setting|
+        key = setting.name.sub(/^openbolt_/, '')
+        if setting.encrypted?
+          defaults[key] = ENCRYPTED_PLACEHOLDER unless setting.value.to_s.empty?
+        elsif !setting.value.to_s.empty?
+          defaults[key] = setting.value
+        end
+      end
+
+      result = {}
+      options.each do |name, meta|
+        result[name] = meta.dup
+        result[name]['default'] = defaults[name] if defaults.key?(name)
+      end
+      result
+    end
+
+    # before_action helpers shared by UI and API controllers
+    def load_smart_proxy
+      smart_proxy_id = params[:smart_proxy_id]
+      if smart_proxy_id.blank?
+        render_json_error('Smart Proxy ID is required', :bad_request)
+        return
+      end
+      @smart_proxy = SmartProxy.authorized(:view_smart_proxies).find_by(id: smart_proxy_id)
+      return if @smart_proxy
+      render_json_error("Smart Proxy with ID #{smart_proxy_id} not found or not authorized", :not_found)
+    end
+
+    def load_openbolt_api
+      return unless @smart_proxy
+      @openbolt_api = ProxyAPI::Openbolt.new(url: @smart_proxy.url)
+    rescue StandardError => e
+      Foreman::Logging.exception("load_openbolt_api for proxy #{@smart_proxy.name}", e)
+      render_json_error('Failed to connect to Smart Proxy', :bad_gateway)
+    end
+
+    # Matches Foreman's custom_error template so UI and API errors share one shape.
+    def render_json_error(message, status)
+      render json: { error: { message: message } }, status: status
+    end
+  end
+end

data/app/controllers/concerns/foreman_openbolt/jobs.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ForemanOpenbolt
+  module Jobs
+    extend ActiveSupport::Concern
+    include ForemanOpenbolt::Common
+
+    included do
+      before_action :load_task_job, only: [:job_status, :job_result]
+    end
+
+    def load_task_job
+      job_id = params[:job_id]
+      if job_id.blank?
+        render_json_error('Job ID is required', :bad_request)
+        return
+      end
+      @task_job = ForemanOpenbolt::TaskJob.find_by(job_id: job_id)
+      logger.debug { "TaskJob lookup #{job_id.inspect}: #{@task_job ? @task_job.status : 'not found'}" }
+      return if @task_job
+      render_json_error("Job #{job_id} not found", :not_found)
+    end
+
+    def task_job_status(task_job)
+      {
+        job_id: task_job.job_id,
+        kind: task_job.kind,
+        status: task_job.status,
+        submitted_at: task_job.submitted_at,
+        completed_at: task_job.completed_at,
+        duration: task_job.duration,
+        name: task_job.task_name,
+        description: task_job.task_description,
+        parameters: task_job.task_parameters,
+        targets: task_job.targets,
+        smart_proxy: {
+          id: task_job.smart_proxy_id,
+          name: task_job.smart_proxy&.name || '(unknown)',
+        },
+      }
+    end
+
+    def task_job_result(task_job)
+      {
+        kind: task_job.kind,
+        status: task_job.status,
+        command: task_job.command,
+        value: task_job.result,
+        log: task_job.log,
+      }
+    end
+
+    def paginated_task_jobs(per_page_param:, page:)
+      page = [page.to_i, 1].max
+      per_page = if per_page_param == 'all'
+                   [ForemanOpenbolt::TaskJob.count, 1].max
+                 elsif per_page_param.present?
+                   per_page_param.to_i.clamp(1, 100)
+                 else
+                   20
+                 end
+      ForemanOpenbolt::TaskJob.includes(:smart_proxy).recent.paginate(page: page, per_page: per_page)
+    end
+
+    def job_status
+      render json: task_job_status(@task_job)
+    end
+
+    def job_result
+      render json: task_job_result(@task_job)
+    end
+
+    def jobs
+      paginated = paginated_task_jobs(per_page_param: params[:per_page], page: params[:page])
+
+      render json: {
+        total: paginated.total_entries,
+        page: paginated.current_page,
+        per_page: paginated.per_page,
+        results: paginated.map { |job| task_job_status(job) },
+      }
+    end
+  end
+end

data/app/controllers/concerns/foreman_openbolt/tasks.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'foreman/logging'
+
+module ForemanOpenbolt
+  module Tasks
+    extend ActiveSupport::Concern
+    include ForemanOpenbolt::Common
+
+    included do
+      before_action :load_smart_proxy, only: [:tasks, :reload_tasks, :task_options, :launch_task]
+      before_action :load_openbolt_api, only: [:tasks, :reload_tasks, :task_options, :launch_task]
+    end
+
+    # Shared by the API and UI controllers. The API controller wraps each
+    # action with super so it can attach apipie docs.
+    def tasks
+      render json: @openbolt_api.tasks
+    end
+
+    def reload_tasks
+      render json: @openbolt_api.reload_tasks
+    end
+
+    def task_options
+      render json: openbolt_options_with_defaults
+    end
+
+    def launch_task
+      job_id = dispatch_task(
+        smart_proxy: @smart_proxy,
+        openbolt_api: @openbolt_api,
+        task_name: params[:task_name],
+        targets: params[:targets],
+        parameters: params[:parameters] || {},
+        options: params[:options] || {}
+      )
+      render json: { job_id: job_id, kind: 'task' }, status: :created
+    end
+
+    # Submits a task to the proxy, saves the TaskJob, and schedules polling.
+    # Returns the proxy-issued job id. Failures after the proxy accepts the
+    # launch raise PartialLaunchError. The proxy job keeps running and there
+    # is no proxy-side cancel hook right now, so we only surface the failure.
+    def dispatch_task(smart_proxy:, openbolt_api:, task_name:, targets:, parameters:, options:)
+      task_name = task_name.to_s.strip
+      targets = targets.to_s.strip
+      raise ForemanOpenbolt::Common::LaunchError, 'Task name and targets cannot be empty' if task_name.empty? || targets.empty?
+
+      merged_options = merge_encrypted_defaults(options)
+
+      logger.info { "Launching OpenBolt task '#{task_name}' on targets '#{targets}' via proxy #{smart_proxy.name}" }
+
+      response = openbolt_api.launch_task(
+        name: task_name,
+        targets: targets,
+        parameters: parameters,
+        options: merged_options
+      )
+      logger.debug { "Task execution response: #{response.inspect}" }
+
+      if response['error']
+        error_detail = response['error'].is_a?(Hash) ? response['error']['message'] : response['error']
+        raise ForemanOpenbolt::Common::LaunchError, "Task execution failed: #{error_detail}"
+      end
+      raise ForemanOpenbolt::Common::LaunchError, 'Task execution failed: No job ID returned' unless response['id']
+
+      # The proxy is now running the task so any failures below are partial state.
+      job_id = response['id']
+
+      task_job = begin
+        # Metadata is optional and a fetch failure should not abort a running job.
+        metadata = begin
+          fetched = openbolt_api.tasks[task_name]
+          if fetched.nil?
+            logger.warn(
+              "Proxy accepted launch of '#{task_name}' (job #{job_id}) but " \
+              "the task is not in the proxy's task list. Description will be empty."
+            )
+          end
+          fetched || {}
+        rescue StandardError => e
+          logger.warn(
+            "Could not fetch task metadata for #{task_name} after launching " \
+            "job #{job_id}: #{e.class}: #{e.message}. Proceeding without description."
+          )
+          {}
+        end
+
+        ForemanOpenbolt::TaskJob.create_from_execution!(
+          proxy: smart_proxy,
+          task_name: task_name,
+          task_description: metadata['description'] || '',
+          targets: targets.split(',').map(&:strip),
+          parameters: parameters,
+          options: scrub_options_for_storage(merged_options),
+          job_id: job_id
+        )
+      rescue StandardError => e
+        Foreman::Logging.exception(
+          "OpenBolt job #{job_id} launched on proxy #{smart_proxy.name} " \
+          "but the Foreman TaskJob row could not be created",
+          e
+        )
+        raise ForemanOpenbolt::Common::PartialLaunchError,
+          "Task launched on the proxy (job #{job_id}) but Foreman could not " \
+          "record it. The task will run on the proxy unmonitored. Error: #{e.message}"
+      end
+
+      begin
+        ForemanTasks.async_task(Actions::ForemanOpenbolt::PollTaskStatus,
+          job_id,
+          smart_proxy.id)
+      rescue StandardError => e
+        Foreman::Logging.exception(
+          "OpenBolt job #{job_id} launched on proxy #{smart_proxy.name} " \
+          "but PollTaskStatus could not be scheduled",
+          e
+        )
+        # Capture before update! flips the in-memory status.
+        previous_status = task_job.status
+        begin
+          task_job.update!(status: 'exception')
+        rescue StandardError => update_error
+          Foreman::Logging.exception(
+            "Could not mark TaskJob #{job_id} as exception after polling-" \
+            "schedule failure. Row will remain in '#{previous_status}' state.",
+            update_error
+          )
+        end
+        raise ForemanOpenbolt::Common::PartialLaunchError,
+          "Task launched on the proxy (job #{job_id}) but background polling " \
+          "could not be scheduled. The task will run on the proxy without " \
+          "status updates in Foreman. Error: #{e.message}"
+      end
+
+      job_id
+    end
+  end
+end