puppet 3.4.2 → 3.4.3

data/lib/puppet/provider/package/rpm.rb

@@ -16,12 +16,10 @@ Puppet::Type.type(:package).provide :rpm, :source => :rpm, :parent => Puppet::Pr
 
   # Note: self:: is required here to keep these constants in the context of what will
   # eventually become this Puppet::Type::Package::ProviderRpm class.
-  self::RPM_DESCRIPTION_DELIMITER = ':DESC:'
   # The query format by which we identify installed packages
-  self::NEVRA_FORMAT = %Q{%{NAME} %|EPOCH?{%{EPOCH}}:{0}| %{VERSION} %{RELEASE} %{ARCH} #{self::RPM_DESCRIPTION_DELIMITER} %{SUMMARY}\\n}
-  self::NEVRA_REGEX  = %r{^(\S+) (\S+) (\S+) (\S+) (\S+)(?: #{self::RPM_DESCRIPTION_DELIMITER} ?(.*))?$}
-  self::RPM_PACKAGE_NOT_FOUND_REGEX = /package .+ is not installed/
-  self::NEVRA_FIELDS = [:name, :epoch, :version, :release, :arch, :description]
+  self::NEVRA_FORMAT = %Q{%{NAME} %|EPOCH?{%{EPOCH}}:{0}| %{VERSION} %{RELEASE} %{ARCH}\\n}
+  self::NEVRA_REGEX  = %r{^(\S+) (\S+) (\S+) (\S+) (\S+)$}
+  self::NEVRA_FIELDS = [:name, :epoch, :version, :release, :arch]
 
   commands :rpm => "rpm"
 
@@ -82,6 +80,7 @@ Puppet::Type.type(:package).provide :rpm, :source => :rpm, :parent => Puppet::Pr
     begin
       output = rpm(*cmd)
     rescue Puppet::ExecutionFailure
+      # rpm -q exits 1 if package not found
       return nil
     end
     # FIXME: We could actually be getting back multiple packages
@@ -179,21 +178,18 @@ Puppet::Type.type(:package).provide :rpm, :source => :rpm, :parent => Puppet::Pr
 
   # @param line [String] one line of rpm package query information
   # @return [Hash] of NEVRA_FIELDS strings parsed from package info
-  # if we failed to parse
-  # @note warns if failed to match a line, and returns an empty Hash.
+  # or an empty hash if we failed to parse
   # @api private
   def self.nevra_to_hash(line)
     line.strip!
     hash = {}
 
-    if self::RPM_PACKAGE_NOT_FOUND_REGEX.match(line)
-      # pass through, package was not found
-    elsif match = self::NEVRA_REGEX.match(line)
+    if match = self::NEVRA_REGEX.match(line)
       self::NEVRA_FIELDS.zip(match.captures) { |f, v| hash[f] = v }
       hash[:provider] = self.name
       hash[:ensure] = "#{hash[:version]}-#{hash[:release]}"
     else
-      Puppet.warning "Failed to match rpm line #{line}"
+      Puppet.debug("Failed to match rpm line #{line}")
     end
 
     return hash

data/lib/puppet/transaction/resource_harness.rb

@@ -1,6 +1,8 @@
 require 'puppet/resource/status'
 
 class Puppet::Transaction::ResourceHarness
+  NO_ACTION = Object.new
+
   extend Forwardable
   def_delegators :@transaction, :relationship_graph
 
@@ -74,9 +76,14 @@ class Puppet::Transaction::ResourceHarness
       cache(resource, param, context.current_values[param])
     end
 
-    managed_via_ensure = manage_via_ensure_if_possible(resource, context)
+    ensure_param = resource.parameter(:ensure)
+    if ensure_param && ensure_param.should
+      ensure_event = sync_if_needed(ensure_param, context)
+    else
+      ensure_event = NO_ACTION
+    end
 
-    if !managed_via_ensure
+    if ensure_event == NO_ACTION
       if context.resource_present?
         resource.properties.each do |param|
           sync_if_needed(param, context)
@@ -101,15 +108,6 @@ class Puppet::Transaction::ResourceHarness
     end
   end
 
-  def manage_via_ensure_if_possible(resource, context)
-    ensure_param = resource.parameter(:ensure)
-    if ensure_param && ensure_param.should
-      sync_if_needed(ensure_param, context)
-    else
-      false
-    end
-  end
-
   def sync_if_needed(param, context)
     historical_value = context.historical_values[param.name]
     current_value = context.current_values[param.name]
@@ -130,9 +128,9 @@ class Puppet::Transaction::ResourceHarness
           sync(event, param, current_value, brief_audit_message)
         end
 
-        true
+        event
       else
-        false
+        NO_ACTION
       end
     rescue => detail
       # Execution will continue on StandardErrors, just store the event
@@ -141,7 +139,7 @@ class Puppet::Transaction::ResourceHarness
       event = create_change_event(param, current_value, historical_value)
       event.status = "failure"
       event.message = "change from #{param.is_to_s(current_value)} to #{param.should_to_s(param.should)} failed: #{detail}"
-      false
+      event
     rescue Exception => detail
       # Execution will halt on Exceptions, they get raised to the application
       event = create_change_event(param, current_value, historical_value)
@@ -214,13 +212,15 @@ class Puppet::Transaction::ResourceHarness
   end
 
   # @api private
-  ResourceApplicationContext = Struct.new(:current_values,
+  ResourceApplicationContext = Struct.new(:resource,
+                                          :current_values,
                                           :historical_values,
                                           :audited_params,
                                           :synced_params,
                                           :status) do
     def self.from_resource(resource, status)
-      ResourceApplicationContext.new(resource.retrieve_resource.to_hash,
+      ResourceApplicationContext.new(resource,
+                                     resource.retrieve_resource.to_hash,
                                      Puppet::Util::Storage.cache(resource).dup,
                                      (resource[:audit] || []).map { |p| p.to_sym },
                                      [],
@@ -228,7 +228,7 @@ class Puppet::Transaction::ResourceHarness
     end
 
     def resource_present?
-      current_values[:ensure] != :absent
+      resource.present?(current_values)
     end
 
     def record(event)

data/lib/puppet/type.rb

@@ -1065,6 +1065,13 @@ class Type
     resource
   end
 
+  # Given the hash of current properties, should this resource be treated as if it
+  # currently exists on the system. May need to be overridden by types that offer up
+  # more than just :absent and :present.
+  def present?(current_values)
+    current_values[:ensure] != :absent
+  end
+
   # Returns a hash of the current properties and their values.
   # If a resource is absent, its value is the symbol `:absent`
   # @return [Hash{Puppet::Property => Object}] mapping of property instance to its value
@@ -1228,21 +1235,24 @@ class Type
   end
 
   newmetaparam(:schedule) do
-    desc "On what schedule the object should be managed.  You must create a
-      schedule object, and then reference the name of that object to use
-      that for your schedule:
-
-          schedule { 'daily':
+    desc "A schedule to govern when Puppet is allowed to manage this resource.
+      The value of this metaparameter must be the `name` of a `schedule`
+      resource. This means you must declare a schedule resource, then
+      refer to it by name; see
+      [the docs for the `schedule` type](http://docs.puppetlabs.com/references/latest/type.html#schedule)
+      for more info.
+
+          schedule { 'everyday':
             period => daily,
             range  => \"2-4\"
           }
 
           exec { \"/usr/bin/apt-get update\":
-            schedule => 'daily'
+            schedule => 'everyday'
           }
 
-      The creation of the schedule object does not need to appear in the
-      configuration before objects that use it."
+      Note that you can declare the schedule resource anywhere in your
+      manifests, as long as it ends up in the final compiled catalog."
   end
 
   newmetaparam(:audit) do
@@ -1392,12 +1402,9 @@ class Type
           }
 
       Tags are useful for things like applying a subset of a host's configuration
-      with [the `tags` setting](/references/latest/configuration.html#tags):
-
-          puppet agent --test --tags bootstrap
-
-      This way, you can easily isolate the portion of the configuration you're
-      trying to test."
+      with [the `tags` setting](/references/latest/configuration.html#tags)
+      (e.g. `puppet agent --test --tags bootstrap`) or filtering alerts with
+      [the `tagmail` report processor](http://docs.puppetlabs.com/references/latest/report.html#tagmail)."
 
     munge do |tags|
       tags = [tags] unless tags.is_a? Array
@@ -1512,134 +1519,93 @@ class Type
   # solution, but it works.
 
   newmetaparam(:require, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :NONE}) do
-    desc "References to one or more objects that this object depends on.
-      This is used purely for guaranteeing that changes to required objects
-      happen before the dependent object.  For instance:
+    desc "One or more resources that this resource depends on, expressed as
+      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      Multiple resources can be specified as an array of references. When this
+      attribute is present:
 
-          # Create the destination directory before you copy things down
-          file { \"/usr/local/scripts\":
-            ensure => directory
-          }
+      * The required resource(s) will be applied **before** this resource.
 
-          file { \"/usr/local/scripts/myscript\":
-            source  => \"puppet://server/module/myscript\",
-            mode    => 755,
-            require => File[\"/usr/local/scripts\"]
-          }
-
-      Multiple dependencies can be specified by providing a comma-separated list
-      of resources, enclosed in square brackets:
-
-          require => [ File[\"/usr/local\"], File[\"/usr/local/scripts\"] ]
-
-      Note that Puppet will autorequire everything that it can, and
-      there are hooks in place so that it's easy for resources to add new
-      ways to autorequire objects, so if you think Puppet could be
-      smarter here, let us know.
-
-      In fact, the above code was redundant --- Puppet will autorequire
-      any parent directories that are being managed; it will
-      automatically realize that the parent directory should be created
-      before the script is pulled down.
-
-      Currently, exec resources will autorequire their CWD (if it is
-      specified) plus any fully qualified paths that appear in the
-      command.   For instance, if you had an `exec` command that ran
-      the `myscript` mentioned above, the above code that pulls the
-      file down would be automatically listed as a requirement to the
-      `exec` code, so that you would always be running againts the
-      most recent version.
-      "
+      This is one of the four relationship metaparameters, along with
+      `before`, `notify`, and `subscribe`. For more context, including the
+      alternate chaining arrow (`->` and `~>`) syntax, see
+      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:subscribe, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :ALL_EVENTS, :callback => :refresh}) do
-    desc "References to one or more objects that this object depends on. This
-      metaparameter creates a dependency relationship like **require,**
-      and also causes the dependent object to be refreshed when the
-      subscribed object is changed. For instance:
-
-          class nagios {
-            file { 'nagconf':
-              path   => \"/etc/nagios/nagios.conf\"
-              source => \"puppet://server/module/nagios.conf\",
-            }
-            service { 'nagios':
-              ensure    => running,
-              subscribe => File['nagconf']
-            }
-          }
+    desc "One or more resources that this resource depends on, expressed as
+      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      Multiple resources can be specified as an array of references. When this
+      attribute is present:
 
-      Currently the `exec`, `mount` and `service` types support
-      refreshing.
-      "
+      * The subscribed resource(s) will be applied _before_ this resource.
+      * If Puppet makes changes to any of the subscribed resources, it will cause
+        this resource to _refresh._ (Refresh behavior varies by resource
+        type: services will restart, mounts will unmount and re-mount, etc. Not
+        all types can refresh.)
+
+      This is one of the four relationship metaparameters, along with
+      `before`, `require`, and `notify`. For more context, including the
+      alternate chaining arrow (`->` and `~>`) syntax, see
+      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:before, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :NONE}) do
-    desc %{References to one or more objects that depend on this object. This
-      parameter is the opposite of **require** --- it guarantees that
-      the specified object is applied later than the specifying object:
-
-          file { "/var/nagios/configuration":
-            source  => "...",
-            recurse => true,
-            before  => Exec["nagios-rebuid"]
-          }
+    desc "One or more resources that depend on this resource, expressed as
+      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      Multiple resources can be specified as an array of references. When this
+      attribute is present:
 
-          exec { "nagios-rebuild":
-            command => "/usr/bin/make",
-            cwd     => "/var/nagios/configuration"
-          }
+      * This resource will be applied _before_ the dependent resource(s).
 
-      This will make sure all of the files are up to date before the
-      make command is run.}
+      This is one of the four relationship metaparameters, along with
+      `require`, `notify`, and `subscribe`. For more context, including the
+      alternate chaining arrow (`->` and `~>`) syntax, see
+      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:notify, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :ALL_EVENTS, :callback => :refresh}) do
-    desc %{References to one or more objects that depend on this object. This
-    parameter is the opposite of **subscribe** --- it creates a
-    dependency relationship like **before,** and also causes the
-    dependent object(s) to be refreshed when this object is changed. For
-    instance:
-
-          file { "/etc/sshd_config":
-            source => "....",
-            notify => Service['sshd']
-          }
+    desc "One or more resources that depend on this resource, expressed as
+      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      Multiple resources can be specified as an array of references. When this
+      attribute is present:
 
-          service { 'sshd':
-            ensure => running
-          }
+      * This resource will be applied _before_ the notified resource(s).
+      * If Puppet makes changes to this resource, it will cause all of the
+        notified resources to _refresh._ (Refresh behavior varies by resource
+        type: services will restart, mounts will unmount and re-mount, etc. Not
+        all types can refresh.)
 
-      This will restart the sshd service if the sshd config file changes.}
+      This is one of the four relationship metaparameters, along with
+      `before`, `require`, and `subscribe`. For more context, including the
+      alternate chaining arrow (`->` and `~>`) syntax, see
+      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:stage) do
-    desc %{Which run stage a given resource should reside in.  This just creates
-      a dependency on or from the named milestone.  For instance, saying that
-      this is in the 'bootstrap' stage creates a dependency on the 'bootstrap'
-      milestone.
+    desc %{Which run stage this class should reside in.
 
-      By default, all classes get directly added to the
-      'main' stage.  You can create new stages as resources:
+      **Note: This metaparameter can only be used on classes,** and only when
+      declaring them with the resource-like syntax. It cannot be used on normal
+      resources or on classes declared with `include`.
 
-          stage { ['pre', 'post']: }
+      By default, all classes are declared in the `main` stage. To assign a class
+      to a different stage, you must:
 
-      To order stages, use standard relationships:
+      * Declare the new stage as a [`stage` resource](http://docs.puppetlabs.com/references/latest/type.html#stage).
+      * Declare an order relationship between the new stage and the `main` stage.
+      * Use the resource-like syntax to declare the class, and set the `stage`
+        metaparameter to the name of the desired stage.
 
-          stage { 'pre': before => Stage['main'] }
+      For example:
 
-      Or use the new relationship syntax:
-
-          Stage['pre'] -> Stage['main'] -> Stage['post']
-
-      Then use the new class parameters to specify a stage:
-
-          class { 'foo': stage => 'pre' }
-
-      Stages can only be set on classes, not individual resources.  This will
-      fail:
+          stage { 'pre':
+            before => Stage['main'],
+          }
 
-          file { '/foo': stage => 'pre', ensure => file }
+          class { 'apt-updates':
+            stage => 'pre',
+          }
     }
   end
 

data/lib/puppet/type/exec.rb

@@ -3,26 +3,48 @@ module Puppet
     include Puppet::Util::Execution
     require 'timeout'
 
-    @doc = "Executes external commands.  It is critical that all commands
-      executed using this mechanism can be run multiple times without
-      harm, i.e., they are *idempotent*.  One useful way to create idempotent
-      commands is to use the checks like `creates` to avoid running the
-      command unless some condition is met.
-
-      Note that you can restrict an `exec` to only run when it receives
-      events by using the `refreshonly` parameter; this is a useful way to
-      have your configuration respond to events with arbitrary commands.
-
-      Note also that if an `exec` receives an event from another resource,
-      it will get executed again (or execute the command specified in `refresh`, if there is one).
-
-      There is a strong tendency to use `exec` to do whatever work Puppet
-      can't already do; while this is obviously acceptable (and unavoidable)
-      in the short term, it is highly recommended to migrate work from `exec`
-      to native Puppet types as quickly as possible.  If you find that
-      you are doing a lot of work with `exec`, please at least notify
-      us at Puppet Labs what you are doing, and hopefully we can work with
-      you to get a native resource type for the work you are doing.
+    @doc = "Executes external commands.
+
+      Any command in an `exec` resource **must** be able to run multiple times
+      without causing harm --- that is, it must be *idempotent*. There are three
+      main ways for an exec to be idempotent:
+
+      * The command itself is already idempotent. (For example, `apt-get update`.)
+      * The exec has an `onlyif`, `unless`, or `creates` attribute, which prevents
+        Puppet from running the command unless some condition is met.
+      * The exec has `refreshonly => true`, which only allows Puppet to run the
+        command when some other resource is changed. (See the notes on refreshing
+        below.)
+
+      A caution: There's a widespread tendency to use collections of execs to
+      manage resources that aren't covered by an existing resource type. This
+      works fine for simple tasks, but once your exec pile gets complex enough
+      that you really have to think to understand what's happening, you should
+      consider developing a custom resource type instead, as it will be much
+      more predictable and maintainable.
+
+      **Refresh:** `exec` resources can respond to refresh events (via
+      `notify`, `subscribe`, or the `~>` arrow). The refresh behavior of execs
+      is non-standard, and can be affected by the `refresh` and
+      `refreshonly` attributes:
+
+      * If `refreshonly` is set to true, the exec will _only_ run when it receives an
+        event. This is the most reliable way to use refresh with execs.
+      * If the exec already would have run and receives an event, it will run its
+        command **up to two times.** (If an `onlyif`, `unless`, or `creates` condition
+        is no longer met after the first run, the second run will not occur.)
+      * If the exec already would have run, has a `refresh` command, and receives an
+        event, it will run its normal command, then run its `refresh` command
+        (as long as any `onlyif`, `unless`, or `creates` conditions are still met
+        after the normal command finishes).
+      * If the exec would **not** have run (due to an `onlyif`, `unless`, or `creates`
+        attribute) and receives an event, it still will not run.
+      * If the exec has `noop => true`, would otherwise have run, and receives
+        an event from a non-noop resource, it will run once (or run its `refresh`
+        command instead, if it has one).
+
+      In short: If there's a possibility of your exec receiving refresh events,
+      it becomes doubly important to make sure the run conditions are restricted.
 
       **Autorequires:** If Puppet is managing an exec's cwd or the executable
       file used in an exec's command, the exec resource will autorequire those