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: Validator Classes: Catalog, Ral, Status, StoreConfigs, Type, TypeCollection

Constant Summary collapse

EMPTY_ARRAY = 
[].freeze
EMPTY_HASH = 
{}.freeze
ATTRIBUTES = 
[:file, :line, :exported, :kind].freeze
TYPE_CLASS = 
'Class'
TYPE_NODE = 
'Node'
CLASS_STRING = 
'class'
DEFINED_TYPE_STRING = 
'defined_type'
COMPILABLE_TYPE_STRING = 
'compilable_type'
UNKNOWN_TYPE_STRING = 
'unknown'
PCORE_TYPE_KEY = 
'__ptype'
VALUE_KEY = 
'value'

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 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.

Parameters:

  • type (Symbol, String) —

    The name of the Puppet Type, as a string or symbol. The actual Type will be looked up using Node::Environment#known_resource_types. This lookup is expensive.

  • type (String) —

    The full resource name in the form of ‘“Type”`. This method of calling should only be used when `title` is `nil`.

  • type (nil) —

    If a ‘nil` is passed, the title argument must be a string of the form `“Type”`.

  • type (Class) —

    A class that inherits from ‘Puppet::Type`. This method of construction is much more efficient as it skips calls to Node::Environment#known_resource_types.

  • title (String, :main, nil) (defaults to: nil) —

    The title of the resource. If type is ‘nil`, may also be the full resource name in the form of `“Type”`.



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
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/puppet/resource.rb', line 267

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.kind = src.kind
    self.exported = src.exported
    self.virtual = src.virtual
    set_tags(src)
    self.environment = src.environment
    @rstype = src.resource_type
    @type = src.type
    @title = src.title

    src.to_hash.each do |p, v|
      case v
      when Puppet::Resource
        v = v.copy_as_resource
      when 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

    if environment.is_a?(Puppet::Node::Environment) && environment != Puppet::Node::Environment::NONE
      self.file = environment.externalize_path(attributes[:file])
    end

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

    rt = resource_type

    self.kind = self.class.to_kind(rt) unless kind
    if strict? && rt.nil?
      if 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

#catalog ⇒ Object 



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

def catalog
  @catalog
end

#exported ⇒ Object 



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

def exported
  @exported
end

#file ⇒ Object 



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

def file
  @file
end

#kind ⇒ Object 



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

def kind
  @kind
end

#line ⇒ Object 



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

def line
  @line
end

#parameters ⇒ Object (readonly) 



17
18
19
 
# File 'lib/puppet/resource.rb', line 17

def parameters
  @parameters
end

#sensitive_parameters ⇒ Array<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.

Returns:

  • (Array<Symbol>) —

    A list of parameters to be treated as sensitive



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

def sensitive_parameters
  @sensitive_parameters
end

#strict ⇒ Object 



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

def strict
  @strict
end

#title ⇒ Object (readonly) 



17
18
19
 
# File 'lib/puppet/resource.rb', line 17

def title
  @title
end

#type ⇒ Object (readonly) 



17
18
19
 
# File 'lib/puppet/resource.rb', line 17

def type
  @type
end

#validate_parameters ⇒ Object

Deprecated. 


25
26
27
 
# File 'lib/puppet/resource.rb', line 25

def validate_parameters
  @validate_parameters
end

#virtual ⇒ Object 



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

def virtual
  @virtual
end

Class Method Details

.from_data_hash(data) ⇒ Object 



46
47
48
49
50
 
# File 'lib/puppet/resource.rb', line 46

def self.from_data_hash(data)
  resource = 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

Returns:



385
386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/puppet/resource.rb', line 385

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)
  else
    result = Puppet::Type.type(type)
    unless result
      krt = environment.known_resource_types
      result = krt.definition(type)
    end
    result
  end
end

.to_kind(resource_type) ⇒ Object 



209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/puppet/resource.rb', line 209

def self.to_kind(resource_type)
  if resource_type == CLASS_STRING
    CLASS_STRING
  elsif resource_type.is_a?(Puppet::Resource::Type) && resource_type.type == :definition
    DEFINED_TYPE_STRING
  elsif resource_type.is_a?(Puppet::CompilableResourceType)
    COMPILABLE_TYPE_STRING
  else
    UNKNOWN_TYPE_STRING
  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. 



581
582
583
584
585
586
587
588
 
# File 'lib/puppet/resource.rb', line 581

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 



148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/puppet/resource.rb', line 148

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 



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

def ==(other)
  return false unless other.respond_to?(:title) and type == other.type and 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.



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

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

#[]=(param, value) ⇒ Object

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



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

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

#builtin? ⇒ Boolean

Compatibility method.

Returns:

  • (Boolean) 


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

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?

Returns:

  • (Boolean) 


204
205
206
207
 
# File 'lib/puppet/resource.rb', line 204

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

#class? ⇒ Boolean

Returns:

  • (Boolean) 


236
237
238
 
# File 'lib/puppet/resource.rb', line 236

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

#copy_as_resource ⇒ Object 



544
545
546
 
# File 'lib/puppet/resource.rb', line 544

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

#each ⇒ Object

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



222
223
224
 
# File 'lib/puppet/resource.rb', line 222

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

#environment ⇒ Object 



406
407
408
409
410
411
412
 
# File 'lib/puppet/resource.rb', line 406

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

#environment=(environment) ⇒ Object 



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

def environment=(environment)
  @environment = environment
end

#include?(parameter) ⇒ Boolean

Returns:

  • (Boolean) 


226
227
228
 
# File 'lib/puppet/resource.rb', line 226

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

#initialize_from_hash(data) ⇒ Object

Raises:

  • (ArgumentError) 


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
79
80
81
82
83
84
85
86
 
# File 'lib/puppet/resource.rb', line 52

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

#inspect ⇒ Object 



88
89
90
 
# File 'lib/puppet/resource.rb', line 88

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

#key_attributes ⇒ Object 



438
439
440
 
# File 'lib/puppet/resource.rb', line 438

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

#name ⇒ Object 



529
530
531
532
533
534
 
# File 'lib/puppet/resource.rb', line 529

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

#pos ⇒ Integer

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

Returns:

  • (Integer) —

    Instances of this class will always return ‘nil`.



558
559
560
 
# File 'lib/puppet/resource.rb', line 558

def pos
  nil
end

#prune_parameters(options = EMPTY_HASH) ⇒ Object 



562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File 'lib/puppet/resource.rb', line 562

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

#ref ⇒ Object 



366
367
368
 
# File 'lib/puppet/resource.rb', line 366

def ref
  to_s
end

#resolve ⇒ Object

Find our resource.



371
372
373
 
# File 'lib/puppet/resource.rb', line 371

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

#resource_type ⇒ 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

Returns:



378
379
380
 
# File 'lib/puppet/resource.rb', line 378

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

Parameters:



402
403
404
 
# File 'lib/puppet/resource.rb', line 402

def resource_type=(type)
  @rstype = type
end

#stage? ⇒ Boolean

Returns:

  • (Boolean) 


240
241
242
 
# File 'lib/puppet/resource.rb', line 240

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

#to_data_hash ⇒ Object

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).



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
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/puppet/resource.rb', line 99

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)
  converter = stringify ? Puppet::Pops::Serialization::ToStringifiedConverter.new : nil

  params = {}
  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_hash ⇒ Object

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.



421
422
423
 
# File 'lib/puppet/resource.rb', line 421

def to_hash
  parse_title.merge parameters
end

#to_hiera_hash ⇒ Object

Convert our resource to a hiera hash suitable for serialization.



467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/puppet/resource.rb', line 467

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!(params.sort.to_h)

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

#to_hierayaml ⇒ Object

Deprecated.

Use #to_hiera_hash instead.

Convert our resource to yaml for Hiera purposes.



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/puppet/resource.rb', line 445

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

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

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

#to_manifest ⇒ Object

Convert our resource to Puppet code.



482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
 
# File 'lib/puppet/resource.rb', line 482

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

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

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

#to_ral ⇒ Object

Convert our resource to a RAL resource instance. Creates component instances for resource types that are not of a compilable_type kind. In case the resource doesn’t exist and it’s compilable_type kind, raise an error. There are certain cases where a resource won’t be in a catalog, such as when we create a resource directly by using Puppet::Resource.new(…), so we must check its kind before deciding whether the catalog format is of an older version or not.

Raises:



515
516
517
518
519
520
521
522
523
524
525
526
527
 
# File 'lib/puppet/resource.rb', line 515

def to_ral
  if kind == COMPILABLE_TYPE_STRING
    typeklass = Puppet::Type.type(type)
  elsif catalog && catalog.catalog_format >= 2
    typeklass = Puppet::Type.type(:component)
  else
    typeklass = Puppet::Type.type(type) || Puppet::Type.type(:component)
  end

  raise(Puppet::Error, "Resource type '#{type}' was not found") unless typeklass

  typeklass.new(self)
end

#to_ref ⇒ Object 



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

def to_ref
  ref
end

#to_s ⇒ Object 



425
426
427
 
# File 'lib/puppet/resource.rb', line 425

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

#uniqueness_key ⇒ Object 



429
430
431
432
433
434
435
436
 
# File 'lib/puppet/resource.rb', line 429

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

#valid_parameter?(name) ⇒ Boolean

Returns:

  • (Boolean) 


548
549
550
 
# File 'lib/puppet/resource.rb', line 548

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

#validate_parameter(name) ⇒ Object

Raises:



552
553
554
 
# File 'lib/puppet/resource.rb', line 552

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 



164
165
166
 
# File 'lib/puppet/resource.rb', line 164

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