puppet 6.18.0-universal-darwin → 6.21.1-universal-darwin

data/lib/puppet/defaults.rb

@@ -77,7 +77,8 @@ module Puppet
           the "facter-ng" gem). This is not necessary if Facter 3.x or later is installed.
           This setting is still experimental.',
         :hook    => proc do |value|
-          if value
+          value = munge(value)
+          if value && Puppet::Util::Package.versioncmp(Facter.value('facterversion'), '4.0.0') < 0
             begin
               original_facter = Object.const_get(:Facter)
               Object.send(:remove_const, :Facter)
@@ -374,7 +375,7 @@ module Puppet
           from the parent process.
 
           This setting can only be set in the `[main]` section of puppet.conf; it cannot
-          be set in `[master]`, `[agent]`, or an environment config section.",
+          be set in `[server]`, `[agent]`, or an environment config section.",
         :call_hook => :on_define_and_write,
         :hook             => proc do |value|
           Puppet::Util.set_env('PATH', '') if Puppet::Util.get_env('PATH').nil?
@@ -562,7 +563,7 @@ module Puppet
         config = File.expand_path(File.join(settings[:confdir], 'hiera.yaml')) if config.nil?
         config
       end,
-      :desc    => "The hiera configuration file. Puppet only reads this file on startup, so you must restart the puppet master every time you edit it.",
+      :desc    => "The hiera configuration file. Puppet only reads this file on startup, so you must restart the puppet server every time you edit it.",
       :type    => :file,
     },
     :binder_config => {
@@ -632,7 +633,7 @@ module Puppet
     :http_proxy_password =>{
       :default    => "none",
       :hook       => proc do |value|
-        if settings[:http_proxy_password] =~ /[@!# \/]/
+        if value =~ /[@!# \/]/
           raise "Passwords set in the http_proxy_password setting must be valid as part of a URL, and any reserved characters must be URL-encoded. We received: #{value}"
         end
       end,
@@ -700,40 +701,54 @@ Valid values are 0 (never cache) and 15 (15 second minimum wait time).
     :environment_timeout => {
       :default    => "0",
       :type       => :ttl,
-      :desc       => "How long the Puppet master should cache data it loads from an
+      :desc       => "How long the Puppet server should cache data it loads from an
       environment.
 
       A value of `0` will disable caching. This setting can also be set to
-      `unlimited`, which will cache environments until the master is restarted
-      or told to refresh the cache.
+      `unlimited`, which will cache environments until the server is restarted
+      or told to refresh the cache. All other values will result in Puppet
+      server evicting expired environments. The expiration time is computed
+      based on either when the environment was created or last accessed, see
+      `environment_timeout_mode`.
 
       You should change this setting once your Puppet deployment is doing
       non-trivial work. We chose the default value of `0` because it lets new
       users update their code without any extra steps, but it lowers the
-      performance of your Puppet master.
-
-      We recommend setting this to `unlimited` and explicitly refreshing your
-      Puppet master as part of your code deployment process.
-
-      * With Puppet Server, you should refresh environments by calling the
-        `environment-cache` API endpoint. See the docs for the Puppet Server
-        [administrative API](https://puppet.com/docs/puppetserver/latest/admin-api/v1/environment-cache.html).
-
-      Any value other than `0` or `unlimited` is deprecated, since most Puppet
-      servers use a pool of Ruby interpreters which all have their own cache
-      timers. When these timers drift out of sync, agents can be served
-      inconsistent catalogs.",
+      performance of your Puppet server. We recommend either:
+
+      * Setting this to `unlimited` and explicitly refreshing your Puppet server
+        as part of your code deployment process.
+
+      * Setting this to a number that will keep your most actively used
+        environments cached, but allow testing environments to fall out of the
+        cache and reduce memory usage. A value of 3 minutes (3m) is a reasonable
+        value. This option requires setting `environment_timeout_mode` to
+        `from_last_used`.
+
+      Once you set `environment_timeout` to a non-zero value, you need to tell
+      Puppet server to read new code from disk using the `environment-cache` API
+      endpoint after you deploy new code. See the docs for the Puppet Server
+      [administrative API](https://puppet.com/docs/puppetserver/latest/admin-api/v1/environment-cache.html).
+      ",
       :hook => proc do |val|
-        unless [0, 'unlimited', Float::INFINITY].include?(val)
-          Puppet.deprecation_warning(<<-WARNING)
-Fine grained control of environment timeouts is deprecated,
-please use `0` or `unlimited` to control default caching behavior
-and the environment-cache endpoint in Puppet Server's administrative
-API to expire the cache as needed
-          WARNING
+        if Puppet[:environment_timeout_mode] == :from_created
+          unless [0, 'unlimited', Float::INFINITY].include?(val)
+            Puppet.deprecation_warning("Evicting environments based on their creation time is deprecated, please set `environment_timeout_mode` to `from_last_used` instead.")
+          end
         end
       end
     },
+    :environment_timeout_mode => {
+      :default => :from_created,
+      :type    => :symbolic_enum,
+      :values  => [:from_created, :from_last_used],
+      :desc => "How Puppet interprets the `environment_timeout` setting when
+      `environment_timeout` is neither `0` nor `unlimited`. If set to
+      `from_created`, then the environment will be evicted `environment_timeout`
+      seconds from when it was created. If set to `from_last_used` then the
+      environment will be evicted `environment_timeout` seconds from when it
+      was last used."
+    },
     :environment_data_provider => {
       :desc       => "The name of a registered environment data provider used when obtaining environment
       specific data. The three built in and registered providers are 'none' (no data), 'function' (data
@@ -827,7 +842,10 @@ API to expire the cache as needed
           **Note:** You must set the certname in the main section of the puppet.conf file. Setting it in a different section causes errors.
 
         Defaults to the node's fully qualified domain name.",
-      :hook => proc { |value| raise(ArgumentError, _("Certificate names must be lower case")) unless value == value.downcase }},
+      :call_hook => :on_initialize_and_write,
+      :hook => proc { |value|
+        raise(ArgumentError, _("Certificate names must be lower case")) unless value == value.downcase
+      }},
     :dns_alt_names => {
       :default => '',
       :desc    => <<EOT,
@@ -1110,7 +1128,7 @@ EOT
       :type      => :string,
       :desc      => "Where to send log messages. Choose between 'syslog' (the POSIX syslog
       service), 'eventlog' (the Windows Event Log), 'console', or the path to a log
-      file."
+      file. Multiple destinations can be set using a comma separated list (eg: `/path/file1,console,/path/file2`)"
       # Sure would be nice to set the Puppet::Util::Log destination here in an :on_initialize_and_write hook,
       # unfortunately we have a large number of tests that rely on the logging not resetting itself when the
       # settings are initialized as they test what gets logged during settings initialization.
@@ -1303,7 +1321,7 @@ EOT
     }
   )
 
-  settings.define_settings(:master,
+  settings.define_settings(:server,
     :user => {
       :default    => "puppet",
       :desc       => "The user Puppet Server will run as. Used to ensure
@@ -1359,6 +1377,10 @@ EOT
       with Puppet Server. (eg `puppet facts upload`, `puppet agent`). May be
       overridden by more specific settings (see `ca_port`, `report_port`).",
     },
+    :serverport => {
+      :type => :alias,
+      :alias_for => :masterport
+    },
     :node_name => {
       :default    => 'cert',
       :type       => :enum,
@@ -1719,7 +1741,7 @@ EOT
       and does not need to horizontally scale.",
     },
     :ca_port => {
-      :default    => "$masterport",
+      :default    => "$serverport",
       :desc       => "The port to use for the certificate authority.",
     },
     :preferred_serialization_format => {
@@ -1808,7 +1830,7 @@ EOT
       :desc     => "The server to send transaction reports to.",
     },
     :report_port => {
-      :default  => "$masterport",
+      :default  => "$serverport",
       :desc     => "The port to communicate with the report_server.",
     },
     :report => {
@@ -1848,7 +1870,11 @@ EOT
       :default  => "$statedir/last_run_report.yaml",
       :type     => :file,
       :mode     => "0640",
-      :desc     => "Where puppet agent stores the last run report in yaml format."
+      :desc     => "Where Puppet Agent stores the last run report, by default, in yaml format.
+        The format of the report can be changed by setting the `cache` key of the `report` terminus
+        in the [routes.yaml](https://puppet.com/docs/puppet/latest/config_file_routes.html) file.
+        To avoid mismatches between content and file extension, this setting needs to be
+        manually updated to reflect the terminus changes."
     },
     :graph => {
       :default  => false,
@@ -2123,7 +2149,7 @@ EOT
     }
   )
 
-  settings.define_settings(:master,
+  settings.define_settings(:server,
     :storeconfigs => {
       :default  => false,
       :type     => :boolean,
@@ -2192,12 +2218,18 @@ EOT
    :func3x_check => {
      :default => true,
      :type => :boolean,
-     :desc => <<-'EOT'
+     :desc => <<-'EOT',
        Causes validation of loaded legacy Ruby functions (3x API) to raise errors about illegal constructs that
        could cause harm or that simply does not work. This flag is on by default. This flag is made available
        so that the validation can be turned off in case the method of validation is faulty - if encountered, please
        file a bug report.
      EOT
+     :call_hook => :on_initialize_and_write,
+     :hook => proc do |value|
+       unless value
+         Puppet.deprecation_warning(_("The 'func3x_check' setting is deprecated and will be removed in a future release."))
+       end
+     end
      },
   :tasks => {
     :default => false,

data/lib/puppet/environments.rb

@@ -159,8 +159,8 @@ module Puppet::Environments
   # Reads environments from a directory on disk. Each environment is
   # represented as a sub-directory. The environment's manifest setting is the
   # `manifest` directory of the environment directory. The environment's
-  # modulepath setting is the global modulepath (from the `[master]` section
-  # for the master) prepended with the `modules` directory of the environment
+  # modulepath setting is the global modulepath (from the `[server]` section
+  # for the server) prepended with the `modules` directory of the environment
   # directory.
   #
   # @api private
@@ -277,7 +277,7 @@ module Puppet::Environments
     def get(name)
       @loaders.each do |loader|
         env = loader.get(name)
-        if env 
+        if env
           return env
         end
       end
@@ -305,13 +305,23 @@ module Puppet::Environments
     include Puppet::Concurrent::Synchronized
 
     class DefaultCacheExpirationService
+      # Called when the environment is created.
+      #
+      # @param [Puppet::Node::Environment] env
       def created(env)
       end
 
+      # Is the environment with this name expired?
+      #
+      # @param [Symbol] env_name The symbolic environment name
+      # @return [Boolean]
       def expired?(env_name)
         false
       end
 
+      # The environment with this name was evicted.
+      #
+      # @param [Symbol] env_name The symbolic environment name
       def evicted(env_name)
       end
     end
@@ -336,12 +346,6 @@ module Puppet::Environments
       @loader = loader
       @cache_expiration_service = Puppet::Environments::Cached.cache_expiration_service
       @cache = {}
-
-      # Holds expiration times in sorted order - next to expire is first
-      @expirations = SortedSet.new
-
-      # Infinity since it there are no entries, this is a cache of the first to expire time
-      @next_expiration = END_OF_TIME
     end
 
     # @!macro loader_list
@@ -362,12 +366,13 @@ module Puppet::Environments
       clear_all_expired
       result = @cache[name]
       if result
+        Puppet.debug {"Found in cache '#{name}' #{result.label}"}
         # found in cache
+        result.touch
         return result.value
       elsif (result = @loader.get(name))
         # environment loaded, cache it
         cache_entry = entry(result)
-        @cache_expiration_service.created(result)
         add_entry(name, cache_entry)
         result
       end
@@ -377,28 +382,36 @@ module Puppet::Environments
     def add_entry(name, cache_entry)
       Puppet.debug {"Caching environment '#{name}' #{cache_entry.label}"}
       @cache[name] = cache_entry
-      expires = cache_entry.expires
-      @expirations.add(expires)
-      if @next_expiration > expires
-        @next_expiration = expires
-      end
+      @cache_expiration_service.created(cache_entry.value)
     end
     private :add_entry
 
+    def clear_entry(name, entry)
+      @cache.delete(name)
+      Puppet.debug {"Evicting cache entry for environment '#{name}'"}
+      @cache_expiration_service.evicted(name.to_sym)
+      Puppet::GettextConfig.delete_text_domain(name)
+      Puppet.settings.clear_environment_settings(name)
+    end
+    private :clear_entry
+
     # Clears the cache of the environment with the given name.
     # (The intention is that this could be used from a MANUAL cache eviction command (TBD)
     def clear(name)
-      @cache.delete(name)
-      Puppet::GettextConfig.delete_text_domain(name)
+      entry = @cache[name]
+      clear_entry(name, entry) if entry
     end
 
     # Clears all cached environments.
     # (The intention is that this could be used from a MANUAL cache eviction command (TBD)
-    def clear_all()
+    def clear_all
       super
+
+      @cache.each_pair do |name, entry|
+        clear_entry(name, entry)
+      end
+
       @cache = {}
-      @expirations.clear
-      @next_expiration = END_OF_TIME
       Puppet::GettextConfig.delete_environment_text_domains
     end
 
@@ -407,17 +420,23 @@ module Puppet::Environments
     #
     def clear_all_expired()
       t = Time.now
-      return if t < @next_expiration && ! @cache.any? {|name, _| @cache_expiration_service.expired?(name.to_sym) }
-      to_expire = @cache.select { |name, entry| entry.expires < t || @cache_expiration_service.expired?(name.to_sym) }
-      to_expire.each do |name, entry|
-        Puppet.debug {"Evicting cache entry for environment '#{name}'"}
-        @cache_expiration_service.evicted(name)
-        clear(name)
-        @expirations.delete(entry.expires)
-        Puppet.settings.clear_environment_settings(name)
+
+      @cache.each_pair do |name, entry|
+        clear_if_expired(name, entry, t)
+      end
+    end
+
+    # Clear an environment if it is expired, either by exceeding its time to live, or
+    # through an explicit eviction determined by the cache expiration service.
+    #
+    def clear_if_expired(name, entry, t = Time.now)
+      return unless entry
+
+      if entry.expired?(t) || @cache_expiration_service.expired?(name.to_sym)
+        clear_entry(name, entry)
       end
-      @next_expiration = @expirations.first || END_OF_TIME
     end
+    private :clear_if_expired
 
     # This implementation evicts the cache, and always gets the current
     # configuration of the environment
@@ -428,32 +447,30 @@ module Puppet::Environments
     #
     # @!macro loader_get_conf
     def get_conf(name)
-      evict_if_expired(name)
+      clear_if_expired(name, @cache[name])
       @loader.get_conf(name)
     end
 
     # Creates a suitable cache entry given the time to live for one environment
     #
     def entry(env)
-      ttl = (conf = get_conf(env.name)) ? conf.environment_timeout : Puppet.settings.value(:environment_timeout)
+      ttl = if (conf = get_conf(env.name))
+              conf.environment_timeout
+            else
+              Puppet[:environment_timeout]
+            end
+
       case ttl
       when 0
         NotCachedEntry.new(env)     # Entry that is always expired (avoids syscall to get time)
       when Float::INFINITY
         Entry.new(env)              # Entry that never expires (avoids syscall to get time)
       else
-        TTLEntry.new(env, ttl)
-      end
-    end
-
-    # Evicts the entry if it has expired
-    # Also clears caches in Settings that may prevent the entry from being updated
-    def evict_if_expired(name)
-      if (result = @cache[name]) && (result.expired? || @cache_expiration_service.expired?(name))
-        Puppet.debug {"Evicting cache entry for environment '#{name}'"}
-        @cache_expiration_service.evicted(name)
-        clear(name)
-        Puppet.settings.clear_environment_settings(name)
+        if Puppet[:environment_timeout_mode] == :from_last_used
+          MRUEntry.new(env, ttl)    # Entry that expires in ttl from when it was last touched
+        else
+          TTLEntry.new(env, ttl)    # Entry that expires in ttl from when it was created
+        end
       end
     end
 
@@ -465,52 +482,60 @@ module Puppet::Environments
         @value = value
       end
 
-      def expired?
+      def touch
+      end
+
+      def expired?(now)
         false
       end
 
       def label
         ""
       end
-
-      def expires
-        END_OF_TIME
-      end
     end
 
     # Always evicting entry
     class NotCachedEntry < Entry
-      def expired?
+      def expired?(now)
         true
       end
 
       def label
         "(ttl = 0 sec)"
       end
-
-      def expires
-        START_OF_TIME
-      end
     end
 
-    # Time to Live eviction policy entry
+    # Policy that expires in ttl_seconds from when it was created
     class TTLEntry < Entry
       def initialize(value, ttl_seconds)
-        super value
+        super(value)
         @ttl = Time.now + ttl_seconds
         @ttl_seconds = ttl_seconds
       end
 
-      def expired?
-        Time.now > @ttl
+      def expired?(now)
+        now > @ttl
       end
 
       def label
         "(ttl = #{@ttl_seconds} sec)"
       end
+    end
 
-      def expires
-        @ttl
+    # Policy that expires if it hasn't been touched within ttl_seconds
+    class MRUEntry < TTLEntry
+      def initialize(value, ttl_seconds)
+        super(value, ttl_seconds)
+
+        touch
+      end
+
+      def touch
+        @ttl = Time.now + @ttl_seconds
+      end
+
+      def label
+        "(mru = #{@ttl_seconds} sec)"
       end
     end
   end