smart_proxy_openbolt 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6197325aea83c274a58cefe654d2fcf0f5afd29a6cd64b0ff66207f061b6a30
-  data.tar.gz: e061867b08ce03aa03a235f48508ffe10d88abd3f4dbdd84d09ad1f6de90a6f3
+  metadata.gz: b6a0f4f6e883f4a2077ea3afccd8f244a1dfd27aafa73c6ce69f29ee423f921b
+  data.tar.gz: f74f56b1108bc2d0570af5135c225194d046e40e5741541265eff68c4bc61359
 SHA512:
-  metadata.gz: 85fd5c0b3a05acd9f9ced2ad741bf688d70191db79204609a90f6e6d3cc5d1a14602d9e0719b32ee18c56e73e2775588a8167c5431c6ee17f72a7be78b57859f
-  data.tar.gz: 9d79f77a3b4912d4e32056064f5a9fbf9d0e7efb06870d6693a21832dfc1f19287a741426a8494c897d4da0071749c28feca5af0dfafd4148ebd7ab88e82c374
+  metadata.gz: cfcc15bcfa344fa5a92b323ec6c9e9a11a0408ac49f111e1bf45e1eafdb228c5a557909d489cadde2594b54e8fd063de944dfff352bca9fca2950b4ac839477f
+  data.tar.gz: 427492ec2136bf63d811c50edd8fa24ab2642e0b54180b97bc02f4c396e9188fa8963d35d845bdc59f06bd0a591b7bdbf2e3317dd84d166ce2522b4a199e774d

data/README.md

@@ -12,14 +12,14 @@ It exposes an HTTP API that the [foreman_openbolt](https://github.com/overlookin
 ## Introduction
 
 [OpenBolt](https://github.com/OpenVoxProject/openbolt) is the open source successor of [Bolt](https://github.com/puppetlabs/bolt) by [Perforce](https://www.perforce.com/).
-It runs Tasks and Plans against remote targets over SSH, WinRM, or other transports.
+It runs Tasks and Plans against remote targets over SSH, WinRM, Choria, or other transports.
 
 This smart proxy plugin wraps the OpenBolt CLI and provides:
 
 * A REST API for listing available tasks, launching task runs, and retrieving results
 * Concurrent job execution via a configurable thread pool
 * Disk-based result storage so results survive proxy restarts
-* Transport option forwarding (SSH, WinRM) from the Foreman UI
+* Transport option forwarding (SSH, WinRM, Choria) from the Foreman UI
 
 The Foreman UI talks to this plugin; it does not invoke OpenBolt directly. See the [foreman_openbolt README](https://github.com/overlookinfra/foreman_openbolt) for screenshots and the full user-facing workflow.
 
@@ -66,6 +66,72 @@ The plugin is configured in `settings.d/openbolt.yml` on the Smart Proxy host. A
 | `connect_timeout` | `30` | Connection timeout in seconds for target connections |
 | `log_dir` | `/var/log/foreman-proxy/openbolt` | Directory for job result files (created automatically if missing) |
 
+After installing the plugin and restarting the smart proxy, refresh the
+proxy features in Foreman so it detects the OpenBolt capability:
+
+```bash
+foreman-rake openbolt:refresh_proxies
+```
+
+## Choria Transport
+
+**Requires OpenBolt 5.5 or later.** The Choria transport is not available
+in Puppet Bolt. SSH and WinRM transports work with any version.
+
+The Choria transport works out of the box on HTTPS-enabled proxies. The
+proxy ships a built-in MCollective client configuration and automatically
+derives SSL paths and the MCollective certname from the proxy's own
+OpenVox/Puppet certificates (configured via `ssl_certificate`,
+`ssl_private_key`, and `ssl_ca_file` in `settings.yml`).
+
+The `foreman-proxy` user must be in the `puppet` group to read the SSL
+files. This is the default when the proxy is set up with
+`foreman-installer` (the `puppet-foreman_proxy` module's
+`manage_puppet_group` parameter handles this).
+
+In common configurations where the Choria broker and Foreman are on the
+same host, OpenVox/Puppet certificates are being used for authentication,
+and Choria configuration is largely using default settings, the Choria
+transport mostly just works out of the box with default settings. The one
+setting you may need to evaluate is **Choria Brokers** (in the Foreman UI
+under Administer > Settings > OpenBolt). If `puppet` resolves to the
+broker host or SRV records are configured, it can be left blank. Otherwise,
+set it to your broker's address (e.g. `primary.example.com:4222`). Other
+Choria settings (SSL, a default config file we provide, certname) are
+derived automatically and can be ignored unless your Choria configuration
+requires customization.
+
+### Custom Choria configuration file
+
+The built-in default config is at
+`lib/smart_proxy_openbolt/config/choria-client.conf` in this gem. You
+can view it to see what settings are included. To use a custom
+MCollective client configuration file instead, set the "Choria Config
+File" setting under Administer > Settings > OpenBolt. When a custom
+config file is provided, the proxy does not inject SSL defaults (the
+config file is expected to handle SSL on its own). SSL settings from
+the Foreman UI still override the config file if set.
+
+If your custom config file includes its own SSL paths, you should also
+set **Choria MCollective Certname** to the CN of the certificate in your
+config file. Without it, the MCollective client defaults to
+`<user>.mcollective` (e.g. `foreman-proxy.mcollective`), which will fail
+authentication if the certificate's CN doesn't match that pattern.
+
+### How it works
+
+When the transport is Choria and no custom config file is provided:
+
+1. The proxy uses its built-in `choria-client.conf` (MCollective boilerplate)
+2. SSL cert, key, and CA default from the proxy's `settings.yml` SSL paths
+3. The MCollective certname is read from the certificate's CN
+4. All values are passed as OpenBolt CLI flags (`--choria-ssl-cert`,
+   `--choria-ssl-key`, `--choria-ssl-ca`, `--choria-mcollective-certname`,
+   `--choria-config-file`)
+
+For full Choria infrastructure setup (broker, managed nodes, Puppet modules),
+see the [Choria Testing](https://github.com/overlookinfra/foreman_openbolt/blob/main/docs/choria-testing.md) guide in the foreman_openbolt repo.
+
 ## API
 
 The plugin mounts its API at `/openbolt` on the Smart Proxy. All endpoints are used by the Foreman plugin and are not intended for direct use, but can be useful for debugging.
@@ -74,7 +140,7 @@ The plugin mounts its API at `/openbolt` on the Smart Proxy. All endpoints are u
 |--------|----------|-------------|
 | `GET` | `/openbolt/tasks` | List available tasks from the configured environment |
 | `GET` | `/openbolt/tasks/reload` | Clear the task cache and reload from disk |
-| `GET` | `/openbolt/tasks/options` | Get available transport options (SSH, WinRM) |
+| `GET` | `/openbolt/tasks/options` | Get available transport options (SSH, WinRM, Choria) |
 | `POST` | `/openbolt/launch/task` | Launch a task run against specified targets |
 | `GET` | `/openbolt/job/:id/status` | Get the status of a running or completed job |
 | `GET` | `/openbolt/job/:id/result` | Get the full result of a completed job |
@@ -177,18 +243,13 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ### Release steps
 
-1. Bump the version in `lib/smart_proxy_openbolt/version.rb`
-2. Generate the changelog:
-   ```bash
-   CHANGELOG_GITHUB_TOKEN=github_pat_... bundle exec rake changelog
-   ```
-3. Create a PR with the version bump and changelog, get it reviewed and merged
-4. Create and push a tag matching the version:
-   ```bash
-   git tag 0.2.0
-   git push origin 0.2.0
-   ```
-5. The [release workflow](.github/workflows/release.yml) runs automatically on tag push and:
+1. Go to [Actions > Prepare Release](../../actions/workflows/prepare_release.yml) and run the workflow with the version to release (e.g. `1.2.0`)
+2. The workflow bumps the version in `version.rb`, generates the changelog, and opens a PR with the `skip-changelog` label
+3. Review and merge the PR
+4. Go to [Actions > Release](../../actions/workflows/release.yml) and run the workflow with the same version
+5. The release workflow:
+   - Verifies the version in `version.rb` matches the input
+   - Creates and pushes a git tag
    - Builds the gem
    - Creates a GitHub Release with auto-generated notes and the gem attached
    - Publishes the gem to GitHub Packages

data/lib/smart_proxy_openbolt/config/choria-client.conf

@@ -0,0 +1,25 @@
+collectives = mcollective
+main_collective = mcollective
+connector = nats
+libdir = /opt/puppetlabs/mcollective/plugins
+logger_type = console
+loglevel = warn
+securityprovider = choria
+
+# This is the default Choria client configuration shipped with
+# smart_proxy_openbolt. SSL paths, the MCollective certname, and
+# Choria broker addresses are provided by the proxy via OpenBolt
+# CLI flags and do not need to be configured here.
+#
+# To use a custom configuration file instead, set the "Choria Config
+# File" option under Administer > Settings > OpenBolt. If your config
+# file includes SSL
+# paths, leave the Choria SSL settings in Foreman blank and they
+# will be read from the config file.
+#
+# Example SSL configuration for a custom config file:
+#
+# plugin.security.provider = file
+# plugin.security.file.certificate = /etc/puppetlabs/puppet/ssl/certs/<certname>.pem
+# plugin.security.file.key = /etc/puppetlabs/puppet/ssl/private_keys/<certname>.pem
+# plugin.security.file.ca = /etc/puppetlabs/puppet/ssl/certs/ca.pem

data/lib/smart_proxy_openbolt/main.rb

@@ -1,5 +1,6 @@
 require 'json'
 require 'open3'
+require 'openssl'
 require 'smart_proxy_openbolt/executor'
 require 'smart_proxy_openbolt/error'
 
@@ -7,7 +8,7 @@ module Proxy::OpenBolt
   extend ::Proxy::Util
   extend ::Proxy::Log
 
-  TRANSPORTS = ['ssh', 'winrm'].freeze
+  TRANSPORTS = ['ssh', 'winrm', 'choria'].freeze
   # The key should be exactly the flag name passed to OpenBolt
   # Type must be :boolean, :string, or an array of acceptable string values
   # Transport must be an array of transport types it applies to. This is
@@ -25,25 +26,25 @@ module Proxy::OpenBolt
     },
     'log-level' => {
       :type => ['error', 'warning', 'info', 'debug', 'trace'],
-      :transport => ['ssh', 'winrm'],
+      :transport => ['ssh', 'winrm', 'choria'],
       :sensitive => false,
       :description => 'Set the log level during OpenBolt execution.',
     },
     'verbose' => {
       :type => :boolean,
-      :transport => ['ssh', 'winrm'],
+      :transport => ['ssh', 'winrm', 'choria'],
       :sensitive => false,
       :description => 'Run the OpenBolt command with the --verbose flag. This prints additional information during OpenBolt execution and will print any out::verbose plan statements.',
     },
     'noop' => {
       :type => :boolean,
-      :transport => ['ssh', 'winrm'],
+      :transport => ['ssh', 'winrm', 'choria'],
       :sensitive => false,
       :description => 'Run the OpenBolt command with the --noop flag, which will make no changes to the target host.',
     },
     'tmpdir' => {
       :type => :string,
-      :transport => ['ssh', 'winrm'],
+      :transport => ['ssh', 'winrm', 'choria'],
       :sensitive => false,
       :description => 'Directory to use for temporary files on target hosts during OpenBolt execution.',
     },
@@ -95,6 +96,84 @@ module Proxy::OpenBolt
       :sensitive => false,
       :description => 'Verify remote host SSL certificate when connecting to hosts via WinRM.',
     },
+    'choria-task-agent' => {
+      :type => ['bolt_tasks', 'shell'],
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Choria agent used to execute tasks on target nodes. "bolt_tasks" runs tasks via the Choria bolt_tasks agent and "shell" runs them via the shell agent. Defaults to "bolt_tasks" when not specified.',
+    },
+    'choria-config-file' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Path on the smart proxy host to the Choria client configuration file. This file must be readable by the foreman-proxy user. When blank, the proxy uses a built-in default.',
+    },
+    'choria-mcollective-certname' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Override the MCollective certname for Choria client identity. When blank, the proxy derives this automatically from the SSL certificate.',
+    },
+    'choria-ssl-ca' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Path on the smart proxy host to the CA certificate used to verify Choria brokers and peers. This file must be readable by the foreman-proxy user. Must be provided together with choria-ssl-cert and choria-ssl-key.',
+    },
+    'choria-ssl-cert' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Path on the smart proxy host to the client SSL certificate used to authenticate with Choria. This file must be readable by the foreman-proxy user. Must be provided together with choria-ssl-ca and choria-ssl-key.',
+    },
+    'choria-ssl-key' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Path on the smart proxy host to the client SSL private key used to authenticate with Choria. This key must be readable by the foreman-proxy user. Must be provided together with choria-ssl-ca and choria-ssl-cert.',
+    },
+    'choria-collective' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Choria collective to route messages through.',
+    },
+    'choria-puppet-environment' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Puppet environment reported to the Choria agent when executing tasks. Defaults to "production" when not specified. Typically matches the proxy\'s environment_path setting.',
+    },
+    'choria-rpc-timeout' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Timeout in seconds for individual Choria RPC calls. Defaults to 30 when not specified.',
+    },
+    'choria-task-timeout' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Timeout in seconds for a Choria task to complete on a target node. Defaults to 300 when not specified.',
+    },
+    'choria-command-timeout' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Timeout in seconds for a Choria shell command to complete on a target node. Defaults to 60 when not specified.',
+    },
+    'choria-brokers' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Comma-separated list of Choria broker addresses in host or host:port format (e.g. broker1:4222,broker2:4222). Port defaults to 4222 if omitted.',
+    },
+    'choria-broker-timeout' => {
+      :type => :string,
+      :transport => ['choria'],
+      :sensitive => false,
+      :description => 'Timeout in seconds for establishing a connection to a Choria broker.',
+    },
   }.freeze
   SORTED_OPTIONS = OPENBOLT_OPTIONS.sort.to_h.freeze
 
@@ -241,9 +320,76 @@ module Proxy::OpenBolt
       # Normalize options, removing blank values
       options = normalize_values(options)
       logger.info("Normalized options: #{scrub(options, options.inspect)}")
-      OPENBOLT_OPTIONS.each { |key, value| options[key] ||= value[:default] if value.key?(:default) }
+      OPENBOLT_OPTIONS.each { |key, meta| options[key] ||= meta[:default] if meta.key?(:default) }
       logger.info("Options with required defaults: #{scrub(options, options.inspect)}")
 
+      # Choria transport defaults: fill in config file, SSL certs, and
+      # certname when the user has not provided them.
+      if options['transport'] == 'choria'
+        user_provided_config = options.key?('choria-config-file')
+
+        unless user_provided_config
+          shipped_config = File.join(File.dirname(__FILE__), 'config', 'choria-client.conf')
+          if File.readable?(shipped_config)
+            options['choria-config-file'] = shipped_config
+          else
+            logger.warn("Choria: shipped config at #{shipped_config} is not readable " \
+                        "(exists=#{File.exist?(shipped_config)}). Check package installation " \
+                        "and foreman-proxy user permissions.")
+          end
+        end
+
+        if !user_provided_config
+          missing_ssl = []
+          missing_ssl << 'ssl_certificate' if Proxy::SETTINGS.ssl_certificate.to_s.strip.empty?
+          missing_ssl << 'ssl_private_key' if Proxy::SETTINGS.ssl_private_key.to_s.strip.empty?
+          missing_ssl << 'ssl_ca_file' if Proxy::SETTINGS.ssl_ca_file.to_s.strip.empty?
+
+          if missing_ssl.empty?
+            options['choria-ssl-cert'] ||= Proxy::SETTINGS.ssl_certificate
+            options['choria-ssl-key']  ||= Proxy::SETTINGS.ssl_private_key
+            options['choria-ssl-ca']   ||= Proxy::SETTINGS.ssl_ca_file
+          else
+            logger.warn("Choria: cannot default SSL from proxy settings, missing: #{missing_ssl.join(', ')}. " \
+                        "Set choria-ssl-cert, choria-ssl-key, and choria-ssl-ca explicitly.")
+          end
+        elsif !options.key?('choria-ssl-cert')
+          logger.info('Choria: custom config file provided without SSL options. ' \
+                      'SSL settings will be read from the config file.')
+        end
+
+        unless options.key?('choria-mcollective-certname')
+          cert_path = options['choria-ssl-cert']
+          if cert_path.nil? && user_provided_config
+            logger.info('Choria: custom config file provided, certname will come from the config file or ' \
+                        "default to '<user>.mcollective'. Set 'choria-mcollective-certname' if needed.")
+          elsif cert_path.nil?
+            logger.warn('Choria: no choria-ssl-cert available, cannot derive mcollective-certname.')
+          elsif !File.readable?(cert_path)
+            logger.warn("Choria: cannot derive mcollective-certname, cert at #{cert_path} is not readable. " \
+                        "Set 'choria-mcollective-certname' explicitly or fix file permissions.")
+          else
+            begin
+              cert = OpenSSL::X509::Certificate.new(File.read(cert_path))
+              cn = cert.subject.to_a.find { |name, _, _| name == 'CN' }
+              if cn
+                options['choria-mcollective-certname'] = cn[1]
+              else
+                logger.warn("Choria: certificate at #{cert_path} has no CN. " \
+                            "Set 'choria-mcollective-certname' explicitly.")
+              end
+            rescue OpenSSL::X509::CertificateError => e
+              raise Error.new(
+                message: "Cannot read Choria certificate at #{cert_path}: #{e.message}. " \
+                         "Set 'choria-mcollective-certname' explicitly or fix the certificate file."
+              )
+            end
+          end
+        end
+
+        logger.info("Choria options after defaults: #{scrub(options, options.inspect)}")
+      end
+
       # Validate option types
       options = options.to_h do |key, value|
         type = OPENBOLT_OPTIONS[key][:type]

data/lib/smart_proxy_openbolt/version.rb

@@ -1,5 +1,5 @@
 module Proxy
   module OpenBolt
-    VERSION = '1.1.0'.freeze
+    VERSION = '1.2.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_proxy_openbolt
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Overlook InfraTech
@@ -42,6 +42,7 @@ files:
 - bundler.d/openbolt.rb
 - lib/smart_proxy_openbolt.rb
 - lib/smart_proxy_openbolt/api.rb
+- lib/smart_proxy_openbolt/config/choria-client.conf
 - lib/smart_proxy_openbolt/error.rb
 - lib/smart_proxy_openbolt/executor.rb
 - lib/smart_proxy_openbolt/http_config.ru