cem_acpt 0.10.8 → 0.10.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93cbd3354b97e498b8eba13d18b40a0294147c2e5d499ee3ce3a8c3cd809637d
-  data.tar.gz: d5879ac35af8d5fa25f4207b9efea2bc51fda8718a65a49aa38a87e7cb74e766
+  metadata.gz: 34279d516f9561d412312959bbe0180d406a234818e4311c2238983922900de5
+  data.tar.gz: cd20359cc64580a648f74964ceb6847c7c60db987cc96dca76ab30cfd0f1a877
 SHA512:
-  metadata.gz: c02e967c85cc1b00840e2263f292af3a911d4675be2509228ad822d5014d586c7282cc81c6ea071d078970b7a7dcbdcf29755ea3c4befe56a1cb7209740d6fef
-  data.tar.gz: a0d1beae7b3ebe208a5310beccf5c8ba176f82a3840affad465cc7cf9ac47d76a1ae8b0eb8fc9f7d806302333bba3cd03b43b14ab9818212cefe57bc61330e92
+  metadata.gz: cb06435dc76fe50ff0dffd557db70d0e354a80093cffed96335580601e00d56dbc43a41805fb621c67177d0cf7c97d67ff33f19e90f3e871516dbcddf0661606
+  data.tar.gz: ffb32d8da0e509d56c828b2bcd356e2e0454ec138713991636881f75ed43da8dfe44f16d8d26e5c700ed0940a645d8e084842f916e5abce4b5218919f4787f91

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cem_acpt (0.10.8)
+    cem_acpt (0.10.9)
       async-http (>= 0.60, < 0.70)
       bcrypt_pbkdf (>= 1.0, < 2.0)
       deep_merge (>= 1.2, < 2.0)

data/lib/cem_acpt/provision/terraform/linux.rb

@@ -48,6 +48,10 @@ module CemAcpt
       end
 
       # A wrapper around provision_commands that allows for extra commands to be added for a specific OS version(i.e EL 8)
+      # @param image_name [String] The name of the OS image being provisioned.
+      # @return [Array<String>] An array of shell commands to be run on the provisioned nodes to set up the necessary
+      #   environment for running the Puppet manifest, including any additional commands needed for specific OS
+      #   versions.
       def provision_commands_wrapper(image_name)
         if ['rhel-8', 'oel-8', 'alma-8', 'rocky-8'].any? { |el8| image_name.include?(el8) }
           commands = [
@@ -68,6 +72,9 @@ module CemAcpt
 
       private
 
+      # @return [String] The command to apply the Puppet manifest on the provisioned nodes, including any necessary
+      #   options for logging and debugging. This command is constructed based on the configuration settings for the
+      #   provisioner, and may include additional options for debug and verbose logging if those settings are enabled.
       def apply_command
         cmd = [
           'sudo',

data/lib/cem_acpt/provision/terraform/os_data.rb

@@ -9,6 +9,11 @@ module CemAcpt
       include CemAcpt::Logging
       extend CemAcpt::Logging
 
+      # Determines if this OsData implementation should be used for the given test name. This method extracts the OS
+      # name and version from the test name using a regular expression, and checks if they match the valid names and
+      # versions defined by the subclass. The test name is expected to be in the format `<prefix>_osname-version`, where
+      # `osname` is the name of the operating system and `version` is the version number. For example, a test name of
+      # `test_ubuntu-20` would indicate an Ubuntu OS with version 20.
       def self.use_for?(test_name)
         name_ver = test_name.match(%r{^\w+_(\w+)-(\d+).*})
         return false unless name_ver && name_ver.length == 3
@@ -20,50 +25,78 @@ module CemAcpt
         false
       end
 
+      # Returns an array of valid OS names that this class can handle. This method should be implemented by subclasses
+      # to specify which OS names they can handle. The OS name is typically extracted from the test name and used to
+      # determine which OS-specific data class to use for provisioning.
+      # @return [Array<String>] An array of valid OS names that this class can handle.
       def self.valid_names
         raise NotImplementedError
       end
 
+      # Returns an array of valid OS versions that this class can handle. This method should be implemented by
+      # subclasses to specify which OS versions they can handle. The OS version is typically extracted from the test
+      # name and used to determine which OS-specific data class to use for provisioning.
+      # @return [Array<String>] An array of valid OS versions that this class can handle.
       def self.valid_versions
         raise NotImplementedError
       end
 
       attr_accessor :base_provision_directory
 
+      # Initializes a new instance of the OsData class with the given configuration and provision data.
+      # @param config [CemAcpt::Config] The configuration object containing settings for the provisioner.
+      # @param provision_data [Hash] A hash containing all necessary information for provisioning, including node data,
+      #   credentials, and module package paths.
       def initialize(config, provision_data)
         @config = config
         @provision_data = provision_data
         @base_provision_directory = @config.get('terraform.dir')
       end
 
+      # Returns the path to the Puppet binary on the provisioned nodes. This method should be implemented by subclasses
+      # to specify the correct path to the Puppet binary for the specific OS they handle.
+      # @return [String] The path to the Puppet binary on the provisioned nodes.
       def puppet_bin_path
         raise NotImplementedError
       end
 
+      # @return [String] The filename of the Puppet manifest to be used for provisioning.
       def puppet_manifest_file
         'manifest.pp'
       end
 
+      # @return [String] The name of the remote package file that will be created on the provisioned nodes for
+      #   installing the Puppet module.
       def remote_module_package_name
         'puppet-module.tar.gz'
       end
 
+      # @return [String] The name of the OsData implementation, derived from the class name.
       def implementation_name
         self.class.to_s.downcase.split('::').last
       end
 
+      # @return [String] The path to the provision directory for this OsData implementation, which is a subdirectory of
+      #  the base provision directory named after the implementation.
       def provision_directory
         File.join(base_provision_directory, implementation_name)
       end
 
+      # @return [String] The path to the destination provision directory on the provisioned nodes. This method should be
+      #   implemented by subclasses to specify the correct path for the specific OS they handle.
       def destination_provision_directory
         raise NotImplementedError
       end
 
+      # @return [Array<String>] An array of shell commands to be run on the provisioned nodes to set up the necessary
+      #   environment for running the Puppet manifest. This method should be implemented by subclasses to specify the
+      #   correct commands for the specific OS they handle.
       def provision_commands
         raise NotImplementedError
       end
 
+      # @return [Array<String>] An array of filenames for Goss test files that should be included in the provision
+      #   directory.
       def goss_files
         Dir.glob(File.join(provision_directory, 'goss', '*.yaml')).map { |f| File.basename(f) }
       end

data/lib/cem_acpt/provision/terraform/terraform_cmd.rb

@@ -15,26 +15,43 @@ module CemAcpt
       attr_accessor :working_dir
       attr_reader :bin_path
 
+      # Initializes a new TerraformCmd instance.
+      # @param working_dir [String, nil] The working directory to run terraform commands in.
+      # @param environment [Hash] A hash of environment variables to set when running terraform commands. These will be
+      #   merged with any additional environment variables passed in when running commands.
       def initialize(working_dir = nil, environment = {})
         @working_dir = working_dir
         @environment = environment
         @bin_path = which_terraform
       end
 
+      # @return [String] A string representation of the TerraformCmd instance.
       def inspect
         to_s
       end
 
+      # @return [String] A string representation of the TerraformCmd instance, which includes the class name and object
+      #   ID.
       def to_s
         "#<#{self.class.name}:0x#{object_id.to_s(16)}>"
       end
 
+      # Sets the environment variables to be used when running terraform commands. This will replace any existing
+      # environment variables set on the instance.
+      # @param env [Hash] A hash of environment variables to set when running terraform commands. These will be merged with any additional environment variables passed in when running commands.
+      # @raise [ArgumentError] If the provided environment is not a Hash.
       def environment=(env)
         raise ArgumentError, 'environment must be a Hash' unless env.is_a?(Hash)
 
         @environment = env
       end
 
+      # Returns a hash of environment variables to be used when running terraform commands. This will merge any
+      # environment variables set on the instance with any additional environment variables passed in. Passed in
+      # environment variables will take precedence over those set on the instance, but will not persist on the instance.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance.
+      # @return [Hash] A hash of environment variables to be used when running terraform commands.
+      # @raise [ArgumentError] If the provided additional environment is not a Hash.
       def environment(env = {})
         raise ArgumentError, 'additional environment must be a Hash' unless env.is_a?(Hash)
 
@@ -44,32 +61,92 @@ module CemAcpt
         @environment.merge(env)
       end
 
-      def init(opts = {}, env = {})
-        run_cmd('init', opts, env)
-      end
-
-      def plan(opts = {}, env = {})
+      # Runs the `terraform init` command with the provided options and environment variables.
+      # @param opts [Hash] A hash of options to pass to the `terraform init` command.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to true.
+      # @return [String] The string output of the command.
+      def init(opts = {}, env = {}, raise_on_fail: true, combine_out_err: true)
+        run_cmd('init', opts, env, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
+      end
+
+      # Runs the `terraform plan` command with the provided options and environment variables. The :plan option is
+      # required and will be used as the output file for the plan.
+      # @param opts [Hash] A hash of options to pass to the `terraform plan` command. The :plan option is required and
+      #   will be used as the output file for the plan.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to true.
+      # @return [String] The string output of the command.
+      # @raise [ArgumentError] If the :plan option is not provided in the opts hash or is nil/empty.
+      def plan(opts = {}, env = {}, raise_on_fail: true, combine_out_err: true)
         plan = extract_arg!(opts, :plan, required: true)
         opts[:out] = plan
-        run_cmd('plan', opts, env)
-      end
-
-      def apply(opts = {}, env = {})
+        run_cmd('plan', opts, env, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
+      end
+
+      # Runs the `terraform apply` command with the provided options and environment variables. The :plan option is
+      # required and will be used as the input file for the apply.
+      # @param opts [Hash] A hash of options to pass to the `terraform apply` command. The :plan option is required and
+      #   will be used as the input file for the apply.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to true.
+      # @return [String] The string output of the command.
+      # @raise [ArgumentError] If the :plan option is not provided in the opts hash or is nil/empty.
+      def apply(opts = {}, env = {}, raise_on_fail: true, combine_out_err: true)
         plan = extract_arg!(opts, :plan, required: true)
-        run_cmd('apply', opts, env, suffix: plan)
-      end
-
-      def destroy(opts = {}, env = {})
-        run_cmd('destroy', opts, env)
-      end
-
-      def show(opts = {}, env = {})
-        run_cmd('show', opts, env)
-      end
-
-      def output(opts = {}, env = {})
+        run_cmd('apply', opts, env, suffix: plan, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
+      end
+
+      # Runs the `terraform destroy` command with the provided options and environment variables.
+      # @param opts [Hash] A hash of options to pass to the `terraform destroy` command.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to true.
+      # @return [String] The string output of the command.
+      def destroy(opts = {}, env = {}, raise_on_fail: true, combine_out_err: true)
+        run_cmd('destroy', opts, env, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
+      end
+
+      # Runs the `terraform show` command with the provided options and environment variables.
+      # @param opts [Hash] A hash of options to pass to the `terraform show` command.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to true.
+      # @return [String] The string output of the command.
+      def show(opts = {}, env = {}, raise_on_fail: true, combine_out_err: true)
+        run_cmd('show', opts, env, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
+      end
+
+      # Runs the `terraform output` command with the provided options and environment variables. The :name option is
+      # required and will be used as the name of the output to show.
+      # @param opts [Hash] A hash of options to pass to the `terraform output` command. The :name option is required and
+      #   will be used as the name of the output to show.
+      # @param env [Hash] A hash of additional environment variables to merge with those set on the instance when
+      #   running the command.
+      # @param raise_on_fail [Boolean] Whether to raise an error if the command fails. Defaults to true.
+      # @param combine_out_err [Boolean] Whether to combine the output and error streams into the output. If false, the
+      #   stderr stream will not be written to the output stream or returned with the output string. Defaults to false
+      #   because output command is typically used to get specific output values and we don't want error messages
+      #   mixed in with the output. Setting this to true can cause JSON parsing of the output to fail if there are error
+      #   messages included in the output string.
+      # @return [String] The string output of the command.
+      # @raise [ArgumentError] If the :name option is not provided in the opts hash or is nil/empty.
+      def output(opts = {}, env = {}, raise_on_fail: true, combine_out_err: false)
         name = extract_arg!(opts, :name, required: true)
-        run_cmd('output', opts, env, suffix: name)
+        run_cmd('output', opts, env, suffix: name, raise_on_fail: raise_on_fail, combine_out_err: combine_out_err)
       end
 
       private
@@ -81,11 +158,12 @@ module CemAcpt
         opts.delete(key)
       end
 
-      def run_cmd(cmd, opts = {}, env = {}, suffix: '')
+      def run_cmd(cmd, opts = {}, env = {}, suffix: '', raise_on_fail: true, combine_out_err: true)
         cmd = format_cmd(cmd, opts, suffix)
         env = environment(env)
         logger.debug('CemAcpt::Provision::TerraformCmd') { "Running command \"#{cmd}\" with environment \"#{env}\"" }
-        CemAcpt::Utils::Shell.run_cmd(cmd, env, output: logger)
+        CemAcpt::Utils::Shell.run_cmd(cmd, env, output: logger, raise_on_fail: raise_on_fail,
+                                      combine_out_err: combine_out_err)
       end
 
       def chdir(opts = {})

data/lib/cem_acpt/provision/terraform.rb

@@ -9,6 +9,9 @@ require_relative 'terraform/terraform_cmd'
 
 module CemAcpt
   module Provision
+    # Class to handle provisioning infrastructure using Terraform. This class abstracts away the details of running
+    # Terraform commands and managing the working directory, allowing for easy provisioning and destruction of
+    # infrastructure for testing purposes.
     class Terraform
       DEFAULT_PLAN_NAME = 'testplan.tfplan'
       DEFAULT_VARS_FILE = 'testvars.json'
@@ -16,6 +19,14 @@ module CemAcpt
 
       attr_reader :environment, :working_dir, :module_package_path, :private_key, :public_key
 
+      # Initializes a new Terraform provisioner with the given configuration and provision data. The provision data
+      # should include all necessary information about the nodes to be provisioned, as well as any necessary
+      # credentials and module package paths. The configuration should include any necessary settings for the
+      # provisioner, such as the base directory for Terraform working directories and any environment variables to
+      # set when running Terraform commands.
+      # @param config [CemAcpt::Config] The configuration object containing settings for the provisioner.
+      # @param provision_data [Hash] A hash containing all necessary information for provisioning, including node data,
+      #   credentials, and module package paths.
       def initialize(config, provision_data)
         @config = config
         @provision_data = provision_data
@@ -28,7 +39,10 @@ module CemAcpt
         @applied = false
       end
 
-      # @return [Hash] A hash of instance names and IPs
+      # Provisions infrastructure using Terraform and returns a hash of instance names and IPs.
+      # @param reuse_working_dir [Boolean] Whether to reuse the existing working directory if it exists. Defaults to
+      #   false.
+      # @return [Hash] A hash of instance names and IPs.
       def provision(reuse_working_dir: false)
         logger.info('CemAcpt::Provision::Terraform') { 'Provisioning nodes...' }
         @working_dir = new_working_dir unless reuse_working_dir
@@ -40,6 +54,10 @@ module CemAcpt
         @applied = true
       end
 
+      # Returns the output of the Terraform apply command as a hash of instance names and IPs.
+      # @return [Hash] A hash of instance names and IPs.
+      # @raise [RuntimeError] If Terraform has not been applied yet.
+      # @raise [JSON::ParserError] If there is an error parsing the Terraform output.
       def output
         raise 'Terraform has not been applied yet' unless @applied
 
@@ -51,6 +69,7 @@ module CemAcpt
         raise e
       end
 
+      # Destroys the infrastructure provisioned by Terraform and deletes the working directory.
       def destroy
         terraform_destroy(formatted_vars)
         logger.verbose('CemAcpt::Provision::Terraform') { "Deleting old working directory #{working_dir}" }
@@ -61,21 +80,32 @@ module CemAcpt
         @public_key = nil
       end
 
+      # Shows the current state of the Terraform-managed infrastructure.
       def show
         terraform_show
       end
 
       private
 
+      # @return [CemAcpt::Provision::TerraformCmd] An instance of the TerraformCmd class, which provides methods for
+      #   running Terraform commands.
       def terraform
         @terraform ||= CemAcpt::Provision::TerraformCmd.new(working_dir, environment)
       end
 
+      # Initializes the Terraform working directory by running `terraform init`. This method should be called before
+      # running any other Terraform commands to ensure that the working directory is properly set up.
       def terraform_init
         logger.info('CemAcpt::Provision::Terraform') { 'Initializing Terraform' }
         terraform.init({ chdir: working_dir, input: false, no_color: true }, { environment: environment })
       end
 
+      # Runs `terraform plan` with the given variables and plan name. This method generates a Terraform plan file that
+      # can then be applied using the `terraform_apply` method. The variables should be passed as a hash, and will be
+      # converted to JSON and saved to a file in the working directory for use by Terraform.
+      # @param vars [Hash] A hash of variables to pass to Terraform. These will be converted to JSON and saved to a file
+      #   in the working directory for use by Terraform.
+      # @param plan_name [String] The name of the Terraform plan file to create. Defaults to `testplan.tfplan`.
       def terraform_plan(vars, plan_name = DEFAULT_PLAN_NAME)
         logger.info('CemAcpt::Provision::Terraform') { "Creating Terraform plan '#{plan_name}'" }
         logger.verbose('CemAcpt::Provision::Terraform') { "Using vars:\n#{JSON.pretty_generate(vars)}" }
@@ -93,16 +123,32 @@ module CemAcpt
         )
       end
 
+      # Runs `terraform apply` with the given plan name. This method applies the Terraform plan generated by the
+      # `terraform_plan` method to provision the infrastructure. The plan name should match the name of the plan file
+      # generated by the `terraform_plan` method.
+      # @param plan_name [String] The name of the Terraform plan file to apply. Defaults to `testplan.tfplan`.
       def terraform_apply(plan_name = DEFAULT_PLAN_NAME)
         logger.info('CemAcpt::Provision::Terraform') { "Running Terraform apply with the plan #{plan_name}" }
         terraform.apply({ chdir: working_dir, input: false, no_color: true, plan: plan_name }, { environment: environment })
       end
 
+      # Runs `terraform output` to get the output of the Terraform apply command. This method can be used to retrieve
+      # any outputs defined in the Terraform configuration, such as instance names and IPs. The output will be returned
+      # as a string, which can then be parsed as JSON if the `json` parameter is set to true.
+      # @param name [String] The name of the Terraform output to retrieve. This should match the name of an output
+      #   defined in the Terraform configuration.
+      # @param json [Boolean] Whether to parse the output as JSON. If true, the output will be returned as a string and
+      #   should be parsed as JSON by the caller. If false, the raw string output from Terraform will be returned.
+      #   Defaults to true.
       def terraform_output(name, json: true)
         logger.info('CemAcpt::Provision::Terraform') { "Getting Terraform output #{name}" }
         terraform.output({ chdir: working_dir, no_color: true, json: json, name: name }, { environment: environment })
       end
 
+      # Runs `terraform destroy` to destroy the infrastructure provisioned by Terraform. This method should be called
+      # when you want to remove all resources created by Terraform.
+      # @param vars [Hash] A hash of variables to pass to Terraform. These should be the same variables that were used
+      #   to provision the infrastructure.
       def terraform_destroy(vars)
         logger.info('CemAcpt::Provision::Terraform') { 'Destroying Terraform resources...' }
         logger.verbose('CemAcpt::Provision::Terraform') { "Using vars: #{vars}" }
@@ -120,11 +166,20 @@ module CemAcpt
         )
       end
 
+      # Runs `terraform show` to display the current state of the Terraform-managed infrastructure.
       def terraform_show
         logger.info('CemAcpt::Provision::Terraform') { 'Showing Terraform state' }
         terraform.show({ chdir: working_dir, no_color: true }, { environment: environment })
       end
 
+      # Creates a new backend instance based on the OS specified in the test name. This method checks the test name
+      # against the valid names and versions defined by the Linux and Windows backend classes, and returns an instance
+      # of the appropriate class. If the test name does not match any known OS, an error is raised.
+      # @param test_name [String] The name of the test, which should include the OS name and version in the format
+      #   `<prefix>_osname-version`.
+      # @return [CemAcpt::Provision::Linux, CemAcpt::Provision::Windows] An instance of the appropriate backend class
+      #   based on the OS specified in the test name.
+      # @raise [ArgumentError] If the test name does not match any known OS or version.
       def new_backend(test_name)
         if CemAcpt::Provision::Linux.use_for?(test_name)
           logger.info('CemAcpt::Provision::Terraform') { 'Using Linux backend' }
@@ -146,6 +201,10 @@ module CemAcpt
         end
       end
 
+      # Creates a new environment hash for Terraform based on the provided configuration.
+      # @param config [CemAcpt::Config] The configuration object containing settings for the provisioner, including any
+      #   environment variables to set when running Terraform commands.
+      # @return [Hash] A hash of environment variables to set when running Terraform commands.
       def new_environment(config)
         env = (config.get('terraform.environment') || {})
         env['CLOUDSDK_PYTHON_SITEPACKAGES'] = '1' # This is needed for gcloud to use numpy
@@ -153,6 +212,9 @@ module CemAcpt
         env
       end
 
+      # Creates a new working directory for Terraform.
+      # @return [String] The path to the new working directory.
+      # @raise [StandardError] If there is an error creating the working directory.
       def new_working_dir
         logger.debug('CemAcpt::Provision::Terraform') { 'Creating new working directory' }
         base_dir = File.join(@config.get('terraform.dir'), @config.get('platform.name'))
@@ -183,6 +245,10 @@ module CemAcpt
         raise e
       end
 
+      # Validates the Terraform working directory by checking that it exists and contains a Terraform file. This method
+      # should be called before running any Terraform commands to ensure that the working directory is properly set up.
+      # @raise [RuntimeError] If the working directory does not exist or does not contain a Terraform file.
+      # @raise [StandardError] If there is another error validating the working directory.
       def validate_working_dir!
         logger.debug('CemAcpt::Provision::Terraform') { "Validating working directory #{working_dir}" }
         logger.verbose('CemAcpt::Provision::Terraform') { "Content of #{working_dir}:\n#{Dir.glob(File.join(working_dir, '*')).join("\n")}" }
@@ -194,6 +260,11 @@ module CemAcpt
         raise e
       end
 
+      # Saves the given variables to a JSON file in the Terraform working directory. This file can then be used by
+      # Terraform to load the variables when running commands.
+      # @param vars [Hash] A hash of variables to save to the file. These will be converted to JSON and saved to a file
+      #   in the working directory for use by Terraform.
+      # @raise [StandardError] If there is an error saving the variables to the file.
       def save_vars_to_file!(vars)
         logger.debug('CemAcpt::Provision::Terraform') { "Saving vars to file #{File.join(working_dir, DEFAULT_VARS_FILE)}" }
         File.write(File.join(working_dir, DEFAULT_VARS_FILE), vars.to_json)
@@ -201,6 +272,8 @@ module CemAcpt
         raise e
       end
 
+      # @return [String] The provision data for the nodes to be provisioned, formatted as a JSON string.
+      # @raise [StandardError] If there is an error formatting the provision data.
       def provision_node_data
         node_data = @provision_data[:nodes].each_with_object({}) do |node, h|
           h[node.node_name] = node.node_data.merge(
@@ -218,6 +291,9 @@ module CemAcpt
         raise e
       end
 
+      # @return [Hash] The variables to be passed to Terraform, including the provision data for the nodes and any
+      #   necessary credentials and module package paths.
+      # @raise [StandardError] If there is an error formatting the variables.
       def formatted_vars
         @provision_data[:nodes].first.platform_data.merge(
           {

data/lib/cem_acpt/utils/shell.rb

@@ -77,9 +77,10 @@ module CemAcpt
         # Logs a debug message to the output if it supports :debug, otherwise writes it to the output stream.
         # @param msg [String] The message to log as debug
         def debug(msg)
-          write("DEBUG: #{msg}\n", :stderr)
           if @output.respond_to? :debug
             @output.debug(log_title) { msg }
+          else
+            write("DEBUG: #{msg}\n", :stderr)
           end
         end
 

data/lib/cem_acpt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CemAcpt
-  VERSION = '0.10.8'
+  VERSION = '0.10.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cem_acpt
 version: !ruby/object:Gem::Version
-  version: 0.10.8
+  version: 0.10.9
 platform: ruby
 authors:
 - puppetlabs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-24 00:00:00.000000000 Z
+date: 2026-02-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http