Class: Bolt::PAL
- Inherits:
-
Object
- Object
- Bolt::PAL
- Defined in:
- lib/bolt/pal.rb,
lib/bolt/pal/issues.rb,
lib/bolt/pal/yaml_plan.rb,
lib/bolt/pal/yaml_plan/step.rb,
lib/bolt/pal/yaml_plan/loader.rb,
lib/bolt/pal/yaml_plan/evaluator.rb,
lib/bolt/pal/yaml_plan/parameter.rb,
lib/bolt/pal/yaml_plan/step/eval.rb,
lib/bolt/pal/yaml_plan/step/plan.rb,
lib/bolt/pal/yaml_plan/step/task.rb,
lib/bolt/pal/yaml_plan/transpiler.rb,
lib/bolt/pal/yaml_plan/step/script.rb,
lib/bolt/pal/yaml_plan/step/upload.rb,
lib/bolt/pal/yaml_plan/step/command.rb,
lib/bolt/pal/yaml_plan/step/message.rb,
lib/bolt/pal/yaml_plan/step/download.rb,
lib/bolt/pal/yaml_plan/step/resources.rb
Defined Under Namespace
Modules: Issues Classes: PALError, YamlPlan
Class Method Summary collapse
-
.configure_logging ⇒ Object
Puppet logging is global so this is class method to avoid confusion.
- .load_puppet ⇒ Object
Instance Method Summary collapse
-
#alias_types(compiler) ⇒ Object
Create a top-level alias for TargetSpec and PlanResult so that users don’t have to namespace it with Boltlib, which is just an implementation detail.
- #convert_plan(plan_path) ⇒ Object
- #detect_project_conflict(project, environment) ⇒ Object
-
#filter_content(content, patterns) ⇒ Object
Filters content by a list of names and glob patterns specified in project configuration.
- #full_modulepath ⇒ Object
- #generate_types ⇒ Object
- #get_plan_info(plan_name) ⇒ Object
- #get_task(task_name) ⇒ Object
-
#in_bolt_compiler ⇒ Object
Runs a block in a PAL script compiler configured for Bolt.
- #in_plan_compiler(executor, inventory, pdb_client, applicator = nil) ⇒ Object
- #in_task_compiler(executor, inventory) ⇒ Object
-
#initialize(modulepath, hiera_config, resource_types, max_compiles = Etc.nprocessors, trusted_external = nil, apply_settings = {}, project = nil) ⇒ PAL
constructor
A new instance of PAL.
-
#list_modules ⇒ Hash{String => Array<Hash{Symbol => String,nil}>}
Returns a mapping of all modules available to the Bolt compiler.
- #list_plans(filter_content: false) ⇒ Object
- #list_tasks(filter_content: false) ⇒ Object
-
#parse_manifest(code, filename) ⇒ Object
Parses a snippet of Puppet manifest code and returns the AST represented in JSON.
- #parse_params(type, object_name, params) ⇒ Object
-
#register_resource_types(loaders) ⇒ Object
Register all resource types defined in $Project/.resource_types as well as the built in types registered with the runtime_3_init method.
- #run_plan(plan_name, params, executor = nil, inventory = nil, pdb_client = nil, applicator = nil) ⇒ Object
- #run_task(task_name, targets, params, executor, inventory, description = nil) ⇒ Object
- #setup ⇒ Object
- #task_signature(task_name) ⇒ Object
- #user_modulepath ⇒ Object
- #with_bolt_executor(executor, inventory, pdb_client = nil, applicator = nil, &block) ⇒ Object
-
#with_puppet_settings ⇒ Object
TODO: PUP-8553 should replace this.
Constructor Details
#initialize(modulepath, hiera_config, resource_types, max_compiles = Etc.nprocessors, trusted_external = nil, apply_settings = {}, project = nil) ⇒ PAL
Returns a new instance of PAL.
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 |
# File 'lib/bolt/pal.rb', line 47 def initialize(modulepath, hiera_config, resource_types, max_compiles = Etc.nprocessors, trusted_external = nil, apply_settings = {}, project = nil) unless modulepath.is_a?(Bolt::Config::Modulepath) msg = "Type error in PAL: modulepath must be a Bolt::Config::Modulepath" raise Bolt::Error.new(msg, "bolt/execution-error") end # Nothing works without initialized this global state. Reinitializing # is safe and in practice only happens in tests self.class.load_puppet @modulepath = modulepath @hiera_config = hiera_config @trusted_external = trusted_external @apply_settings = apply_settings @max_compiles = max_compiles @resource_types = resource_types @project = project @logger = Bolt::Logger.logger(self) unless user_modulepath.empty? @logger.debug("Loading modules from #{full_modulepath.join(File::PATH_SEPARATOR)}") end @loaded = false end |
Class Method Details
.configure_logging ⇒ Object
Puppet logging is global so this is class method to avoid confusion
81 82 83 84 85 86 87 |
# File 'lib/bolt/pal.rb', line 81 def self.configure_logging Puppet::Util::Log.destinations.clear Puppet::Util::Log.newdestination(Bolt::Logger.logger('Puppet')) # Defer all log level decisions to the Logging library by telling Puppet # to log everything Puppet.settings[:log_level] = 'debug' end |
.load_puppet ⇒ Object
89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 |
# File 'lib/bolt/pal.rb', line 89 def self.load_puppet if Bolt::Util.windows? # Windows 'fix' for openssl behaving strangely. Prevents very slow operation # of random_bytes later when establishing winrm connections from a Windows host. # See https://github.com/rails/rails/issues/25805 for background. require 'openssl' OpenSSL::Random.random_bytes(1) end begin require 'puppet_pal' rescue LoadError raise Bolt::Error.new("Puppet must be installed to execute tasks", "bolt/puppet-missing") end require 'bolt/pal/logging' require 'bolt/pal/issues' require 'bolt/pal/yaml_plan/loader' require 'bolt/pal/yaml_plan/transpiler' # Now that puppet is loaded we can include puppet mixins in data types Bolt::ResultSet.include_iterable end |
Instance Method Details
#alias_types(compiler) ⇒ Object
Create a top-level alias for TargetSpec and PlanResult so that users don’t have to namespace it with Boltlib, which is just an implementation detail. This allows them to feel like a built-in type in bolt, rather than something has been, no pun intended, “bolted on”.
128 129 130 131 |
# File 'lib/bolt/pal.rb', line 128 def alias_types(compiler) compiler.evaluate_string('type TargetSpec = Boltlib::TargetSpec') compiler.evaluate_string('type PlanResult = Boltlib::PlanResult') end |
#convert_plan(plan_path) ⇒ Object
456 457 458 459 460 |
# File 'lib/bolt/pal.rb', line 456 def convert_plan(plan_path) Puppet[:tasks] = true transpiler = YamlPlan::Transpiler.new transpiler.transpile(plan_path) end |
#detect_project_conflict(project, environment) ⇒ Object
148 149 150 151 152 153 154 155 156 157 158 159 |
# File 'lib/bolt/pal.rb', line 148 def detect_project_conflict(project, environment) return unless project && project.load_as_module? # The environment modulepath has stripped out non-existent directories, # so we don't need to check for them modules = environment.modulepath.flat_map do |path| Dir.children(path).select { |name| Puppet::Module.is_module_directory?(name, path) } end if modules.include?(project.name) Bolt::Logger.warn_once("project shadows module", "The project '#{project.name}' shadows an existing module of the same name") end end |
#filter_content(content, patterns) ⇒ Object
Filters content by a list of names and glob patterns specified in project configuration.
291 292 293 294 295 296 297 |
# File 'lib/bolt/pal.rb', line 291 def filter_content(content, patterns) return content unless content && patterns content.select do |name,| patterns.any? { |pattern| File.fnmatch?(pattern, name, File::FNM_EXTGLOB) } end end |
#full_modulepath ⇒ Object
72 73 74 |
# File 'lib/bolt/pal.rb', line 72 def full_modulepath @modulepath.full_modulepath end |
#generate_types ⇒ Object
493 494 495 496 497 498 499 500 501 |
# File 'lib/bolt/pal.rb', line 493 def generate_types require 'puppet/face/generate' in_bolt_compiler do generator = Puppet::Generate::Type inputs = generator.find_inputs(:pcore) FileUtils.mkdir_p(@resource_types) generator.generate(inputs, @resource_types, true) end end |
#get_plan_info(plan_name) ⇒ Object
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 |
# File 'lib/bolt/pal.rb', line 372 def get_plan_info(plan_name) plan_sig = in_bolt_compiler do |compiler| compiler.plan_signature(plan_name) end if plan_sig.nil? raise Bolt::Error.unknown_plan(plan_name) end # path may be a Pathname object, so make sure to stringify it mod = plan_sig.instance_variable_get(:@plan_func).loader.parent.path.to_s # If it's a Puppet language plan, use strings to extract data. The only # way to tell is to check which filename exists in the module. plan_subpath = File.join(plan_name.split('::').drop(1)) plan_subpath = 'init' if plan_subpath.empty? pp_path = File.join(mod, 'plans', "#{plan_subpath}.pp") if File.exist?(pp_path) require 'puppet-strings' require 'puppet-strings/yard' PuppetStrings::Yard.setup! YARD::Logger.instance.level = :error YARD.parse(pp_path) plan = YARD::Registry.at("puppet_plans::#{plan_name}") description = if plan.tag(:summary) plan.tag(:summary).text elsif !plan.docstring.empty? plan.docstring end defaults = plan.parameters.to_h.compact signature_params = Set.new(plan.parameters.map(&:first)) parameters = plan.(:param).each_with_object({}) do |param, params| name = param.name if signature_params.include?(name) params[name] = { 'type' => param.types.first } params[name]['sensitive'] = param.types.first =~ /\ASensitive(\[.*\])?\z/ ? true : false params[name]['default_value'] = defaults[name] if defaults.key?(name) params[name]['description'] = param.text unless param.text.empty? else @logger.warn("The documented parameter '#{name}' does not exist in plan signature") end end { 'name' => plan_name, 'description' => description, 'parameters' => parameters, 'module' => mod } # If it's a YAML plan, fall back to limited data else yaml_path = File.join(mod, 'plans', "#{plan_subpath}.yaml") plan_content = File.read(yaml_path) plan = Bolt::PAL::YamlPlan::Loader.from_string(plan_name, plan_content, yaml_path) parameters = plan.parameters.each_with_object({}) do |param, params| name = param.name type_str = case param.type_expr when Puppet::Pops::Types::PTypeReferenceType param.type_expr.type_string when nil 'Any' else param.type_expr end params[name] = { 'type' => type_str } params[name]['sensitive'] = param.type_expr.instance_of?(Puppet::Pops::Types::PSensitiveType) params[name]['default_value'] = param.value unless param.value.nil? params[name]['description'] = param.description if param.description end { 'name' => plan_name, 'description' => plan.description, 'parameters' => parameters, 'module' => mod } end end |
#get_task(task_name) ⇒ Object
350 351 352 353 354 355 356 357 358 |
# File 'lib/bolt/pal.rb', line 350 def get_task(task_name) task = task_signature(task_name) if task.nil? raise Bolt::Error.unknown_task(task_name) end Bolt::Task.from_task_signature(task) end |
#in_bolt_compiler ⇒ Object
Runs a block in a PAL script compiler configured for Bolt. Catches exceptions thrown by the block and re-raises them ensuring they are Bolt::Errors since the script compiler block will squash all exceptions.
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 |
# File 'lib/bolt/pal.rb', line 164 def in_bolt_compiler # TODO: If we always call this inside a bolt_executor we can remove this here setup r = Puppet::Pal.in_tmp_environment('bolt', modulepath: full_modulepath, facts: {}) do |pal| # Only load the project if it a) exists, b) has a name it can be loaded with Puppet.override(bolt_project: @project, yaml_plan_instantiator: Bolt::PAL::YamlPlan::Loader) do # Because this has the side effect of loading and caching the list # of modules, it must happen *after* we have overridden # bolt_project or the project will be ignored detect_project_conflict(@project, Puppet.lookup(:environments).get('bolt')) pal.with_script_compiler(set_local_facts: false) do |compiler| alias_types(compiler) register_resource_types(Puppet.lookup(:loaders)) if @resource_types begin yield compiler rescue Bolt::Error => e e rescue Puppet::DataBinding::LookupError => e if e.issue_code == :HIERA_UNDEFINED_VARIABLE = "Interpolations are not supported in lookups outside of an apply block: #{e.}" PALError.new() else PALError.from_preformatted_error(e) end rescue Puppet::PreformattedError => e if e.issue_code == :UNKNOWN_VARIABLE && %w[facts trusted server_facts settings].include?(e.arguments[:name]) = "Evaluation Error: Variable '#{e.arguments[:name]}' is not available in the current scope "\ "unless explicitly defined." details = { file: e.file, line: e.line, column: e.pos } PALError.new(, details) else PALError.from_preformatted_error(e) end rescue StandardError => e PALError.from_preformatted_error(e) end end end end # Plans may return PuppetError but nothing should be throwing them if r.is_a?(StandardError) && !r.is_a?(Bolt::PuppetError) raise r end r end |
#in_plan_compiler(executor, inventory, pdb_client, applicator = nil) ⇒ Object
237 238 239 240 241 242 243 244 245 246 247 248 |
# File 'lib/bolt/pal.rb', line 237 def in_plan_compiler(executor, inventory, pdb_client, applicator = nil) with_bolt_executor(executor, inventory, pdb_client, applicator) do # TODO: remove this call and see if anything breaks when # settings dirs don't actually exist. Plans shouldn't # actually be using them. with_puppet_settings do in_bolt_compiler do |compiler| yield compiler end end end end |
#in_task_compiler(executor, inventory) ⇒ Object
250 251 252 253 254 255 256 |
# File 'lib/bolt/pal.rb', line 250 def in_task_compiler(executor, inventory) with_bolt_executor(executor, inventory) do in_bolt_compiler do |compiler| yield compiler end end end |
#list_modules ⇒ Hash{String => Array<Hash{Symbol => String,nil}>}
Returns a mapping of all modules available to the Bolt compiler
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 |
# File 'lib/bolt/pal.rb', line 469 def list_modules internal_module_groups = { Bolt::Config::Modulepath::BOLTLIB_PATH => 'Plan Language Modules', Bolt::Config::Modulepath::MODULES_PATH => 'Packaged Modules', @project.managed_moduledir.to_s => 'Project Dependencies' } in_bolt_compiler do # NOTE: Can replace map+to_h with transform_values when Ruby 2.4 # is the minimum supported version. Puppet.lookup(:current_environment).modules_by_path.map do |path, modules| module_group = internal_module_groups[path] values = modules.map do |mod| mod_info = { name: (mod.forge_name || mod.name), version: mod.version } mod_info[:internal_module_group] = module_group unless module_group.nil? mod_info end [path, values] end.to_h end end |
#list_plans(filter_content: false) ⇒ Object
360 361 362 363 364 365 366 367 368 369 370 |
# File 'lib/bolt/pal.rb', line 360 def list_plans(filter_content: false) in_bolt_compiler do |compiler| errors = [] plans = compiler.list_plans(nil, errors).map { |plan| [plan.name] }.sort errors.each do |error| @logger.warn(error.details['original_error']) end filter_content ? filter_content(plans, @project&.plans) : plans end end |
#list_tasks(filter_content: false) ⇒ Object
299 300 301 302 303 304 305 306 307 308 309 310 |
# File 'lib/bolt/pal.rb', line 299 def list_tasks(filter_content: false) in_bolt_compiler do |compiler| tasks = compiler.list_tasks.map(&:name).sort.each_with_object([]) do |task_name, data| task_sig = compiler.task_signature(task_name) unless task_sig.task_hash['metadata']['private'] data << [task_name, task_sig.task_hash['metadata']['description']] end end filter_content ? filter_content(tasks, @project&.tasks) : tasks end end |
#parse_manifest(code, filename) ⇒ Object
Parses a snippet of Puppet manifest code and returns the AST represented in JSON.
282 283 284 285 286 287 |
# File 'lib/bolt/pal.rb', line 282 def parse_manifest(code, filename) setup Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code, filename) rescue Puppet::Error => e raise Bolt::PAL::PALError, "Failed to parse manifest: #{e}" end |
#parse_params(type, object_name, params) ⇒ Object
312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 |
# File 'lib/bolt/pal.rb', line 312 def parse_params(type, object_name, params) in_bolt_compiler do |compiler| case type when 'task' param_spec = compiler.task_signature(object_name)&.task_hash&.dig('parameters') when 'plan' plan = compiler.plan_signature(object_name) param_spec = plan.params_type.elements&.each_with_object({}) { |t, h| h[t.name] = t.value_type } if plan end param_spec ||= {} params.each_with_object({}) do |(name, str), acc| type = param_spec[name] begin parsed = JSON.parse(str, quirks_mode: true) # The type may not exist if the module is remote on orch or if a task # defines no parameters. Since we treat no parameters as Any we # should parse everything in this case acc[name] = if type && !type.instance?(parsed) str else parsed end rescue JSON::ParserError # This value may not be assignable in which case run_* will error acc[name] = str end acc end end end |
#register_resource_types(loaders) ⇒ Object
Register all resource types defined in $Project/.resource_types as well as the built in types registered with the runtime_3_init method.
135 136 137 138 139 140 141 142 143 144 145 146 |
# File 'lib/bolt/pal.rb', line 135 def register_resource_types(loaders) static_loader = loaders.static_loader static_loader.runtime_3_init if File.directory?(@resource_types) Dir.children(@resource_types).each do |resource_pp| type_name_from_file = File.basename(resource_pp, '.pp').capitalize typed_name = Puppet::Pops::Loader::TypedName.new(:type, type_name_from_file) resource_type = Puppet::Pops::Types::TypeFactory.resource(type_name_from_file) loaders.static_loader.set_entry(typed_name, resource_type) end end end |
#run_plan(plan_name, params, executor = nil, inventory = nil, pdb_client = nil, applicator = nil) ⇒ Object
510 511 512 513 514 515 516 517 |
# File 'lib/bolt/pal.rb', line 510 def run_plan(plan_name, params, executor = nil, inventory = nil, pdb_client = nil, applicator = nil) in_plan_compiler(executor, inventory, pdb_client, applicator) do |compiler| r = compiler.call_function('run_plan', plan_name, params.merge('_bolt_api_call' => true)) Bolt::PlanResult.from_pcore(r, 'success') end rescue Bolt::Error => e Bolt::PlanResult.new(e, 'failure') end |
#run_task(task_name, targets, params, executor, inventory, description = nil) ⇒ Object
503 504 505 506 507 508 |
# File 'lib/bolt/pal.rb', line 503 def run_task(task_name, targets, params, executor, inventory, description = nil) in_task_compiler(executor, inventory) do |compiler| params = params.merge('_bolt_api_call' => true, '_catch_errors' => true) compiler.call_function('run_task', task_name, targets, description, params) end end |
#setup ⇒ Object
113 114 115 116 117 118 119 120 121 122 |
# File 'lib/bolt/pal.rb', line 113 def setup unless @loaded # This is slow so don't do it until we have to Bolt::PAL.load_puppet # Make sure we don't create the puppet directories with_puppet_settings { |_| nil } @loaded = true end end |
#task_signature(task_name) ⇒ Object
344 345 346 347 348 |
# File 'lib/bolt/pal.rb', line 344 def task_signature(task_name) in_bolt_compiler do |compiler| compiler.task_signature(task_name) end end |
#user_modulepath ⇒ Object
76 77 78 |
# File 'lib/bolt/pal.rb', line 76 def user_modulepath @modulepath.user_modulepath end |
#with_bolt_executor(executor, inventory, pdb_client = nil, applicator = nil, &block) ⇒ Object
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 |
# File 'lib/bolt/pal.rb', line 213 def with_bolt_executor(executor, inventory, pdb_client = nil, applicator = nil, &block) setup opts = { bolt_executor: executor, bolt_inventory: inventory, bolt_pdb_client: pdb_client, apply_executor: applicator || Applicator.new( inventory, executor, full_modulepath, # Skip syncing built-in plugins, since we vendor some Puppet 6 # versions of "core" types, which are already present on the agent, # but may cause issues on Puppet 5 agents. user_modulepath, @project, pdb_client, @hiera_config, @max_compiles, @apply_settings ) } Puppet.override(opts, &block) end |
#with_puppet_settings ⇒ Object
TODO: PUP-8553 should replace this
259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 |
# File 'lib/bolt/pal.rb', line 259 def with_puppet_settings dir = Dir.mktmpdir('bolt') cli = [] Puppet::Settings::REQUIRED_APP_SETTINGS.each do |setting| cli << "--#{setting}" << dir end Puppet.settings.send(:clear_everything_for_tests) Puppet.initialize_settings(cli) Puppet::GettextConfig.create_default_text_domain Puppet[:trusted_external_command] = @trusted_external Puppet.settings[:hiera_config] = @hiera_config self.class.configure_logging yield ensure # Delete the tmpdir if it still exists. This check is needed to # prevent Bolt from erroring if the tmpdir is somehow deleted # before reaching this point. FileUtils.remove_entry_secure(dir) if File.exist?(dir) end |