Class: Bolt::Plugin

Inherits:
Object
  • Object
show all
Defined in:
lib/bolt/plugin.rb,
lib/bolt/plugin/task.rb,
lib/bolt/plugin/cache.rb,
lib/bolt/plugin/module.rb,
lib/bolt/plugin/prompt.rb,
lib/bolt/plugin/env_var.rb,
lib/bolt/plugin/puppetdb.rb,
lib/bolt/plugin/puppet_connect_data.rb

Defined Under Namespace

Classes: Cache, EnvVar, Module, PluginContext, PluginError, Prompt, PuppetConnectData, Puppetdb, Task

Constant Summary collapse

KNOWN_HOOKS = 
%i[
  puppet_library
  resolve_reference
  secret_encrypt
  secret_decrypt
  secret_createkeys
  validate_resolve_reference
].freeze
RUBY_PLUGINS = 
%w[task prompt env_var puppetdb puppet_connect_data].freeze
BUILTIN_PLUGINS = 
%w[task terraform pkcs7 prompt vault aws_inventory puppetdb azure_inventory
yaml env_var gcloud_inventory].freeze
DEFAULT_PLUGIN_HOOKS = 
{ 'puppet_library' => { 'plugin' => 'puppet_agent', 'stop_service' => true } }.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, pal, analytics, load_plugins: true) ⇒ Plugin

Returns a new instance of Plugin.



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/bolt/plugin.rb', line 152

def initialize(config, pal, analytics, load_plugins: true)
  @config = config
  @analytics = analytics
  @plugin_context = PluginContext.new(config, pal, self)
  @plugins = {}
  @pal = pal
  @load_plugins = load_plugins
  @unknown = Set.new
  @resolution_stack = []
  @unresolved_plugin_configs = config.plugins.dup
  # The puppetdb plugin config comes from the puppetdb section, not from
  # the plugins section
  if @unresolved_plugin_configs.key?('puppetdb')
    msg = "Configuration for the PuppetDB plugin must be in the 'puppetdb' config section, not 'plugins'"
    raise Bolt::Error.new(msg, 'bolt/plugin-error')
  end
  @unresolved_plugin_configs['puppetdb'] = config.puppetdb if config.puppetdb
  @plugin_hooks = DEFAULT_PLUGIN_HOOKS.dup
end

Instance Attribute Details

#pal ⇒ Object (readonly)

Returns the value of attribute pal.



147
148
149
 
# File 'lib/bolt/plugin.rb', line 147

def pal
  @pal
end

#plugin_context ⇒ Object (readonly)

Returns the value of attribute plugin_context.



147
148
149
 
# File 'lib/bolt/plugin.rb', line 147

def plugin_context
  @plugin_context
end

#plugin_hooks ⇒ Object

Returns the value of attribute plugin_hooks.



148
149
150
 
# File 'lib/bolt/plugin.rb', line 148

def plugin_hooks
  @plugin_hooks
end

Class Method Details

.setup(config, pal, analytics = Bolt::Analytics::NoopClient.new, **opts) ⇒ Object 



130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/bolt/plugin.rb', line 130

def self.setup(config, pal, analytics = Bolt::Analytics::NoopClient.new, **opts)
  plugins = new(config, pal, analytics, **opts)

  config.plugins.each_key do |plugin|
    plugins.by_name(plugin)
  end

  plugins.plugin_hooks.merge!(plugins.resolve_references(config.plugin_hooks))

  plugins
end

Instance Method Details

#add_module_plugin(plugin_name) ⇒ Object 



194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/bolt/plugin.rb', line 194

def add_module_plugin(plugin_name)
  opts = {
    context: @plugin_context,
    # Make sure that the plugin's config is validated _before_ the unknown-plugin
    # and loading-disabled checks. This way, we can fail early on invalid plugin
    # config instead of _after_ loading the modulepath (which can be expensive).
    config: config_for_plugin(plugin_name)
  }

  mod = modules[plugin_name]

  plugin = Bolt::Plugin::Module.load(mod, opts)
  add_plugin(plugin)
end

#add_plugin(plugin) ⇒ Object 



176
177
178
 
# File 'lib/bolt/plugin.rb', line 176

def add_plugin(plugin)
  @plugins[plugin.name] = plugin
end

#add_ruby_plugin(plugin_name) ⇒ Object 



180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/bolt/plugin.rb', line 180

def add_ruby_plugin(plugin_name)
  cls_name = Bolt::Util.snake_name_to_class_name(plugin_name)
  filename = "bolt/plugin/#{plugin_name}"
  require filename
  cls = Kernel.const_get("Bolt::Plugin::#{cls_name}")
  opts = {
    context: @plugin_context,
    config: config_for_plugin(plugin_name)
  }

  plugin = cls.new(**opts)
  add_plugin(plugin)
end

#by_name(plugin_name) ⇒ Object

Calling by_name or get_hook will load any module based plugin automatically



239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/bolt/plugin.rb', line 239

def by_name(plugin_name)
  if known_plugin?(plugin_name)
    if @plugins.include?(plugin_name)
      @plugins[plugin_name]
    elsif !@load_plugins
      raise PluginError::LoadingDisabled, plugin_name
    elsif RUBY_PLUGINS.include?(plugin_name)
      add_ruby_plugin(plugin_name)
    else
      add_module_plugin(plugin_name)
    end
  end
end

#config_for_plugin(plugin_name) ⇒ Object 



209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/bolt/plugin.rb', line 209

def config_for_plugin(plugin_name)
  return {} unless @unresolved_plugin_configs.include?(plugin_name)
  if @resolution_stack.include?(plugin_name)
    msg = "Configuration for plugin '#{plugin_name}' depends on the plugin itself"
    raise PluginError.new(msg, 'bolt/plugin-error')
  else
    @resolution_stack.push(plugin_name)
    config = resolve_references(@unresolved_plugin_configs[plugin_name])
    @unresolved_plugin_configs.delete(plugin_name)
    @resolution_stack.pop
    config
  end
end

#get_hook(plugin_name, hook) ⇒ Object

Raises:



229
230
231
232
233
234
235
236
 
# File 'lib/bolt/plugin.rb', line 229

def get_hook(plugin_name, hook)
  plugin = by_name(plugin_name)
  raise PluginError::Unknown, plugin_name unless plugin
  raise PluginError::UnsupportedHook.new(plugin_name, hook) unless plugin.hooks.include?(hook)
  @analytics.report_bundled_content("Plugin #{hook}", plugin_name)

  plugin.method(hook)
end

#known_plugin?(plugin_name) ⇒ Boolean

Returns:

  • (Boolean) 


223
224
225
226
227
 
# File 'lib/bolt/plugin.rb', line 223

def known_plugin?(plugin_name)
  @plugins.include?(plugin_name) ||
    RUBY_PLUGINS.include?(plugin_name) ||
    (modules.include?(plugin_name) && modules[plugin_name].plugin?)
end

#modules ⇒ Object 



172
173
174
 
# File 'lib/bolt/plugin.rb', line 172

def modules
  @modules ||= Bolt::Module.discover(@pal.full_modulepath, @config.project)
end

#puppetdb_client ⇒ Object 



253
254
255
 
# File 'lib/bolt/plugin.rb', line 253

def puppetdb_client
  by_name('puppetdb').puppetdb_client
end

#reference?(input) ⇒ Boolean

Checks whether a given value is a _plugin reference

Returns:

  • (Boolean) 


340
341
342
 
# File 'lib/bolt/plugin.rb', line 340

def reference?(input)
  input.is_a?(Hash) && input.key?('_plugin')
end

#resolve_references(data) ⇒ Object

Evaluate all _plugin references in a data structure. Leaves are evaluated and then their parents are evaluated with references replaced by their values. If the result of a reference contains more references, they are resolved again before continuing to ascend the tree. The final result will not contain any references.



262
263
264
265
266
267
268
269
 
# File 'lib/bolt/plugin.rb', line 262

def resolve_references(data)
  Bolt::Util.postwalk_vals(data) do |value|
    reference?(value) ? resolve_references(resolve_single_reference(value)) : value
  end
rescue SystemStackError
  raise Bolt::Error.new("Stack depth exceeded while recursively resolving references.",
                        "bolt/recursive-reference-loop")
end

#resolve_top_level_references(data) ⇒ Object

Iteratively resolves “top-level” references until the result no longer has top-level references. A top-level reference is one which is not contained within another hash. It may be either the actual top-level result or arbitrarily nested within arrays. If parameters of the reference are themselves references, they will be looked. Any remaining references nested inside the result will not be evaluated once the top-level result is not a reference. This is used to resolve the ‘targets` and `groups` keys which are allowed to be references or arrays of references, but which may return data with nested references that should be resolved lazily. The end result will either be a single hash or a flat array of hashes.



282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/bolt/plugin.rb', line 282

def resolve_top_level_references(data)
  if data.is_a?(Array)
    data.flat_map { |elem| resolve_top_level_references(elem) }
  elsif reference?(data)
    partially_resolved = data.transform_values do |v|
      resolve_references(v)
    end
    fully_resolved = resolve_single_reference(partially_resolved)
    # The top-level reference may have returned more references, so repeat the process
    resolve_top_level_references(fully_resolved)
  else
    data
  end
end