class Puppet::Provider
A Provider
is an implementation of the actions that manage resources (of some type) on a system. This class is the base class for all implementation of a Puppet
Provider
.
Concepts:
Constants
- Confine
Common module for the Boolean confines. It currently contains just enough code to implement PUP-9336.
Attributes
@!attribute [r] doc
The (full) documentation for this provider class. The documentation for the provider class itself should be set with the DSL method {desc=}. Setting the documentation with with {doc=} has the same effect as setting it with {desc=} (only the class documentation part is set). In essence this means that there is no getter for the class documentation part (since the getter returns the full documentation when there are additional contributors). @return [String] Returns the full documentation for the provider.
@see Puppet::Utils::Docs @comment This is puzzling … a write only doc attribute??? The generated setter never seems to be
used, instead the instance variable @doc is set in the `desc` method. This seems wrong. It is instead documented as a read only attribute (to get the full documentation). Also see doc below for desc.
@!attribute [w] desc
Sets the documentation of this provider class. (The full documentation is read via the {doc} attribute). @dsl type
@return [String] The name of the provider
@todo What is this type? A reference to a Puppet::Type
? @return [Puppet::Type] the resource type (that this provider is … WHAT?)
@todo Original = _“The source parameter exists so that providers using the same
source can specify this, so reading doesn't attempt to read the same package multiple times."_ This seems to be a package type specific attribute. Is this really used?
@return [???] The source is WHAT?
@return [???] This resource is what? Is an instance of a provider attached to one particular Puppet::Resource
?
Public Class Methods
Returns the absolute path to the executable for the command referenced by the given name. @raise [Puppet::DevError] if the name does not reference an existing command. @return [String] the absolute path to the found executable for the command @see which @api public
# File lib/puppet/provider.rb 125 def self.command(name) 126 name = name.intern 127 128 command = @commands[name] if defined?(@commands) 129 command = superclass.command(name) if !command && superclass.respond_to?(:command) 130 131 unless command 132 raise Puppet::DevError, _("No command %{command} defined for provider %{provider}") % { command: name, provider: self.name } 133 end 134 135 which(command) 136 end
Confines this provider to be suitable only on hosts where the given commands are present. Also see {Puppet::Confiner#confine} for other types of confinement of a provider by use of other types of predicates.
@note It is preferred if the commands are not entered with absolute paths as this allows puppet
to search for them using the PATH variable.
@param command_specs [Hash{String => String}] Map of name to command that the provider will
be executing on the system. Each command is specified with a name and the path of the executable.
@return [void] @see optional_commands
@api public
# File lib/puppet/provider.rb 151 def self.commands(command_specs) 152 command_specs.each do |name, path| 153 has_command(name, path) 154 end 155 end
@return [Boolean] Return whether the given feature has been declared or not.
# File lib/puppet/provider.rb 250 def self.declared_feature?(name) 251 defined?(@declared_features) and @declared_features.include?(name) 252 end
@return [Boolean] Returns whether this implementation satisfies all of the default requirements or not.
Returns false if there is no matching defaultfor
@see Provider.defaultfor
# File lib/puppet/provider.rb 258 def self.default? 259 default_match ? true : false 260 end
Look through the array of defaultfor hashes and return the first match. @return [Hash<{String => Object}>] the matching hash specified by a defaultfor @see Provider.defaultfor
@api private
# File lib/puppet/provider.rb 266 def self.default_match 267 return nil if some_default_match(@notdefaults) # Blacklist means this provider cannot be a default 268 some_default_match(@defaults) 269 end
Sets a facts filter that determine which of several suitable providers should be picked by default. This selection only kicks in if there is more than one suitable provider. To filter on multiple facts the given hash may contain more than one fact name/value entry. The filter picks the provider if all the fact/value entries match the current set of facts. (In case there are still more than one provider after this filtering, the first found is picked). @param hash [Hash<{String => Object}>] hash of fact name to fact value. @return [void]
# File lib/puppet/provider.rb 319 def self.defaultfor(hash) 320 @defaults << hash 321 end
(see Puppet::Util::Execution.execpipe
)
# File lib/puppet/provider.rb 116 def self.execpipe(*args, &block) 117 Puppet::Util::Execution.execpipe(*args, &block) 118 end
(see Puppet::Util::Execution.execute
)
# File lib/puppet/provider.rb 105 def self.execute(*args) 106 Puppet::Util::Execution.execute(*args) 107 end
Compare a fact value against one or more supplied value @param [Symbol] fact a fact to query to match against one of the given values @param [Array, Regexp, String] values one or more values to compare to the
value of the given fact
@return [Boolean] whether or not the fact value matches one of the supplied
values. Given one or more Regexp instances, fact is compared via the basic pattern-matching operator.
# File lib/puppet/provider.rb 291 def self.fact_match(fact, values) 292 fact_val = Facter.value(fact).to_s.downcase 293 if fact_val.empty? 294 return false 295 else 296 values = [values] unless values.is_a?(Array) 297 values.any? do |value| 298 if value.is_a?(Regexp) 299 fact_val =~ value 300 else 301 fact_val.intern == value.to_s.downcase.intern 302 end 303 end 304 end 305 end
# File lib/puppet/provider.rb 307 def self.feature_match(value) 308 Puppet.features.send(value.to_s + "?") 309 end
Creates a convenience method for invocation of a command.
This generates a Provider
method that allows easy execution of the command. The generated method may take arguments that will be passed through to the executable as the command line arguments when it is invoked.
@example Use it like this:
has_command(:echo, "/bin/echo") def some_method echo("arg 1", "arg 2") end
@comment the . . . below is intentional to avoid the three dots to become an illegible ellipsis char. @example . . . or like this
has_command(:echo, "/bin/echo") do is_optional environment :HOME => "/var/tmp", :PWD => "/tmp" end
@param name [Symbol] The name of the command (will become the name of the generated method that executes the command) @param path [String] The path to the executable for the command @yield [ ] A block that configures the command (see {Puppet::Provider::Command}) @comment a yield [ ] produces {|| …} in the signature, do not remove the space. @note the name ´has_command´ looks odd in an API context, but makes more sense when seen in the internal
DSL context where a Provider is declaratively defined.
@api public
# File lib/puppet/provider.rb 201 def self.has_command(name, path, &block) 202 name = name.intern 203 command = CommandDefiner.define(name, path, self, &block) 204 205 @commands[name] = command.executable 206 207 # Now define the class and instance methods. 208 create_class_and_instance_method(name) do |*args| 209 return command.execute(*args) 210 end 211 end
Initializes defaults and commands (i.e. clears them). @return [void]
# File lib/puppet/provider.rb 350 def self.initvars 351 @defaults = [] 352 @notdefaults = [] 353 @commands = {} 354 end
Returns a list of system resources (entities) this provider may/can manage. This is a query mechanism that lists entities that the provider may manage on a given system. It is is directly used in query services, but is also the foundation for other services; prefetching, and purging.
As an example, a package provider lists all installed packages. (In contrast, the File provider does not list all files on the file-system as that would make execution incredibly slow). An implementation of this method should be made if it is possible to quickly (with a single system call) provide all instances.
An implementation of this method should only cache the values of properties if they are discovered as part of the process for finding existing resources. Resource properties that require additional commands (than those used to determine existence/identity) should be implemented in their respective getter method. (This is important from a performance perspective; it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed).
An implementation may return an empty list (naturally with the effect that it is not possible to query for manageable entities).
By implementing this method, it is possible to use the `resources´ resource type to specify purging of all non managed entities.
@note The returned instances are instance of some subclass of Provider
, not resources. @return [Array<Puppet::Provider>] a list of providers referencing the system entities @abstract this method must be implemented by a subclass and this super method should never be called as it raises an exception. @raise [Puppet::DevError] Error indicating that the method should have been implemented by subclass. @see prefetch
# File lib/puppet/provider.rb 383 def self.instances 384 raise Puppet::DevError, _("To support listing resources of this type the '%{provider}' provider needs to implement an 'instances' class method returning the current set of resources. We recommend porting your module to the simpler Resource API instead: https://puppet.com/search/docs?keys=resource+api") % { provider: self.name } 385 end
Creates getter- and setter- methods for each property supported by the resource type. Call this method to generate simple accessors for all properties supported by the resource type. These simple accessors lookup and sets values in the property hash. The generated methods may be overridden by more advanced implementations if something else than a straight forward getter/setter pair of methods is required. (i.e. define such overriding methods after this method has been called)
An implementor of a provider that makes use of `prefetch` and `flush` can use this method since it uses the internal `@property_hash` variable to store values. An implementation would then update the system state on a call to `flush` based on the current values in the `@property_hash`.
@return [void]
# File lib/puppet/provider.rb 400 def self.mk_resource_methods 401 [resource_type.validproperties, resource_type.parameters].flatten.each do |attr| 402 attr = attr.intern 403 next if attr == :name 404 define_method(attr) do 405 if @property_hash[attr].nil? 406 :absent 407 else 408 @property_hash[attr] 409 end 410 end 411 412 define_method(attr.to_s + "=") do |val| 413 @property_hash[attr] = val 414 end 415 end 416 end
Creates a new provider that is optionally initialized from a resource or a hash of properties. If no argument is specified, a new non specific provider is initialized. If a resource is given it is remembered for further operations. If a hash is used it becomes the internal `@property_hash` structure of the provider - this hash holds the current state property values of system entities as they are being discovered by querying or other operations (typically getters).
@todo The use of a hash as a parameter needs a better explanation; why is this done? What is the intent? @param resource [Puppet::Resource, Hash] optional resource or hash
# File lib/puppet/provider.rb 519 def initialize(resource = nil) 520 if resource.is_a?(Hash) 521 # We don't use a duplicate here, because some providers (ParsedFile, at least) 522 # use the hash here for later events. 523 @property_hash = resource 524 elsif resource 525 @resource = resource 526 @property_hash = {} 527 else 528 @property_hash = {} 529 end 530 end
# File lib/puppet/provider.rb 323 def self.notdefaultfor(hash) 324 @notdefaults << hash 325 end
Defines optional commands. Since Puppet
2.7.8 this is typically not needed as evaluation of provider suitability is lazy (when a resource is evaluated) and the absence of commands that will be present after other resources have been applied no longer needs to be specified as optional. @param [Hash{String => String}] hash Named commands that the provider will
be executing on the system. Each command is specified with a name and the path of the executable.
(@see has_command) @see commands @api public
# File lib/puppet/provider.rb 167 def self.optional_commands(hash) 168 hash.each do |name, target| 169 has_command(name, target) do 170 is_optional 171 end 172 end 173 end
# File lib/puppet/provider.rb 271 def self.some_default_match(defaultlist) 272 defaultlist.find do |default| 273 default.all? do |key, values| 274 case key 275 when :feature 276 feature_match(values) 277 else 278 fact_match(key, values) 279 end 280 end 281 end 282 end
@return [String] Returns the data source, which is the provider name if no other source has been set. @todo Unclear what “the source” is used for?
# File lib/puppet/provider.rb 439 def self.source 440 @source ||= self.name 441 end
@return [Integer] Returns a numeric specificity for this provider based on how many requirements it has
and number of _ancestors_. The higher the number the more specific the provider.
The number of requirements is based on the hash size of the matching {Provider.defaultfor}.
The ancestors is the Ruby Module::ancestors method and the number of classes returned is used to boost the score. The intent is that if two providers are equal, but one is more “derived” than the other (i.e. includes more classes), it should win because it is more specific). @note Because of how this value is
calculated there could be surprising side effects if a provider included an excessive amount of classes.
# File lib/puppet/provider.rb 337 def self.specificity 338 # This strange piece of logic attempts to figure out how many parent providers there 339 # are to increase the score. What is will actually do is count all classes that Ruby Module::ancestors 340 # returns (which can be other classes than those the parent chain) - in a way, an odd measure of the 341 # complexity of a provider). 342 match = default_match 343 length = match ? match.length : 0 344 345 (length * 100) + ancestors.select { |a| a.is_a? Class }.length 346 end
Returns true if the given attribute/parameter is supported by the provider. The check is made that the parameter is a valid parameter for the resource type, and then if all its required features (if any) are supported by the provider.
@param param [Class, Puppet::Parameter] the parameter class, or a parameter instance @return [Boolean] Returns whether this provider supports the given parameter or not. @raise [Puppet::DevError] if the given parameter is not valid for the resource type
# File lib/puppet/provider.rb 451 def self.supports_parameter?(param) 452 if param.is_a?(Class) 453 klass = param 454 else 455 klass = resource_type.attrclass(param) 456 unless klass 457 raise Puppet::DevError, _("'%{parameter_name}' is not a valid parameter for %{resource_type}") % { parameter_name: param, resource_type: resource_type.name } 458 end 459 end 460 features = klass.required_features 461 return true unless features 462 463 !!satisfies?(*features) 464 end
Private Class Methods
This method is used to generate a method for a command. @return [void] @api private
# File lib/puppet/provider.rb 424 def self.create_class_and_instance_method(name, &block) 425 unless singleton_class.method_defined?(name) 426 meta_def(name, &block) 427 end 428 429 unless method_defined?(name) 430 define_method(name) do |*args| 431 self.class.send(name, *args) 432 end 433 end 434 end
Public Instance Methods
Compares this provider against another provider. Comparison is only possible with another provider (no other class). The ordering is based on the class name of the two providers.
@return [-1,0,+1, nil] A comparison result -1, 0, +1 if this is before other, equal or after other. Returns
nil oif not comparable to other.
@see Comparable
# File lib/puppet/provider.rb 577 def <=>(other) 578 # We can only have ordering against other providers. 579 return nil unless other.is_a? Puppet::Provider 580 # Otherwise, order by the providers class name. 581 return self.class.name <=> other.class.name 582 end
Clears this provider instance to allow GC to clean up.
# File lib/puppet/provider.rb 493 def clear 494 @resource = nil 495 end
(see command)
# File lib/puppet/provider.rb 498 def command(name) 499 self.class.command(name) 500 end
Convenience methods - see class method with the same name. @return (see self.execpipe)
# File lib/puppet/provider.rb 111 def execpipe(*args, &block) 112 Puppet::Util::Execution.execpipe(*args, &block) 113 end
Convenience methods - see class method with the same name. @return (see self.execute)
# File lib/puppet/provider.rb 100 def execute(*args) 101 Puppet::Util::Execution.execute(*args) 102 end
Returns the value of a parameter value, or `:absent` if it is not defined. @param param [Puppet::Parameter] the parameter to obtain the value of @return [Object] the value of the parameter or `:absent` if not defined.
# File lib/puppet/provider.rb 506 def get(param) 507 @property_hash[param.intern] || :absent 508 end
@return [String] Returns a human readable string with information about the resource and the provider.
# File lib/puppet/provider.rb 564 def inspect 565 to_s 566 end
Returns the name of the resource this provider is operating on. @return [String] the name of the resource instance (e.g. the file path of a File). @raise [Puppet::DevError] if no resource is set, or no name defined.
# File lib/puppet/provider.rb 536 def name 537 n = @property_hash[:name] 538 if n 539 return n 540 elsif self.resource 541 resource.name 542 else 543 raise Puppet::DevError, _("No resource and no name in property hash in %{class_name} instance") % { class_name: self.class.name } 544 end 545 end
Sets the given parameters values as the current values for those parameters. Other parameters are unchanged. @param [Array<Puppet::Parameter>] params the parameters with values that should be set @return [void]
# File lib/puppet/provider.rb 552 def set(params) 553 params.each do |param, value| 554 @property_hash[param.intern] = value 555 end 556 end
@return [String] Returns a human readable string with information about the resource and the provider.
# File lib/puppet/provider.rb 559 def to_s 560 "#{@resource}(provider=#{self.class.name})" 561 end