Class: Puppet::Module

Inherits:
Object show all
Includes:
Util::Logging
Defined in:
lib/puppet/module.rb

Overview

Support for modules

Defined Under Namespace

Classes: Error, FaultyMetadata, IncompatibleModule, IncompatiblePlatform, InvalidFilePattern, InvalidName, MissingMetadata, MissingModule, UnsupportedPlatform

Constant Summary collapse

FILETYPES = 
{
  "manifests" => "manifests",
  "files" => "files",
  "templates" => "templates",
  "plugins" => "lib",
  "pluginfacts" => "facts.d",
}

Constants included from Util::Logging

Util::Logging::FILE_AND_LINE, Util::Logging::FILE_NO_LINE, Util::Logging::MM, Util::Logging::NO_FILE_LINE, Util::Logging::SUPPRESS_FILE_LINE

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Logging

#clear_deprecation_warnings, #debug, #deprecation_warning, #format_exception, #get_deprecation_offender, #log_and_raise, #log_deprecations_to_file, #log_exception, #puppet_deprecation_warning, #send_log, setup_facter_logging!, #warn_once

Constructor Details

#initialize(name, path, environment, strict_semver = true) ⇒ Module

Returns a new instance of Module.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/puppet/module.rb', line 88

def initialize(name, path, environment, strict_semver = true)
  @name = name
  @path = path
  @strict_semver = strict_semver
  @environment = environment

  assert_validity
  load_metadata

  @absolute_path_to_manifests = Puppet::FileSystem::PathPattern.absolute(manifests)

  # i18n initialization for modules
  if Puppet::GETTEXT_AVAILABLE
    begin
      initialize_i18n
    rescue Exception => e
      Puppet.warning _("GettextSetup initialization for %{module_name} failed with: %{error_message}") % { module_name: name, error_message: e.message }
    end
  else
    Puppet.warning _("GettextSetup is not available, skipping GettextSetup initialization for %{module_name}.") % { module_name: name }
  end
end

Instance Attribute Details

#author ⇒ Object

Returns the value of attribute author.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def author
  @author
end

#dependencies ⇒ Object

Returns the value of attribute dependencies.



85
86
87
 
# File 'lib/puppet/module.rb', line 85

def dependencies
  @dependencies
end

#description ⇒ Object

Returns the value of attribute description.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def description
  @description
end

#environment ⇒ Object

Returns the value of attribute environment.



82
83
84
 
# File 'lib/puppet/module.rb', line 82

def environment
  @environment
end

#forge_name ⇒ Object

Returns the value of attribute forge_name.



85
86
87
 
# File 'lib/puppet/module.rb', line 85

def forge_name
  @forge_name
end

#license ⇒ Object

Returns the value of attribute license.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def license
  @license
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



82
83
84
 
# File 'lib/puppet/module.rb', line 82

def metadata
  @metadata
end

#name ⇒ Object (readonly)

Returns the value of attribute name.



82
83
84
 
# File 'lib/puppet/module.rb', line 82

def name
  @name
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



82
83
84
 
# File 'lib/puppet/module.rb', line 82

def path
  @path
end

#project_page ⇒ Object

Returns the value of attribute project_page.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def project_page
  @project_page
end

#source ⇒ Object

Returns the value of attribute source.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def source
  @source
end

#summary ⇒ Object

Returns the value of attribute summary.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def summary
  @summary
end

#version ⇒ Object

Returns the value of attribute version.



86
87
88
 
# File 'lib/puppet/module.rb', line 86

def version
  @version
end

Class Method Details

.find(modname, environment = nil) ⇒ Object

Find and return the module that path belongs to. If path is absolute, or if there is no module whose name is the first component of path, return nil



30
31
32
33
34
35
 
# File 'lib/puppet/module.rb', line 30

def self.find(modname, environment = nil)
  return nil unless modname
  # Unless a specific environment is given, use the current environment
  env = environment ? Puppet.lookup(:environments).get!(environment) : Puppet.lookup(:current_environment)
  env.module(modname)
end

.is_module_directory?(name, path) ⇒ Boolean

Returns:



37
38
39
40
41
42
 
# File 'lib/puppet/module.rb', line 37

def self.is_module_directory?(name, path)
  # it must be a directory
  fullpath = File.join(path, name)
  return false unless Puppet::FileSystem.directory?(fullpath)
  return is_module_directory_name?(name)
end

.is_module_directory_name?(name) ⇒ Boolean

Returns:



44
45
46
47
48
 
# File 'lib/puppet/module.rb', line 44

def self.is_module_directory_name?(name)
  # it must match an installed module name according to forge validator
  return true if name =~ /^[a-z][a-z0-9_]*$/
  return false
end

.is_module_namespaced_name?(name) ⇒ Boolean

Returns:



50
51
52
53
54
 
# File 'lib/puppet/module.rb', line 50

def self.is_module_namespaced_name?(name)
  # it must match the full module name according to forge validator
  return true if name =~ /^[a-zA-Z0-9]+[-][a-z][a-z0-9_]*$/
  return false
end

.parse_range(range, strict) ⇒ 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.

API:

  • private



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/puppet/module.rb', line 57

def self.parse_range(range, strict)
  @parse_range_method ||= SemanticPuppet::VersionRange.method(:parse)
  if @parse_range_method.arity == 1
    @semver_gem_version ||= SemanticPuppet::Version.parse(SemanticPuppet::VERSION)

    # Give user a heads-up if the desired strict setting cannot be honored
    if strict
      if @semver_gem_version.major < 1
        Puppet.warn_once('strict_version_ranges', 'version_range_cannot_be_strict',
          _('VersionRanges will never be strict when using non-vendored SemanticPuppet gem, version %{version}') % { version: @semver_gem_version},
          :default, :default, :notice)
      end
    else
      if @semver_gem_version.major >= 1
        Puppet.warn_once('strict_version_ranges', 'version_range_always_strict',
          _('VersionRanges will always be strict when using non-vendored SemanticPuppet gem, version %{version}') % { version: @semver_gem_version},
          :default, :default, :notice)
      end
    end
    @parse_range_method.call(range)
  else
    @parse_range_method.call(range, strict)
  end
end

Instance Method Details

#==(other) ⇒ Object 



388
389
390
391
392
393
 
# File 'lib/puppet/module.rb', line 388

def ==(other)
  self.name == other.name &&
  self.version == other.version &&
  self.path == other.path &&
  self.environment == other.environment
end

#all_manifests ⇒ Object 



242
243
244
245
246
 
# File 'lib/puppet/module.rb', line 242

def all_manifests
  return [] unless Puppet::FileSystem.exist?(manifests)

  Dir.glob(File.join(manifests, '**', '*.pp'))
end

#dependencies_as_modules ⇒ Object 



294
295
296
297
298
299
300
301
302
303
 
# File 'lib/puppet/module.rb', line 294

def dependencies_as_modules
  dependent_modules = []
  dependencies and dependencies.each do |dep|
    author, dep_name = dep["name"].split('/')
    found_module = environment.module(dep_name)
    dependent_modules << found_module if found_module
  end

  dependent_modules
end

#has_external_facts? ⇒ Boolean

Returns:



279
280
281
 
# File 'lib/puppet/module.rb', line 279

def has_external_facts?
  File.directory?(plugin_fact_directory)
end

#has_hiera_conf? ⇒ Boolean

Returns:



262
263
264
 
# File 'lib/puppet/module.rb', line 262

def has_hiera_conf?
  hiera_conf_file.nil? ? false : Puppet::FileSystem.exist?(hiera_conf_file)
end

#has_metadata? ⇒ Boolean

Returns:



125
126
127
128
129
130
131
132
 
# File 'lib/puppet/module.rb', line 125

def has_metadata?
  begin
    load_metadata
    @metadata.is_a?(Hash) && !@metadata.empty?
  rescue Puppet::Module::MissingMetadata
    false
  end
end

#hiera_conf_file ⇒ Object 



255
256
257
258
259
260
 
# File 'lib/puppet/module.rb', line 255

def hiera_conf_file
  unless defined?(@hiera_conf_file)
     @hiera_conf_file = path.nil? ? nil : File.join(path, Puppet::Pops::Lookup::HieraConfig::CONFIG_FILE_NAME)
  end
  @hiera_conf_file
end

#initialize_i18n ⇒ Object 



399
400
401
402
403
404
405
406
407
408
409
410
411
412
 
# File 'lib/puppet/module.rb', line 399

def initialize_i18n
  module_name = @forge_name.gsub("/","-") if @forge_name
  return if module_name.nil? || i18n_initialized?(module_name)

  locales_path = File.absolute_path('locales', path)

  begin
    GettextSetup.initialize(locales_path)
    Puppet.debug "#{module_name} initialized for i18n: #{GettextSetup.translation_repositories[module_name]}"
  rescue
    config_path = File.absolute_path('config.yaml', locales_path)
    Puppet.debug "Could not find locales configuration file for #{module_name} at #{config_path}. Skipping i18n initialization."
  end
end

#license_file ⇒ Object 



172
173
174
175
176
177
 
# File 'lib/puppet/module.rb', line 172

def license_file
  return @license_file if defined?(@license_file)

  return @license_file = nil unless path
  @license_file = File.join(path, "License")
end

#load_metadata ⇒ Object 



197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/puppet/module.rb', line 197

def load_metadata
  return if instance_variable_defined?(:@metadata)

  @metadata = data = read_metadata
  return if data.empty?

  @forge_name = data['name'].gsub('-', '/') if data['name']

  [:source, :author, :version, :license, :dependencies].each do |attr|
    value = data[attr.to_s]
    raise MissingMetadata, "No #{attr} module metadata provided for #{self.name}" if value.nil?

    if attr == :dependencies
      unless value.is_a?(Array)
        raise MissingMetadata, "The value for the key dependencies in the file metadata.json of the module #{self.name} must be an array, not: '#{value}'"
      end
      value.each do |dep|
        name = dep['name']
        dep['name'] = name.tr('-', '/') unless name.nil?
        dep['version_requirement'] ||= '>= 0.0.0'
      end
    end

    send(attr.to_s + "=", value)
  end
end

#match_manifests(rest) ⇒ Object

Return the list of manifests matching the given glob pattern, defaulting to ‘init.pp’ for empty modules.



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/puppet/module.rb', line 226

def match_manifests(rest)
  if rest
    wanted_manifests = wanted_manifests_from(rest)
    searched_manifests = wanted_manifests.glob.reject { |f| FileTest.directory?(f) }
  else
    searched_manifests = []
  end

  # (#4220) Always ensure init.pp in case class is defined there.
  init_manifest = manifest("init.pp")
  if !init_manifest.nil? && !searched_manifests.include?(init_manifest)
    searched_manifests.unshift(init_manifest)
  end
  searched_manifests
end

#metadata_file ⇒ Object 



248
249
250
251
252
253
 
# File 'lib/puppet/module.rb', line 248

def metadata_file
  return @metadata_file if defined?(@metadata_file)

  return @metadata_file = nil unless path
  @metadata_file = File.join(path, "metadata.json")
end

#modulepath ⇒ Object 



266
267
268
 
# File 'lib/puppet/module.rb', line 266

def modulepath
  File.dirname(path) if path
end

#plugin_directory ⇒ Object

Find all plugin directories. This is used by the Plugins fileserving mount.



271
272
273
 
# File 'lib/puppet/module.rb', line 271

def plugin_directory
  subpath("lib")
end

#plugin_fact_directory ⇒ Object 



275
276
277
 
# File 'lib/puppet/module.rb', line 275

def plugin_fact_directory
  subpath("facts.d")
end

#puppetversion ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



112
113
114
 
# File 'lib/puppet/module.rb', line 112

def puppetversion
  nil
end

#puppetversion=(something) ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



117
118
 
# File 'lib/puppet/module.rb', line 117

def puppetversion=(something)
end

#read_metadata ⇒ Object 



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/puppet/module.rb', line 179

def read_metadata
  md_file = metadata_file
  md_file.nil? ? {} : JSON.parse(File.read(md_file, :encoding => 'utf-8'))
rescue Errno::ENOENT
  {}
rescue JSON::JSONError => e
  msg = "#{name} has an invalid and unparsable metadata.json file. The parse error: #{e.message}"
  case Puppet[:strict]
  when :off
    Puppet.debug(msg)
  when :warning
    Puppet.warning(msg)
  when :error
    raise FaultyMetadata, msg
  end
  {}
end

#required_by ⇒ Object 



305
306
307
 
# File 'lib/puppet/module.rb', line 305

def required_by
  environment.module_requirements[self.forge_name] || {}
end

#strict_semver? ⇒ Boolean

Returns:



395
396
397
 
# File 'lib/puppet/module.rb', line 395

def strict_semver?
  @strict_semver
end

#supports(name, version = nil) ⇒ Object 



283
284
285
286
 
# File 'lib/puppet/module.rb', line 283

def supports(name, version = nil)
  @supports ||= []
  @supports << [name, version]
end

#to_s ⇒ Object 



288
289
290
291
292
 
# File 'lib/puppet/module.rb', line 288

def to_s
  result = "Module #{name}"
  result += "(#{path})" if path
  result
end

#unmet_dependencies ⇒ Object

Identify and mark unmet dependencies. A dependency will be marked unmet for the following reasons:

* not installed and is thus considered missing
* installed and does not meet the version requirements for this module
* installed and doesn't use semantic versioning

Returns a list of hashes representing the details of an unmet dependency.

Example:

[
  {
    :reason => :missing,
    :name   => 'puppetlabs-mysql',
    :version_constraint => 'v0.0.1',
    :mod_details => {
      :installed_version => '0.0.1'
    }
    :parent => {
      :name    => 'puppetlabs-bacula',
      :version => 'v1.0.0'
    }
  }
]



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
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/puppet/module.rb', line 335

def unmet_dependencies
  unmet_dependencies = []
  return unmet_dependencies unless dependencies

  dependencies.each do |dependency|
    name = dependency['name']
    version_string = dependency['version_requirement'] || '>= 0.0.0'

    dep_mod = begin
      environment.module_by_forge_name(name)
    rescue
      nil
    end

    error_details = {
      :name => name,
      :version_constraint => version_string.gsub(/^(?=\d)/, "v"),
      :parent => {
        :name => self.forge_name,
        :version => self.version.gsub(/^(?=\d)/, "v")
      },
      :mod_details => {
        :installed_version => dep_mod.nil? ? nil : dep_mod.version
      }
    }

    unless dep_mod
      error_details[:reason] = :missing
      unmet_dependencies << error_details
      next
    end

    if version_string
      begin
        required_version_semver_range = self.class.parse_range(version_string, @strict_semver)
        actual_version_semver = SemanticPuppet::Version.parse(dep_mod.version)
      rescue ArgumentError
        error_details[:reason] = :non_semantic_version
        unmet_dependencies << error_details
        next
      end

      unless required_version_semver_range.include? actual_version_semver
        error_details[:reason] = :version_mismatch
        unmet_dependencies << error_details
        next
      end
    end
  end

  unmet_dependencies
end

#validate_puppet_version ⇒ Object

Deprecated.

The puppetversion module metadata field is no longer used.



121
122
123
 
# File 'lib/puppet/module.rb', line 121

def validate_puppet_version
  return
end