Module: Puppet::Pal

Defined in:
lib/puppet/pal/pal_impl.rb,
lib/puppet/pal/pal_api.rb,
lib/puppet/pal/compiler.rb,
lib/puppet/pal/plan_signature.rb,
lib/puppet/pal/task_signature.rb,
lib/puppet/pal/script_compiler.rb,
lib/puppet/pal/catalog_compiler.rb,
lib/puppet/pal/function_signature.rb,
lib/puppet/pal/json_catalog_encoder.rb

Overview

This is the main entry point for "Puppet As a Library" PAL. This file should be required instead of "puppet" Initially, this will require ALL of puppet - over time this will change as the monolithical "puppet" is broken up into smaller components.

Examples:

Running a snippet of Puppet Language code

require 'puppet_pal'
result = Puppet::Pal.in_tmp_environment('pal_env', modulepath: ['/tmp/testmodules']) do |pal|
  pal.evaluate_script_string('1+2+3')
end
# The result is the value 6

Calling a function

require 'puppet_pal'
result = Puppet::Pal.in_tmp_environment('pal_env', modulepath: ['/tmp/testmodules']) do |pal|
  pal.call_function('mymodule::myfunction', 10, 20)
end
# The result is what 'mymodule::myfunction' returns

Defined Under Namespace

Classes: CatalogCompiler, Compiler, FunctionSignature, JsonCatalogEncoder, PlanSignature, ScriptCompiler, TaskSignature

Constant Summary collapse

T_STRING = 
Puppet::Pops::Types::PStringType::NON_EMPTY
T_STRING_ARRAY = 
Puppet::Pops::Types::TypeFactory.array_of(T_STRING)
T_ANY_ARRAY = 
Puppet::Pops::Types::TypeFactory.array_of_any
T_BOOLEAN = 
Puppet::Pops::Types::PBooleanType::DEFAULT
T_GENERIC_TASK_HASH = 
Puppet::Pops::Types::TypeFactory.hash_kv(
  Puppet::Pops::Types::TypeFactory.pattern(/\A[a-z][a-z0-9_]*\z/), Puppet::Pops::Types::TypeFactory.data
)

Class Method Summary collapse

Class Method Details

.assert_non_empty_string(s, what, allow_nil = false) ⇒ Object 



538
539
540
 
# File 'lib/puppet/pal/pal_impl.rb', line 538

def self.assert_non_empty_string(s, what, allow_nil = false)
  assert_type(T_STRING, s, what, allow_nil)
end

.assert_type(type, value, what, allow_nil = false) ⇒ Object 



534
535
536
 
# File 'lib/puppet/pal/pal_impl.rb', line 534

def self.assert_type(type, value, what, allow_nil = false)
  Puppet::Pops::Types::TypeAsserter.assert_instance_of(nil, type, value, allow_nil) { _('Puppet Pal: %{what}') % { what: what } }
end

.create_internal_compiler(compiler_class_reference, node) ⇒ Object 



514
515
516
517
518
519
520
521
522
523
 
# File 'lib/puppet/pal/pal_impl.rb', line 514

def self.create_internal_compiler(compiler_class_reference, node)
  case compiler_class_reference
  when :script
    Puppet::Parser::ScriptCompiler.new(node.environment, node.name)
  when :catalog
    Puppet::Parser::CatalogCompiler.new(node)
  else
    raise ArgumentError, "Internal Error: Invalid compiler type requested."
  end
end

.in_environment(env_name, modulepath: nil, pre_modulepath: [], post_modulepath: [], settings_hash: {}, env_dir: nil, envpath: nil, facts: nil, variables: {}) {|context,| ... } ⇒ Object

Defines the context in which to perform puppet operations (evaluation, etc) The code to evaluate in this context is given in a block.

The name of an environment (env_name) is always given. The location of that environment on disk is then either constructed by:

  • searching a given envpath where name is a child of a directory on that path, or
  • it is the directory given in env_dir (which must exist).

The env_dir and envpath options are mutually exclusive.

Parameters:

  • env_name (String) —

    the name of an existing environment

  • modulepath (Array<String>) (defaults to: nil) —

    an array of directory paths containing Puppet modules, overrides the modulepath of an existing env. Defaults to {env_dir}/modules if env_dir is given,

  • pre_modulepath (Array<String>) (defaults to: []) —

    like modulepath, but is prepended to the modulepath

  • post_modulepath (Array<String>) (defaults to: []) —

    like modulepath, but is appended to the modulepath

  • settings_hash (Hash) (defaults to: {}) —

    a hash of settings - currently not used for anything, defaults to empty hash

  • env_dir (String) (defaults to: nil) —

    a reference to a directory being the named environment (mutually exclusive with envpath)

  • envpath (String) (defaults to: nil) —

    a path of directories in which there are environments to search for env_name (mutually exclusive with env_dir). Should be a single directory, or several directories separated with platform specific File::PATH_SEPARATOR character.

  • facts (Hash) (defaults to: nil) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)

  • variables (Hash) (defaults to: {}) —

    optional map of fully qualified variable name to value

Yield Parameters:

  • context, (Puppet::Pal) —

    a context that responds to Puppet::Pal methods

Returns:

  • (Object) —

    returns what the given block returns



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/puppet/pal/pal_impl.rb', line 253

def self.in_environment(env_name,
                        modulepath: nil,
                        pre_modulepath: [],
                        post_modulepath: [],
                        settings_hash: {},
                        env_dir:       nil,
                        envpath:       nil,
                        facts:         nil,
                        variables:     {},
                        &block)
  # TRANSLATORS terms in the assertions below are names of terms in code
  assert_non_empty_string(env_name, 'env_name')
  assert_optionally_empty_array(modulepath, 'modulepath', true)
  assert_optionally_empty_array(pre_modulepath, 'pre_modulepath', false)
  assert_optionally_empty_array(post_modulepath, 'post_modulepath', false)
  assert_mutually_exclusive(env_dir, envpath, 'env_dir', 'envpath')

  unless block_given?
    raise ArgumentError, _("A block must be given to 'in_environment'") # TRANSLATORS 'in_environment' is a name, do not translate
  end

  if env_dir
    unless Puppet::FileSystem.exist?(env_dir)
      raise ArgumentError, _("The environment directory '%{env_dir}' does not exist") % { env_dir: env_dir }
    end

    # a nil modulepath for env_dir means it should use its ./modules directory
    mid_modulepath = modulepath.nil? ? [Puppet::FileSystem.expand_path(File.join(env_dir, 'modules'))] : modulepath

    env = Puppet::Node::Environment.create(env_name, pre_modulepath + mid_modulepath + post_modulepath)
    environments = Puppet::Environments::StaticDirectory.new(env_name, env_dir, env) # The env being used is the only one...
  else
    assert_non_empty_string(envpath, 'envpath')

    # The environment is resolved against the envpath. This is setup without a basemodulepath
    # The modulepath defaults to the 'modulepath' in the found env when "Directories" is used
    #
    if envpath.is_a?(String) && envpath.include?(File::PATH_SEPARATOR)
      # potentially more than one directory to search
      env_loaders = Puppet::Environments::Directories.from_path(envpath, [])
      environments = Puppet::Environments::Combined.new(*env_loaders)
    else
      environments = Puppet::Environments::Directories.new(envpath, [])
    end
    env = environments.get(env_name)
    if env.nil?
      raise ArgumentError, _("No directory found for the environment '%{env_name}' on the path '%{envpath}'") % { env_name: env_name, envpath: envpath }
    end

    # A given modulepath should override the default
    mid_modulepath = modulepath.nil? ? env.modulepath : modulepath
    env_path = env.configuration.path_to_env
    env = env.override_with(:modulepath => pre_modulepath + mid_modulepath + post_modulepath)
    # must configure this in case logic looks up the env by name again (otherwise the looked up env does
    # not have the same effective modulepath).
    environments = Puppet::Environments::StaticDirectory.new(env_name, env_path, env) # The env being used is the only one...
  end
  in_environment_context(environments, env, facts, variables, &block)
end

.in_tmp_environment(env_name, modulepath: [], settings_hash: {}, facts: nil, variables: {}) {|context,| ... } ⇒ Object

Defines the context in which to perform puppet operations (evaluation, etc) The code to evaluate in this context is given in a block.

Parameters:

  • env_name (String) —

    a name to use for the temporary environment - this only shows up in errors

  • modulepath (Array<String>) (defaults to: []) —

    an array of directory paths containing Puppet modules, may be empty, defaults to empty array

  • settings_hash (Hash) (defaults to: {}) —

    a hash of settings - currently not used for anything, defaults to empty hash

  • facts (Hash) (defaults to: nil) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation)

  • variables (Hash) (defaults to: {}) —

    optional map of fully qualified variable name to value

Yield Parameters:

  • context, (Puppet::Pal) —

    a context that responds to Puppet::Pal methods

Returns:

  • (Object) —

    returns what the given block returns



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/puppet/pal/pal_impl.rb', line 206

def self.in_tmp_environment(env_name,
                            modulepath:    [],
                            settings_hash: {},
                            facts:         nil,
                            variables:     {},
                            &block)
  assert_non_empty_string(env_name, _("temporary environment name"))
  # TRANSLATORS: do not translate variable name string in these assertions
  assert_optionally_empty_array(modulepath, 'modulepath')

  unless block_given?
    raise ArgumentError, _("A block must be given to 'in_tmp_environment'") # TRANSLATORS 'in_tmp_environment' is a name, do not translate
  end

  env = Puppet::Node::Environment.create(env_name, modulepath)

  in_environment_context(
    Puppet::Environments::Static.new(env), # The tmp env is the only known env
    env, facts, variables, &block
  )
end

.with_catalog_compiler(configured_by_env: false, manifest_file: nil, code_string: nil, facts: {}, variables: {}, target_variables: {}, &block) {|compiler,| ... } ⇒ Object

Defines a context in which multiple operations in an env with a catalog producing compiler can be performed in a given block. The calls that takes place to PAL inside of the given block are all with the same instance of the compiler. The parameter configured_by_env makes it possible to either use the configuration in the environment, or specify manifest_file or code_string manually. If neither is given, an empty code_string is used.

Examples:

define a catalog compiler without any initial logic

pal.with_catalog_compiler do | compiler |
  # do things with compiler
end

define a catalog compiler with a code_string containing initial logic

pal.with_catalog_compiler(code_string: '$myglobal_var = 42')  do | compiler |
  # do things with compiler
end

Parameters:

  • configured_by_env (Boolean) (defaults to: false) —

    when true the environment's settings are used, otherwise the given manifest_file or code_string

  • manifest_file (String) (defaults to: nil) —

    a Puppet Language file to load and evaluate before calling the given block, mutually exclusive with code_string

  • code_string (String) (defaults to: nil) —

    a Puppet Language source string to load and evaluate before calling the given block, mutually exclusive with manifest_file

  • facts (Hash) (defaults to: {}) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation) If given at the environment level, the facts given here are merged with higher priority.

  • variables (Hash) (defaults to: {}) —

    optional map of fully qualified variable name to value. If given at the environment level, the variables given here are merged with higher priority.

  • block (Proc) —

    the block performing operations on compiler

Yield Parameters:

Returns:

  • (Object) —

    what the block returns



140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
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
 
# File 'lib/puppet/pal/pal_impl.rb', line 140

def self.with_catalog_compiler(
  configured_by_env: false,
  manifest_file:     nil,
  code_string:       nil,
  facts:             {},
  variables:         {},
  target_variables:  {},
  &block
)
  # TRANSLATORS: do not translate variable name strings in these assertions
  assert_mutually_exclusive(manifest_file, code_string, 'manifest_file', 'code_string')
  assert_non_empty_string(manifest_file, 'manifest_file', true)
  assert_non_empty_string(code_string, 'code_string', true)
  assert_type(T_BOOLEAN, configured_by_env, "configured_by_env", false)

  if configured_by_env
    unless manifest_file.nil? && code_string.nil?
      # TRANSLATORS: do not translate the variable names in this error message
      raise ArgumentError, _("manifest_file or code_string cannot be given when configured_by_env is true")
    end

    # Use the manifest setting
    manifest_file = Puppet[:manifest]
  elsif manifest_file.nil? && code_string.nil?
    # An "undef" code_string is the only way to override Puppet[:manifest] & Puppet[:code] settings since an
    # empty string is taken as Puppet[:code] not being set.
    #
    code_string = 'undef'
  end

  # We need to make sure to set these back when we're done
  previous_tasks_value = Puppet[:tasks]
  previous_code_value = Puppet[:code]

  Puppet[:tasks] = false
  # After the assertions, if code_string is non nil - it has the highest precedence
  Puppet[:code] = code_string unless code_string.nil?

  # If manifest_file is nil, the #main method will use the env configured manifest
  # to do things in the block while a Script Compiler is in effect
  main(
    manifest: manifest_file,
    facts: facts,
    variables: variables,
    target_variables: target_variables,
    internal_compiler_class: :catalog,
    set_local_facts: false,
    &block
  )
ensure
  # Clean up after ourselves
  Puppet[:tasks] = previous_tasks_value
  Puppet[:code] = previous_code_value
end

.with_script_compiler(configured_by_env: false, manifest_file: nil, code_string: nil, facts: {}, variables: {}, set_local_facts: true, &block) {|compiler,| ... } ⇒ Object

Defines a context in which multiple operations in an env with a script compiler can be performed in a given block. The calls that takes place to PAL inside of the given block are all with the same instance of the compiler. The parameter configured_by_env makes it possible to either use the configuration in the environment, or specify manifest_file or code_string manually. If neither is given, an empty code_string is used.

Examples:

define a script compiler without any initial logic

pal.with_script_compiler do | compiler |
  # do things with compiler
end

define a script compiler with a code_string containing initial logic

pal.with_script_compiler(code_string: '$myglobal_var = 42')  do | compiler |
  # do things with compiler
end

Parameters:

  • configured_by_env (Boolean) (defaults to: false) —

    when true the environment's settings are used, otherwise the given manifest_file or code_string

  • manifest_file (String) (defaults to: nil) —

    a Puppet Language file to load and evaluate before calling the given block, mutually exclusive with code_string

  • code_string (String) (defaults to: nil) —

    a Puppet Language source string to load and evaluate before calling the given block, mutually exclusive with manifest_file

  • facts (Hash) (defaults to: {}) —

    optional map of fact name to fact value - if not given will initialize the facts (which is a slow operation) If given at the environment level, the facts given here are merged with higher priority.

  • variables (Hash) (defaults to: {}) —

    optional map of fully qualified variable name to value. If given at the environment level, the variables given here are merged with higher priority.

  • set_local_facts (Boolean) (defaults to: true) —

    when true, the $facts, $server_facts, and $trusted variables are set for the scope.

  • block (Proc) —

    the block performing operations on compiler

Yield Parameters:

Returns:

  • (Object) —

    what the block returns



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/puppet/pal/pal_impl.rb', line 59

def self.with_script_compiler(
  configured_by_env: false,
  manifest_file:     nil,
  code_string:       nil,
  facts:             {},
  variables:         {},
  set_local_facts:   true,
  &block
)
  # TRANSLATORS: do not translate variable name strings in these assertions
  assert_mutually_exclusive(manifest_file, code_string, 'manifest_file', 'code_string')
  assert_non_empty_string(manifest_file, 'manifest_file', true)
  assert_non_empty_string(code_string, 'code_string', true)
  assert_type(T_BOOLEAN, configured_by_env, "configured_by_env", false)

  if configured_by_env
    unless manifest_file.nil? && code_string.nil?
      # TRANSLATORS: do not translate the variable names in this error message
      raise ArgumentError, _("manifest_file or code_string cannot be given when configured_by_env is true")
    end

    # Use the manifest setting
    manifest_file = Puppet[:manifest]
  elsif manifest_file.nil? && code_string.nil?
    # An "undef" code_string is the only way to override Puppet[:manifest] & Puppet[:code] settings since an
    # empty string is taken as Puppet[:code] not being set.
    #
    code_string = 'undef'
  end

  previous_tasks_value = Puppet[:tasks]
  previous_code_value = Puppet[:code]
  Puppet[:tasks] = true
  # After the assertions, if code_string is non nil - it has the highest precedence
  Puppet[:code] = code_string unless code_string.nil?

  # If manifest_file is nil, the #main method will use the env configured manifest
  # to do things in the block while a Script Compiler is in effect
  main(
    manifest: manifest_file,
    facts: facts,
    variables: variables,
    internal_compiler_class: :script,
    set_local_facts: set_local_facts,
    &block
  )
ensure
  Puppet[:tasks] = previous_tasks_value
  Puppet[:code] = previous_code_value
end