Class: Puppet::Resource

Inherits:
Object show all
Extended by:
Indirector
Includes:
Enumerable, Util::PsychSupport, Util::Tagging
Defined in:
lib/puppet/resource.rb,
lib/puppet/resource/status.rb

Overview

The simplest resource class. Eventually it will function as the base class for all resource-like behaviour.

Direct Known Subclasses

Parser::Resource

Defined Under Namespace

Modules: CapabilityFinder, Validator Classes: Catalog, Ral, Status, StoreConfigs, Type, TypeCollection

Constant Summary collapse

EMPTY_ARRAY =
[].freeze
EMPTY_HASH =
{}.freeze
ATTRIBUTES =
[:file, :line, :exported].freeze
TYPE_CLASS =
'Class'.freeze
TYPE_NODE =
'Node'.freeze
TYPE_SITE =
'Site'.freeze
PCORE_TYPE_KEY =
'__ptype'.freeze
VALUE_KEY =
'value'.freeze

Constants included from Indirector

Indirector::BadNameRegexp

Constants included from Util::Tagging

Util::Tagging::ValidTagRegex

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Indirector

configure_routes, indirects

Methods included from Enumerable

#uniq

Methods included from Util::PsychSupport

#encode_with, #init_with

Methods included from Util::Tagging

#merge_into, #merge_tags_from, #raw_tagged?, #set_tags, #tag, #tag_if_valid, #tagged?, #tags, #tags=, #valid_tag?

Constructor Details

#initialize(type, title = nil, attributes = EMPTY_HASH) ⇒ Resource

Construct a resource from data.

Constructs a resource instance with the given `type` and `title`. Multiple type signatures are possible for these arguments and most will result in an expensive call to Node::Environment#known_resource_types in order to resolve `String` and `Symbol` Types to actual Ruby classes.


243
244
245
246
247
248
249
250
251
252
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
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
# File 'lib/puppet/resource.rb', line 243

def initialize(type, title = nil, attributes = EMPTY_HASH)
  @parameters = {}
  @sensitive_parameters = []
  if type.is_a?(Puppet::Resource)
    # Copy constructor. Let's avoid munging, extracting, tagging, etc
    src = type
    self.file = src.file
    self.line = src.line
    self.exported = src.exported
    self.virtual = src.virtual
    self.set_tags(src)
    self.environment = src.environment
    @rstype = src.resource_type
    @type = src.type
    @title = src.title

    src.to_hash.each do |p, v|
      if v.is_a?(Puppet::Resource)
        v = v.copy_as_resource
      elsif v.is_a?(Array)
        # flatten resource references arrays
        v = v.flatten if v.flatten.find { |av| av.is_a?(Puppet::Resource) }
        v = v.collect do |av|
          av = av.copy_as_resource if av.is_a?(Puppet::Resource)
          av
        end
      end

      self[p] = v
    end
    @sensitive_parameters.replace(type.sensitive_parameters)
  else
    if type.is_a?(Hash)
      #TRANSLATORS 'Puppet::Resource.new' should not be translated
      raise ArgumentError, _("Puppet::Resource.new does not take a hash as the first argument.") + ' ' +
        _("Did you mean (%{type}, %{title}) ?") %
            { type: (type[:type] || type["type"]).inspect, title: (type[:title] || type["title"]).inspect }
    end

    # In order to avoid an expensive search of 'known_resource_types" and
    # to obey/preserve the implementation of the resource's type - if the
    # given type is a resource type implementation (one of):
    #   * a "classic" 3.x ruby plugin
    #   * a compatible implementation (e.g. loading from pcore metadata)
    #   * a resolved user defined type
    #
    # ...then, modify the parameters to the "old" (agent side compatible) way
    # of describing the type/title with string/symbols.
    #
    # TODO: Further optimizations should be possible as the "type juggling" is
    # not needed when the type implementation is known.
    #
    if type.is_a?(Puppet::CompilableResourceType) || type.is_a?(Puppet::Resource::Type)
      # set the resource type implementation
      self.resource_type = type
      # set the type name to the symbolic name
      type = type.name
    end
    @exported = false

    # Set things like environment, strictness first.
    attributes.each do |attr, value|
      next if attr == :parameters
      send(attr.to_s + "=", value)
    end

    @type, @title = self.class.type_and_title(type, title)

    rt = resource_type

    if strict? && rt.nil?
      if self.class?
        raise ArgumentError, _("Could not find declared class %{title}") % { title: title }
      else
        raise ArgumentError, _("Invalid resource type %{type}") % { type: type }
      end
    end

    params = attributes[:parameters]
    unless params.nil? || params.empty?
      extract_parameters(params)
      if rt && rt.respond_to?(:deprecate_params)
        rt.deprecate_params(title, params)
      end
    end

    tag(self.type)
    tag_if_valid(self.title)
  end
end

Instance Attribute Details

#catalogObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def catalog
  @catalog
end

#exportedObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def exported
  @exported
end

#fileObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def file
  @file
end

#lineObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def line
  @line
end

#parametersObject (readonly)


15
16
17
# File 'lib/puppet/resource.rb', line 15

def parameters
  @parameters
end

#sensitive_parametersArray<Symbol>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns A list of parameters to be treated as sensitive


20
21
22
# File 'lib/puppet/resource.rb', line 20

def sensitive_parameters
  @sensitive_parameters
end

#strictObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def strict
  @strict
end

#titleObject (readonly)


15
16
17
# File 'lib/puppet/resource.rb', line 15

def title
  @title
end

#typeObject (readonly)


15
16
17
# File 'lib/puppet/resource.rb', line 15

def type
  @type
end

#validate_parametersObject

Deprecated.

23
24
25
# File 'lib/puppet/resource.rb', line 23

def validate_parameters
  @validate_parameters
end

#virtualObject


14
15
16
# File 'lib/puppet/resource.rb', line 14

def virtual
  @virtual
end

Class Method Details

.from_data_hash(data) ⇒ Object


40
41
42
43
44
# File 'lib/puppet/resource.rb', line 40

def self.from_data_hash(data)
  resource = self.allocate
  resource.initialize_from_hash(data)
  resource
end

.resource_type(type, title, environment) ⇒ Puppet::Type, Puppet::Resource::Type

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The resource's type implementation


376
377
378
379
380
381
382
383
384
385
386
387
388
389
# File 'lib/puppet/resource.rb', line 376

def self.resource_type(type, title, environment)
  case type
  when TYPE_CLASS; environment.known_resource_types.hostclass(title == :main ? "" : title)
  when TYPE_NODE; environment.known_resource_types.node(title)
  when TYPE_SITE; environment.known_resource_types.site(nil)
  else
    result = Puppet::Type.type(type)
    if !result
      krt = environment.known_resource_types
      result = krt.definition(type) || krt.application(type)
    end
    result
  end
end

.type_and_title(type, title) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.


618
619
620
621
622
623
624
625
# File 'lib/puppet/resource.rb', line 618

def self.type_and_title(type, title)
  type, title = extract_type_and_title(type, title)
  type = munge_type_name(type)
  if type == TYPE_CLASS
    title = title == '' ? :main : munge_type_name(title)
  end
  [type, title]
end

.value_to_json_data(value) ⇒ Object


137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# File 'lib/puppet/resource.rb', line 137

def self.value_to_json_data(value)
  if value.is_a?(Array)
    value.map{|v| value_to_json_data(v) }
  elsif value.is_a?(Hash)
    result = {}
    value.each_pair { |k, v| result[value_to_json_data(k)] = value_to_json_data(v) }
    result
  elsif value.is_a?(Puppet::Resource)
    value.to_s
  elsif value.is_a?(Symbol) && value == :undef
    nil
  else
    value
  end
end

Instance Method Details

#==(other) ⇒ Object


178
179
180
181
182
183
# File 'lib/puppet/resource.rb', line 178

def ==(other)
  return false unless other.respond_to?(:title) and self.type == other.type and self.title == other.title

  return false unless to_hash == other.to_hash
  true
end

#[](param) ⇒ Object

Return a given parameter's value. Converts all passed names to lower-case symbols.


174
175
176
# File 'lib/puppet/resource.rb', line 174

def [](param)
  parameters[parameter_name(param)]
end

#[]=(param, value) ⇒ Object

Set a given parameter. Converts all passed names to lower-case symbols.


167
168
169
170
# File 'lib/puppet/resource.rb', line 167

def []=(param, value)
  validate_parameter(param) if validate_parameters
  parameters[parameter_name(param)] = value
end

#builtin?Boolean

Compatibility method.


186
187
188
189
# File 'lib/puppet/resource.rb', line 186

def builtin?
  # TODO: should be deprecated (was only used in one place in puppet codebase)
  builtin_type?
end

#builtin_type?Boolean

Is this a builtin resource type?


192
193
194
195
# File 'lib/puppet/resource.rb', line 192

def builtin_type?
  # Note - old implementation only checked if the resource_type was a Class
  resource_type.is_a?(Puppet::CompilableResourceType)
end

#class?Boolean


212
213
214
# File 'lib/puppet/resource.rb', line 212

def class?
  @is_class ||= @type == TYPE_CLASS
end

#copy_as_resourceObject


550
551
552
# File 'lib/puppet/resource.rb', line 550

def copy_as_resource
  Puppet::Resource.new(self)
end

#eachObject

Iterate over each param/value pair, as required for Enumerable.


198
199
200
# File 'lib/puppet/resource.rb', line 198

def each
  parameters.each { |p,v| yield p, v }
end

#environmentObject


398
399
400
401
402
403
404
# File 'lib/puppet/resource.rb', line 398

def environment
  @environment ||= if catalog
                     catalog.environment_instance
                   else
                     Puppet.lookup(:current_environment) { Puppet::Node::Environment::NONE }
                   end
end

#environment=(environment) ⇒ Object


406
407
408
# File 'lib/puppet/resource.rb', line 406

def environment=(environment)
  @environment = environment
end

#exportObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the value of the 'export' metaparam as an Array


361
362
363
364
# File 'lib/puppet/resource.rb', line 361

def export
  v = self[:export] || []
  v.is_a?(Array) ? v : [ v ]
end

#include?(parameter) ⇒ Boolean


202
203
204
# File 'lib/puppet/resource.rb', line 202

def include?(parameter)
  super || parameters.keys.include?( parameter_name(parameter) )
end

#initialize_from_hash(data) ⇒ Object

Raises:

  • (ArgumentError)

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
# File 'lib/puppet/resource.rb', line 46

def initialize_from_hash(data)
  type = data['type']
  raise ArgumentError, _('No resource type provided in serialized data') unless type
  title = data['title']
  raise ArgumentError, _('No resource title provided in serialized data') unless title
  @type, @title = self.class.type_and_title(type, title)

  params = data['parameters']
  if params
    params = Puppet::Pops::Serialization::FromDataConverter.convert(params)
    @parameters = {}
    params.each { |param, value| self[param] = value }
  else
    @parameters = EMPTY_HASH
  end

  sensitives = data['sensitive_parameters']
  if sensitives
    @sensitive_parameters = sensitives.map(&:to_sym)
  else
    @sensitive_parameters = EMPTY_ARRAY
  end

  tags = data['tags']
  if tags
    tag(*tags)
  end

  ATTRIBUTES.each do |a|
    value = data[a.to_s]
    send("#{a}=", value) unless value.nil?
  end
end

#inspectObject


80
81
82
# File 'lib/puppet/resource.rb', line 80

def inspect
  "#{@type}[#{@title}]#{to_hash.inspect}"
end

#is_application_component?Boolean

A resource is an application component if it exports or consumes one or more capabilities, or if it requires a capability resource


345
346
347
348
349
350
351
# File 'lib/puppet/resource.rb', line 345

def is_application_component?
  return true if ! export.empty? || self[:consume]
  # Array(self[:require]) does not work for Puppet::Resource instances
  req = self[:require] || []
  req = [ req ] unless req.is_a?(Array)
  req.any? { |r| r.is_capability? }
end

#is_capability?Boolean

A resource is a capability (instance) if its underlying type is a capability type


355
356
357
# File 'lib/puppet/resource.rb', line 355

def is_capability?
  !resource_type.nil? && resource_type.is_capability?
end

#key_attributesObject


430
431
432
# File 'lib/puppet/resource.rb', line 430

def key_attributes
  resource_type.respond_to?(:key_attributes) ? resource_type.key_attributes : [:name]
end

#nameObject


503
504
505
506
507
508
# File 'lib/puppet/resource.rb', line 503

def name
  # this is potential namespace conflict
  # between the notion of an "indirector name"
  # and a "resource name"
  [ type, title ].join('/')
end

#posInteger

This method, together with #file and #line, makes it possible for a Resource to be a 'source_pos' in a reported issue.


595
596
597
# File 'lib/puppet/resource.rb', line 595

def pos
  nil
end

#prune_parameters(options = EMPTY_HASH) ⇒ Object


599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
# File 'lib/puppet/resource.rb', line 599

def prune_parameters(options = EMPTY_HASH)
  properties = resource_type.properties.map(&:name)

  dup.collect do |attribute, value|
    if value.to_s.empty? or Array(value).empty?
      delete(attribute)
    elsif value.to_s == "absent" and attribute.to_s != "ensure"
      delete(attribute)
    end

    parameters_to_include = resource_type.parameters_to_include
    parameters_to_include += options[:parameters_to_include] || []

    delete(attribute) unless properties.include?(attribute) || parameters_to_include.include?(attribute)
  end
  self
end

#refObject


334
335
336
# File 'lib/puppet/resource.rb', line 334

def ref
  to_s
end

#resolveObject

Find our resource.


339
340
341
# File 'lib/puppet/resource.rb', line 339

def resolve
  catalog ? catalog.resource(to_s) : nil
end

#resource_typePuppet::Type, Puppet::Resource::Type

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The resource's type implementation


369
370
371
# File 'lib/puppet/resource.rb', line 369

def resource_type
  @rstype ||= self.class.resource_type(type, title, environment)
end

#resource_type=(type) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Set the resource's type implementation


394
395
396
# File 'lib/puppet/resource.rb', line 394

def resource_type=(type)
  @rstype = type
end

#set_default_parameters(scope) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Not used by Puppet


520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
# File 'lib/puppet/resource.rb', line 520

def set_default_parameters(scope)
  Puppet.deprecation_warning(_('The method Puppet::Resource.set_default_parameters is deprecated and will be removed in the next major release of Puppet.'))

  return [] unless resource_type and resource_type.respond_to?(:arguments)

  unless is_a?(Puppet::Parser::Resource)
    fail Puppet::DevError, _("Cannot evaluate default parameters for %{resource} - not a parser resource") % { resource: self }
  end

  missing_arguments.collect do |param, default|
    rtype = resource_type
    if rtype.type == :hostclass
      using_bound_value = false
      catch(:no_such_key) do
        bound_value = Puppet::Pops::Lookup.search_and_merge("#{rtype.name}::#{param}", Puppet::Pops::Lookup::Invocation.new(scope), nil)
        # Assign bound value but don't let an undef trump a default expression
        unless bound_value.nil? && !default.nil?
          self[param.to_sym] = bound_value
          using_bound_value = true
        end
      end
    end
    unless using_bound_value
      next if default.nil?
      self[param.to_sym] = default.safeevaluate(scope)
    end
    param
  end.compact
end

#stage?Boolean


216
217
218
# File 'lib/puppet/resource.rb', line 216

def stage?
  @is_stage ||= @type.to_s.casecmp("stage").zero?
end

#to_data_hashObject

Produces a Data compliant hash of the resource. The result depends on the –rich_data setting, and the context value for Puppet.lookup(:stringify_rich), that if it is `true` will use the ToStringifiedConverter to produce the value per parameter. (Note that the ToStringifiedConverter output is lossy and should not be used when producing a catalog serialization).


91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
# File 'lib/puppet/resource.rb', line 91

def to_data_hash
  data = {
    'type' => type,
    'title' => title.to_s,
    'tags' => tags.to_data_hash
  }
  ATTRIBUTES.each do |param|
    value = send(param)
    data[param.to_s] = value unless value.nil?
  end

  data['exported'] ||= false

  # To get stringified parameter values the flag :stringify_rich can be set
  # in the puppet context.
  #
  stringify = Puppet.lookup(:stringify_rich) { false }
  converter = stringify ? Puppet::Pops::Serialization::ToStringifiedConverter.new : nil

  params = {}
  self.to_hash.each_pair do |param, value|
    # Don't duplicate the title as the namevar
    unless param == namevar && value == title
      if stringify
        params[param.to_s] = converter.convert(value)
      else
        params[param.to_s] = Puppet::Resource.value_to_json_data(value)
      end
    end
  end

  unless params.empty?
    data['parameters'] = Puppet::Pops::Serialization::ToDataConverter.convert(params, {
      :rich_data => Puppet.lookup(:rich_data),
      :symbol_as_string => true,
      :local_reference => false,
      :type_by_reference => true,
      :message_prefix => ref,
      :semantic => self
    })
  end

  data['sensitive_parameters'] = sensitive_parameters.map(&:to_s) unless sensitive_parameters.empty?
  data
end

#to_hashObject

Produces a hash of attribute to value mappings where the title parsed into its components acts as the default values overridden by any parameter values explicitly given as parameters.


413
414
415
# File 'lib/puppet/resource.rb', line 413

def to_hash
  parse_title.merge parameters
end

#to_hiera_hashObject

Convert our resource to a hiera hash suitable for serialization.


457
458
459
460
461
462
463
464
465
466
467
468
469
# File 'lib/puppet/resource.rb', line 457

def to_hiera_hash
  # to_data_hash converts to safe Data types, e.g. no symbols, unicode replacement character
  h = to_data_hash

  params = h['parameters'] || {}
  value = params.delete('ensure')

  res = {}
  res['ensure'] = value if value
  res.merge!(Hash[params.sort])

  return { h['title'] => res }
end

#to_hierayamlObject

Deprecated.

Use #to_hiera_hash instead.

Convert our resource to yaml for Hiera purposes.


437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
# File 'lib/puppet/resource.rb', line 437

def to_hierayaml
  # Collect list of attributes to align => and move ensure first
  attr = parameters.keys
  attr_max = attr.inject(0) { |max,k| k.to_s.length > max ? k.to_s.length : max }

  attr.sort!
  if attr.first != :ensure  && attr.include?(:ensure)
    attr.delete(:ensure)
    attr.unshift(:ensure)
  end

  attributes = attr.collect { |k|
    v = parameters[k]
    "    %-#{attr_max}s: %s\n" % [k, Puppet::Parameter.format_value_for_display(v)]
  }.join

  "  %s:\n%s" % [self.title, attributes]
end

#to_manifestObject

Convert our resource to Puppet code.


472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
# File 'lib/puppet/resource.rb', line 472

def to_manifest
  # Collect list of attributes to align => and move ensure first
  attr = parameters.keys
  attr_max = attr.inject(0) { |max,k| k.to_s.length > max ? k.to_s.length : max }

  attr.sort!
  if attr.first != :ensure  && attr.include?(:ensure)
    attr.delete(:ensure)
    attr.unshift(:ensure)
  end

  attributes = attr.collect { |k|
    v = parameters[k]
    "  %-#{attr_max}s => %s,\n" % [k, Puppet::Parameter.format_value_for_display(v)]
  }.join

  escaped = self.title.gsub(/'/,"\\\\'")
  "%s { '%s':\n%s}" % [self.type.to_s.downcase, escaped, attributes]
end

#to_ralObject

Convert our resource to a RAL resource instance. Creates component instances for resource types that don't exist.


498
499
500
501
# File 'lib/puppet/resource.rb', line 498

def to_ral
  typeklass = Puppet::Type.type(self.type) || Puppet::Type.type(:component)
  typeklass.new(self)
end

#to_refObject


492
493
494
# File 'lib/puppet/resource.rb', line 492

def to_ref
  ref
end

#to_sObject


417
418
419
# File 'lib/puppet/resource.rb', line 417

def to_s
  "#{type}[#{title}]"
end

#uniqueness_keyObject


421
422
423
424
425
426
427
428
# File 'lib/puppet/resource.rb', line 421

def uniqueness_key
  # Temporary kludge to deal with inconsistent use patterns; ensure we don't return nil for namevar/:name
  h = self.to_hash
  name = h[namevar] || h[:name] || self.name
  h[namevar] ||= name
  h[:name]   ||= name
  h.values_at(*key_attributes.sort_by { |k| k.to_s })
end

#valid_parameter?(name) ⇒ Boolean


554
555
556
# File 'lib/puppet/resource.rb', line 554

def valid_parameter?(name)
  resource_type.valid_parameter?(name)
end

#validate_completeObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Not used by Puppet

Verify that all required arguments are either present or have been provided with defaults. Must be called after 'set_default_parameters'. We can't join the methods because Type#set_parameters needs specifically ordered behavior.


565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
# File 'lib/puppet/resource.rb', line 565

def validate_complete
  Puppet.deprecation_warning(_('The method Puppet::Resource.validate_complete is deprecated and will be removed in the next major release of Puppet.'))

  return unless resource_type and resource_type.respond_to?(:arguments)

  resource_type.arguments.each do |param, default|
    param = param.to_sym
    fail Puppet::ParseError, _("Must pass %{param} to %{resource}") % { param: param, resource: self } unless parameters.include?(param)
  end

  # Perform optional type checking
  arg_types = resource_type.argument_types
  # Parameters is a map from name, to parameter, and the parameter again has name and value
  parameters.each do |name, value|
    t = arg_types[name.to_s] # untyped, and parameters are symbols here (aargh, strings in the type)
    next unless t
    unless Puppet::Pops::Types::TypeCalculator.instance?(t, value.value)
      inferred_type = Puppet::Pops::Types::TypeCalculator.infer_set(value.value)
      actual = inferred_type.generalize()
      fail Puppet::ParseError, _("Expected parameter '%{name}' of '%{value0}' to have type %{value1}, got %{value2}") % { name: name, value0: self, value1: t.to_s, value2: actual.to_s }
    end
  end
end

#validate_parameter(name) ⇒ Object

Raises:


589
590
591
# File 'lib/puppet/resource.rb', line 589

def validate_parameter(name)
  raise Puppet::ParseError.new(_("no parameter named '%{name}'") % { name: name }, file, line) unless valid_parameter?(name)
end

#yaml_property_munge(x) ⇒ Object


153
154
155
# File 'lib/puppet/resource.rb', line 153

def yaml_property_munge(x)
  self.value.to_json_data(x)
end