puppet 6.21.1 → 7.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a276ad05a056a465b7a0a2c8a3c6e8ca1027a12614be90761c61c884237aefc8
-  data.tar.gz: 69bc653c7fcf75a6893083bd7fe216d8628e9f03e5a1ded3567f0f8f94891e8d
+  metadata.gz: 1dc7fca54856073eca2fb108213f2870e9d9cbe9c176bf4c0ff1820182aa1487
+  data.tar.gz: 0e73ef249f8a19167ba68b84e3d8ddf2a5fcf82a5689d7955ed777feff43c5cf
 SHA512:
-  metadata.gz: 7e0ff67c06a24ed7a113c00b3fb60da8258940b8bf7642fa37bfd562200b169a928d7d0d8b35c6019f88f5155042c39f2bb3a3647ae8bd32e8472d83fa0139c5
-  data.tar.gz: 335aa790b52bf6c92f866c056f8b3103b583828d3c9face8a375c0488e683dd82bd51e2eaca88ec1c95e21291ce0781a5091e57d6eb92c5f86a2d7800f1a3cbb
+  metadata.gz: 313206ed5d0288d41c429eaef41b6507afd490298ff4b549bae911dffcbd06c2a1579329e4cf9ae94d5a1c2888d981c51730ec38450298cfd63b35f07cd34ca3
+  data.tar.gz: a9204bfb79227de4126b352a12dce922723de2910c621ebfa28e220756440c3b76f34d4e489e7c5d898a93a9f79297c044ac3bb8dff420279493dc8f75098a1a

data/Gemfile

@@ -14,13 +14,10 @@ end
 
 # override .gemspec deps - may issue warning depending on Bundler version
 gem "facter", *location_for(ENV['FACTER_LOCATION']) if ENV.has_key?('FACTER_LOCATION')
-gem "facter-ng", *location_for(ENV['FACTER_NG_LOCATION']) if ENV.has_key?('FACTER_NG_LOCATION')
 gem "hiera", *location_for(ENV['HIERA_LOCATION']) if ENV.has_key?('HIERA_LOCATION')
 gem "semantic_puppet", *location_for(ENV['SEMANTIC_PUPPET_LOCATION'] || ["~> 1.0"])
 gem "puppet-resource_api", *location_for(ENV['RESOURCE_API_LOCATION'] || ["~> 1.5"])
 
-gem "scanf" if RUBY_VERSION.to_f >= 2.7
-
 group(:features) do
   gem 'diff-lcs', '~> 1.3', require: false
   gem 'hiera-eyaml', *location_for(ENV['HIERA_EYAML_LOCATION'])
@@ -34,7 +31,7 @@ group(:features) do
   # gem 'ruby-augeas', require: false, platforms: [:ruby]
   # requires native ldap headers/libs
   # gem 'ruby-ldap', '~> 0.9', require: false, platforms: [:ruby]
-  gem 'puppetserver-ca', '~> 1.1', require: false
+  gem 'puppetserver-ca', '~> 2.0', require: false
 end
 
 group(:test) do

data/Gemfile.lock

@@ -1,16 +1,16 @@
 PATH
   remote: .
   specs:
-    puppet (6.21.1)
+    puppet (7.4.1)
       CFPropertyList (~> 2.2)
       concurrent-ruby (~> 1.0)
       deep_merge (~> 1.0)
       facter (>= 2.4.0, < 5)
       fast_gettext (~> 1.1)
       hiera (>= 3.2.1, < 4)
-      httpclient (~> 2.8)
       locale (~> 2.1)
       multi_json (~> 1.13)
+      scanf (~> 1.0)
       semantic_puppet (~> 1.0)
 
 GEM
@@ -49,7 +49,6 @@ GEM
     highline (1.6.21)
     hocon (1.3.1)
     hpricot (0.8.6)
-    httpclient (2.8.3)
     json-schema (2.8.1)
       addressable (>= 2.4)
     locale (2.1.3)
@@ -75,7 +74,7 @@ GEM
     public_suffix (4.0.6)
     puppet-resource_api (1.8.13)
       hocon (>= 1.0)
-    puppetserver-ca (1.9.1)
+    puppetserver-ca (2.0.1)
       facter (>= 2.0.1, < 5)
     racc (1.4.9)
     rainbow (2.2.2)
@@ -118,6 +117,7 @@ GEM
       rubocop (~> 0.49.0)
     ruby-prof (1.4.2)
     ruby-progressbar (1.11.0)
+    scanf (1.0.0)
     semantic_puppet (1.0.3)
     text (1.3.1)
     thor (1.1.0)
@@ -146,7 +146,7 @@ DEPENDENCIES
   pry
   puppet!
   puppet-resource_api (~> 1.5)
-  puppetserver-ca (~> 1.1)
+  puppetserver-ca (~> 2.0)
   racc (= 1.4.9)
   rake (~> 12.2)
   rdoc (~> 6.0)

data/README.md

@@ -15,7 +15,7 @@ Documentation for Puppet and related projects can be found online at the
 
 ### HTTP API
 
-[HTTP API Index](https://puppet.com/docs/puppet/5.5/http_api/http_api_index.html)
+[HTTP API Index](https://puppet.com/docs/puppet/latest/http_api/http_api_index.html)
 
 ## Installation
 

data/conf/fileserver.conf

@@ -12,10 +12,9 @@
 #
 # [extra_files]
 #   path /etc/puppetlabs/puppet/files
-#   allow *
 #
-# In the example above, anything in /etc/puppetlabs/puppet/files/<file name> would be
-# available to authenticated nodes at puppet:///extra_files/<file name>.
+# In the example above, anything in /etc/puppetlabs/puppet/files/<file name>
+# would be available to authenticated nodes at puppet:///extra_files/<file name>.
 #
 # Mount points may also use three placeholders as part of their path:
 #
@@ -28,10 +27,6 @@
 # PERMISSIONS
 
 # The ability to set permissions - for example, using the allow, allow_ip, or
-# deny directives - has been removed. Instead, you can control file access in
-# auth.conf by controlling the /file_metadata(s)/<mount point> and
-# /file_content(s)/<mount point> paths.
-#
-# For details and an example, see the auth.conf file. If you're using Puppet
-# Server, see the Puppet Server documentation at
-# https://puppet.com/docs/puppetserver/latest/config_file_auth.html.
+# deny directives - has been removed from fileserver.conf. Instead, you can
+# control file access in Puppet Server's auth.conf file. See the documentation
+# at https://puppet.com/docs/puppetserver/latest/config_file_auth.html.

data/ext/build_defaults.yaml

@@ -1,6 +1,5 @@
 ---
 packager: 'puppetlabs'
-gpg_key: '7F438280EF8D349F'
 
 # These are the build targets used by the packaging repo. Uncomment to allow use.
 #final_mocks: 'pl-el-5-i386 pl-el-6-i386 pl-el-7-x86_64'
@@ -16,4 +15,4 @@ apt_signing_server: 'apt.puppetlabs.com'
 apt_repo_url: 'http://apt.puppetlabs.com'
 apt_repo_path: '/opt/repository/incoming'
 tar_host: 'downloads.puppetlabs.com'
-nonfinal_gem_path: '/opt/repository-nightlies/downloads/gems/puppet6-nightly'
+nonfinal_gem_path: '/opt/repository-nightlies/downloads/gems/puppet7-nightly'

data/ext/osx/file_mapping.yaml

@@ -15,11 +15,6 @@ directories:
     group: 'wheel'
     perms: '0755'
 files:
-  'conf/auth.conf':
-    path: 'private/etc/puppet'
-    owner: 'root'
-    group: 'wheel'
-    perms: '0644'
   'man/man5/puppet.conf.5':
     path: 'usr/share/man/man5'
     owner: 'root'

data/ext/project_data.yaml

@@ -14,7 +14,7 @@ gem_test_files: 'spec/**/*'
 gem_executables: 'puppet'
 gem_default_executables: 'puppet'
 gem_forge_project: 'puppet'
-gem_required_ruby_version: '>= 2.3.0'
+gem_required_ruby_version: '>= 2.5.0'
 gem_required_rubygems_version: '> 1.3.1'
 gem_runtime_dependencies:
   facter: ['> 2.0.1', '< 5']
@@ -23,10 +23,10 @@ gem_runtime_dependencies:
   fast_gettext: '~> 1.1'
   locale: '~> 2.1'
   multi_json: '~> 1.10'
-  httpclient: '~> 2.8'
   puppet-resource_api: '~>1.5'
   concurrent-ruby: '~> 1.0'
   deep_merge: '~> 1.0'
+  scanf: '~> 1.0'
 gem_rdoc_options:
   - --title
   - "Puppet - Configuration Management"
@@ -40,22 +40,10 @@ gem_platform_dependencies:
   x86-mingw32:
     gem_runtime_dependencies:
       ffi: ['> 1.9.24', '< 2']
-      # win32-xxxx gems are pinned due to PUP-6445
-      win32-dir: '= 0.4.9'
-      win32-process: '= 0.7.5'
-      # Use of win32-security is deprecated
-      win32-security: '= 0.2.5'
-      win32-service: '= 0.8.8'
       minitar: '~> 0.9'
   x64-mingw32:
     gem_runtime_dependencies:
       ffi: ['> 1.9.24', '< 2']
-      # win32-xxxx gems are pinned due to PUP-6445
-      win32-dir: '= 0.4.9'
-      win32-process: '= 0.7.5'
-      # Use of win32-security is deprecated
-      win32-security: '= 0.2.5'
-      win32-service: '= 0.8.8'
       minitar: '~> 0.9'
 bundle_platforms:
   universal-darwin: all

data/ext/redhat/puppet.spec.erb

@@ -199,7 +199,6 @@ touch %{buildroot}%{_localstatedir}/log/puppet/masterhttp.log
 %config(noreplace) %{_sysconfdir}/tmpfiles.d/%{name}.conf
 %endif
 %config(noreplace) %{_sysconfdir}/puppet/puppet.conf
-%config(noreplace) %{_sysconfdir}/puppet/auth.conf
 %config(noreplace) %{_sysconfdir}/logrotate.d/puppet
 # We don't want to require emacs or vim, so we need to own these dirs
 %{_datadir}/emacs

data/ext/windows/service/daemon.rb

@@ -1,22 +1,23 @@
 #!/usr/bin/env ruby
 
 require 'fileutils'
-require 'win32/daemon'
-require 'win32/dir'
-require 'win32/process'
+require 'puppet/util/windows/daemon'
 
 # This file defines utilities for logging to eventlog. While it lives inside
 # Puppet, it is completely independent and loads no other parts of Puppet, so we
 # can safely require *just* it.
 require 'puppet/util/windows/eventlog'
 
-class WindowsDaemon < Win32::Daemon
+# monkey patches ruby Process to add .create method
+require 'puppet/util/windows/monkey_patches/process'
+
+class WindowsDaemon < Puppet::Util::Windows::Daemon
   CREATE_NEW_CONSOLE          = 0x00000010
 
   @run_thread = nil
   @LOG_TO_FILE = false
   @loglevel = 0
-  LOG_FILE =  File.expand_path(File.join(Dir::COMMON_APPDATA, 'PuppetLabs', 'puppet', 'var', 'log', 'windows.log'))
+  LOG_FILE =  File.expand_path(File.join(ENV['ALLUSERSPROFILE'], 'PuppetLabs', 'puppet', 'var', 'log', 'windows.log'))
   LEVELS = [:debug, :info, :notice, :warning, :err, :alert, :emerg, :crit]
   LEVELS.each do |level|
     define_method("log_#{level}") do |msg|

data/install.rb

@@ -178,6 +178,9 @@ def prepare_installation
     opts.on('--vardir[=OPTIONAL]', 'Installation directory for var files', 'Default /opt/puppetlabs/puppet/cache') do |vardir|
       InstallOptions.vardir = vardir
     end
+    opts.on('--publicdir[=OPTIONAL]', 'Installation directory for public files such as the `last_run_summary.yaml` report', 'Default /opt/puppetlabs/puppet/public') do |publicdir|
+      InstallOptions.publicdir = publicdir
+    end
     opts.on('--rundir[=OPTIONAL]', 'Installation directory for state files', 'Default /var/run/puppetlabs') do |rundir|
       InstallOptions.rundir = rundir
     end
@@ -242,20 +245,10 @@ def prepare_installation
     $operatingsystem = Facter.value :operatingsystem
   end
 
-  if $operatingsystem == "windows"
-    begin
-      # populates constants used to specify default Windows directories
-      require 'win32/dir'
-    rescue LoadError => e
-      puts "Cannot run on Microsoft Windows without the win32-process, win32-dir & win32-service gems: #{e}"
-      exit(-1)
-    end
-  end
-
   if not InstallOptions.configdir.nil?
     configdir = InstallOptions.configdir
   elsif $operatingsystem == "windows"
-    configdir = File.join(Dir::COMMON_APPDATA, "PuppetLabs", "puppet", "etc")
+    configdir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "puppet", "etc")
   else
     configdir = "/etc/puppetlabs/puppet"
   end
@@ -263,7 +256,7 @@ def prepare_installation
   if not InstallOptions.codedir.nil?
     codedir = InstallOptions.codedir
   elsif $operatingsystem == "windows"
-    codedir = File.join(Dir::COMMON_APPDATA, "PuppetLabs", "code")
+    codedir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "code")
   else
     codedir = "/etc/puppetlabs/code"
   end
@@ -271,15 +264,23 @@ def prepare_installation
   if not InstallOptions.vardir.nil?
     vardir = InstallOptions.vardir
   elsif $operatingsystem == "windows"
-    vardir = File.join(Dir::COMMON_APPDATA, "PuppetLabs", "puppet", "cache")
+    vardir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "puppet", "cache")
   else
     vardir = "/opt/puppetlabs/puppet/cache"
   end
 
+  if not InstallOptions.publicdir.nil?
+    publicdir = InstallOptions.publicdir
+  elsif $operatingsystem == "windows"
+    publicdir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "puppet", "public")
+  else
+    publicdir = "/opt/puppetlabs/puppet/public"
+  end
+
   if not InstallOptions.rundir.nil?
     rundir = InstallOptions.rundir
   elsif $operatingsystem == "windows"
-    rundir = File.join(Dir::COMMON_APPDATA, "PuppetLabs", "puppet", "var", "run")
+    rundir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "puppet", "var", "run")
   else
     rundir = "/var/run/puppetlabs"
   end
@@ -287,7 +288,7 @@ def prepare_installation
   if not InstallOptions.logdir.nil?
     logdir = InstallOptions.logdir
   elsif $operatingsystem == "windows"
-    logdir = File.join(Dir::COMMON_APPDATA, "PuppetLabs", "puppet", "var", "log")
+    logdir = File.join(ENV['ALLUSERSPROFILE'], "PuppetLabs", "puppet", "var", "log")
   else
     logdir = "/var/log/puppetlabs/puppet"
   end
@@ -302,7 +303,7 @@ def prepare_installation
     localedir = InstallOptions.localedir
   else
     if $operatingsystem == "windows"
-      localedir = File.join(Dir::PROGRAM_FILES, "Puppet Labs", "Puppet", "puppet", "share", "locale")
+      localedir = File.join(ENV['PROGRAMFILES'], "Puppet Labs", "Puppet", "puppet", "share", "locale")
     else
       localedir = "/opt/puppetlabs/puppet/share/locale"
     end
@@ -342,6 +343,7 @@ def prepare_installation
   configdir = join(destdir, configdir)
   codedir = join(destdir, codedir)
   vardir = join(destdir, vardir)
+  publicdir = join(destdir, publicdir)
   rundir = join(destdir, rundir)
   logdir = join(destdir, logdir)
   bindir = join(destdir, bindir)
@@ -355,6 +357,7 @@ def prepare_installation
   FileUtils.makedirs(mandir)
   FileUtils.makedirs(sitelibdir)
   FileUtils.makedirs(vardir)
+  FileUtils.makedirs(publicdir)
   FileUtils.makedirs(rundir)
   FileUtils.makedirs(logdir)
   FileUtils.makedirs(localedir)
@@ -366,6 +369,7 @@ def prepare_installation
   InstallOptions.lib_dir = libdir
   InstallOptions.man_dir = mandir
   InstallOptions.var_dir = vardir
+  InstallOptions.public_dir = publicdir
   InstallOptions.run_dir = rundir
   InstallOptions.log_dir = logdir
   InstallOptions.locale_dir = localedir
@@ -474,7 +478,7 @@ end
 # Change directory into the puppet root so we don't get the wrong files for install.
 FileUtils.cd File.dirname(__FILE__) do
   # Set these values to what you want installed.
-  configs = glob(%w{conf/auth.conf conf/puppet.conf conf/hiera.yaml})
+  configs = glob(%w{conf/puppet.conf conf/hiera.yaml})
   bins  = glob(%w{bin/*})
   #rdoc  = glob(%w{bin/* lib/**/*.rb README* }).reject { |e| e=~ /\.(bat|cmd)$/ }
   #ri    = glob(%w{bin/*.rb lib/**/*.rb}).reject { |e| e=~ /\.(bat|cmd)$/ }

data/lib/puppet.rb

@@ -1,11 +1,11 @@
 require 'puppet/version'
 require 'puppet/concurrent/synchronized'
 
-if Gem::Version.new(RUBY_VERSION.dup) < Gem::Version.new("2.3.0")
-  raise LoadError, "Puppet #{Puppet.version} requires Ruby 2.3.0 or greater, found Ruby #{RUBY_VERSION.dup}."
+if Gem::Version.new(RUBY_VERSION.dup) < Gem::Version.new("2.5.0")
+  raise LoadError, "Puppet #{Puppet.version} requires Ruby 2.5.0 or greater, found Ruby #{RUBY_VERSION.dup}."
 end
 
-Puppet::OLDEST_RECOMMENDED_RUBY_VERSION = '2.3.0'
+Puppet::OLDEST_RECOMMENDED_RUBY_VERSION = '2.5.0'
 
 $LOAD_PATH.extend(Puppet::Concurrent::Synchronized)
 
@@ -27,16 +27,16 @@ require 'puppet/external/pson/pure'
 require 'puppet/gettext/config'
 require 'puppet/defaults'
 
-
-#------------------------------------------------------------
-# the top-level module
+# Defines the `Puppet` module. There are different entry points into Puppet
+# depending on your use case.
 #
-# all this really does is dictate how the whole system behaves, through
-# preferences for things like debugging
+# To use puppet as a library, see {Puppet::Pal}.
 #
-# it's also a place to find top-level commands like 'debug'
-
-# The main Puppet class. Everything is contained here.
+# To create a new application, see {Puppet::Application}.
+#
+# To create a new function, see {Puppet::Functions}.
+#
+# To access puppet's REST APIs, see https://puppet.com/docs/puppet/latest/http_api/http_api_index.html.
 #
 # @api public
 module Puppet
@@ -97,12 +97,6 @@ module Puppet
   # Load the base features.
   require 'puppet/feature/base'
 
-  # Store a new default value.
-  def self.define_settings(section, hash)
-    Puppet.deprecation_warning('The method Puppet.define_settings is deprecated and will be removed in a future release')
-    @@settings.define_settings(section, hash)
-  end
-
   # setting access and stuff
   def self.[]=(param,value)
     @@settings[param] = value
@@ -245,7 +239,6 @@ module Puppet
 
     {
       :environments => Puppet::Environments::Cached.new(Puppet::Environments::Combined.new(*loaders)),
-      :http_pool => proc { Puppet.runtime[:http].pool },
       :ssl_context => proc {
         begin
           cert = Puppet::X509::CertProvider.new
@@ -260,7 +253,6 @@ module Puppet
           raise e
         end
       },
-      :ssl_host => proc { Puppet::SSL::Host.localhost(true) },
       :http_session => proc { Puppet.runtime[:http].create_session },
       :plugins => proc { Puppet::Plugins::Configuration.load_plugins },
       :rich_data => false
@@ -364,7 +356,6 @@ require 'puppet/ssl'
 require 'puppet/module'
 require 'puppet/data_binding'
 require 'puppet/util/storage'
-require 'puppet/status'
 require 'puppet/file_bucket/file'
 require 'puppet/plugins/configuration'
 require 'puppet/pal/pal_api'

data/lib/puppet/application.rb

@@ -6,95 +6,74 @@ require 'puppet/application_support'
 
 module Puppet
 
-# This class handles all the aspects of a Puppet application/executable
-# * setting up options
-# * setting up logs
-# * choosing what to run
-# * representing execution status
+# Defines an abstract Puppet application.
 #
-# === Usage
-# An application is a subclass of Puppet::Application.
-#
-# For legacy compatibility,
-#      Puppet::Application[:example].run
-# is equivalent to
-#      Puppet::Application::Example.new.run
+# # Usage
 #
+# To create a new application extend `Puppet::Application`. Derived applications
+# must implement the `main` method and should implement the `summary` and
+# `help` methods in order to be included in `puppet help`, and should define
+# application-specific options. For example:
 #
+# ```
 # class Puppet::Application::Example < Puppet::Application
 #
-#     def preinit
-#         # perform some pre initialization
-#         @all = false
-#     end
-#
-#     # run_command is called to actually run the specified command
-#     def run_command
-#         send Puppet::Util::CommandLine.new.args.shift
-#     end
+#   def summary
+#     "My puppet example application"
+#   end
 #
-#     # option uses metaprogramming to create a method
-#     # and also tells the option parser how to invoke that method
-#     option("--arg ARGUMENT") do |v|
-#         @args << v
-#     end
+#   def help
+#     <<~HELP
+#     puppet-example(8) -- #{summary}
+#     ...
+#     HELP
+#   end
 #
-#     option("--debug", "-d") do |v|
-#         @debug = v
-#     end
+#   # define arg with a required option
+#   option("--arg ARGUMENT") do |v|
+#     options[:arg] = v
+#   end
 #
-#     option("--all", "-a:) do |v|
-#         @all = v
-#     end
+#   # define arg with an optional option
+#   option("--maybe [ARGUMENT]") do |v|
+#     options[:maybe] = v
+#   end
 #
-#     def handle_unknown(opt,arg)
-#         # last chance to manage an option
-#         ...
-#         # let's say to the framework we finally handle this option
-#         true
-#     end
+#   # define long and short arg
+#   option("--all", "-a")
 #
-#     def read
-#         # read action
-#     end
+#   def initialize(command_line = Puppet::Util::CommandLine.new)
+#     super
+#     @data = {}
+#   end
 #
-#     def write
-#         # writeaction
-#     end
-#
-# end
+#   def main
+#     # call action
+#     send(@command_line.args.shift)
+#   end
 #
-# === Preinit
-# The preinit block is the first code to be called in your application, before option parsing,
-# setup or command execution.
+#   def read
+#     # read action
+#   end
 #
-# === Options
-# Puppet::Application uses +OptionParser+ to manage the application options.
-# Options are defined with the +option+ method to which are passed various
-# arguments, including the long option, the short option, a description...
-# Refer to +OptionParser+ documentation for the exact format.
-# * If the option method is given a block, this one will be called whenever
-# the option is encountered in the command-line argument.
-# * If the option method has no block, a default functionality will be used, that
-# stores the argument (or true/false if the option doesn't require an argument) in
-# the global (to the application) options array.
-# * If a given option was not defined by a the +option+ method, but it exists as a Puppet settings:
-#  * if +unknown+ was used with a block, it will be called with the option name and argument
-#  * if +unknown+ wasn't used, then the option/argument is handed to Puppet.settings.handlearg for
-#    a default behavior
+#   def write
+#     # write action
+#   end
 #
-# --help is managed directly by the Puppet::Application class, but can be overridden.
+# end
+# ```
 #
-# === Setup
-# Applications can use the setup block to perform any initialization.
-# The default +setup+ behaviour is to: read Puppet configuration and manage log level and destination
+# Puppet defines the following application lifecycle methods that are called in
+# the following order:
 #
-# === What and how to run
-# If the +dispatch+ block is defined it is called. This block should return the name of the registered command
-# to be run.
-# If it doesn't exist, it defaults to execute the +main+ command if defined.
+# * {#initialize}
+# * {#initialize_app_defaults}
+# * {#preinit}
+# * {#parse_options}
+# * {#setup}
+# * {#main}
 #
-# === Execution state
+# ## Execution state
 # The class attributes/methods of Puppet::Application serve as a global place to set and query the execution
 # status of the application: stopping, restarting, etc.  The setting of the application status does not directly
 # affect its running status; it's assumed that the various components within the application will consult these
@@ -104,21 +83,27 @@ module Puppet
 #
 # So, if something in your application needs to stop the process, for some reason, you might consider:
 #
+# ```
 #  def stop_me!
-#      # indicate that we're stopping
-#      Puppet::Application.stop!
-#      # ...do stuff...
+#    # indicate that we're stopping
+#    Puppet::Application.stop!
+#    # ...do stuff...
 #  end
+# ```
 #
 # And, if you have some component that involves a long-running process, you might want to consider:
 #
+# ```
 #  def my_long_process(giant_list_to_munge)
-#      giant_list_to_munge.collect do |member|
-#          # bail if we're stopping
-#          return if Puppet::Application.stop_requested?
-#          process_member(member)
-#      end
+#    giant_list_to_munge.collect do |member|
+#      # bail if we're stopping
+#      return if Puppet::Application.stop_requested?
+#      process_member(member)
+#    end
 #  end
+# ```
+# @abstract
+# @api public
 class Application
   require 'puppet/util'
   include Puppet::Util
@@ -137,34 +122,42 @@ class Application
       self.run_status = nil
     end
 
+    # Signal that the application should stop.
+    # @api public
     def stop!
       self.run_status = :stop_requested
     end
 
+    # Signal that the application should restart.
+    # @api public
     def restart!
       self.run_status = :restart_requested
     end
 
     # Indicates that Puppet::Application.restart! has been invoked and components should
     # do what is necessary to facilitate a restart.
+    # @api public
     def restart_requested?
       :restart_requested == run_status
     end
 
     # Indicates that Puppet::Application.stop! has been invoked and components should do what is necessary
     # for a clean stop.
+    # @api public
     def stop_requested?
       :stop_requested == run_status
     end
 
     # Indicates that one of stop! or start! was invoked on Puppet::Application, and some kind of process
     # shutdown/short-circuit may be necessary.
+    # @api public
     def interrupted?
       [:restart_requested, :stop_requested].include? run_status
     end
 
     # Indicates that Puppet::Application believes that it's in usual running run_mode (no stop/restart request
     # currently active).
+    # @api public
     def clear?
       run_status.nil?
     end
@@ -270,14 +263,21 @@ class Application
     end
     private :try_load_class
 
+    # Return an instance of the specified application.
+    #
+    # @param [Symbol] name the lowercase name of the application
+    # @return [Puppet::Application] an instance of the specified name
+    # @raise [Puppet::Error] if the application class was not found.
+    # @raise [LoadError] if there was a problem loading the application file.
+    # @api public
     def [](name)
       find(name).new
     end
 
     # Sets or gets the run_mode name. Sets the run_mode name if a mode_name is
     # passed. Otherwise, gets the run_mode or a default run_mode
-    #
-    def run_mode( mode_name = nil)
+    # @api public
+    def run_mode(mode_name = nil)
       if mode_name
         Puppet.settings.preferred_run_mode = mode_name
       end
@@ -288,12 +288,19 @@ class Application
       @run_mode = Puppet::Util::RunMode[ mode_name || Puppet.settings.preferred_run_mode ]
     end
 
-    # Sets environment_mode name
+    # Sets environment_mode name. When acting as a compiler, the environment mode
+    # should be `:local` since the directory must exist to compile the catalog.
+    # When acting as an agent, the environment mode should be `:remote` since
+    # the Puppet[:environment] setting refers to an environment directoy on a remote
+    # system. The `:not_required` mode is for cases where the application does not
+    # need an environment to run.
+    #
     # @param mode_name [Symbol] The name of the environment mode to run in. May
-    #   be one of :local, :remote, or :not_required. This impacts where the
-    #   application looks for its specified environment. If :not_required or
-    #   :remote are set, the application will not fail if the environment does
+    #   be one of `:local`, `:remote`, or `:not_required`. This impacts where the
+    #   application looks for its specified environment. If `:not_required` or
+    #   `:remote` are set, the application will not fail if the environment does
     #   not exist on the local filesystem.
+    # @api public
     def environment_mode(mode_name)
       raise Puppet::Error, _("Invalid environment mode '%{mode_name}'") % { mode_name: mode_name } unless [:local, :remote, :not_required].include?(mode_name)
       @environment_mode = mode_name
@@ -301,11 +308,14 @@ class Application
 
     # Gets environment_mode name. If none is set with `environment_mode=`,
     # default to :local.
+    # @return [Symbol] The current environment mode
+    # @api public
     def get_environment_mode
       @environment_mode || :local
     end
 
     # This is for testing only
+    # @api public
     def clear_everything_for_tests
       @run_mode = @banner = @run_status = @option_parser_commands = nil
     end
@@ -327,37 +337,66 @@ class Application
     exit(0)
   end
 
-  def app_defaults()
+  # Initialize the application receiving the {Puppet::Util::CommandLine} object
+  # containing the application name and arguments.
+  #
+  # @param command_line [Puppet::Util::CommandLine] An instance of the command line to create the application with
+  # @api public
+  def initialize(command_line = Puppet::Util::CommandLine.new)
+    @command_line = CommandLineArgs.new(command_line.subcommand_name, command_line.args.dup)
+    @options = {}
+  end
+
+  # Now that the `run_mode` has been resolved, return default settings for the
+  # application. Note these values may be overridden when puppet's configuration
+  # is loaded later.
+  #
+  # @example To override the facts terminus:
+  #   def app_defaults
+  #     super.merge({
+  #       :facts_terminus => 'yaml'
+  #     })
+  #   end
+  #
+  # @return [Hash<String, String>] default application settings
+  # @api public
+  def app_defaults
     Puppet::Settings.app_defaults_for_run_mode(self.class.run_mode).merge(
         :name => name
     )
   end
 
+  # Initialize application defaults. It's usually not necessary to override this method.
+  # @return [void]
+  # @api public
   def initialize_app_defaults()
     Puppet.settings.initialize_app_defaults(app_defaults)
   end
 
-  # override to execute code before running anything else
+  # The preinit block is the first code to be called in your application, after
+  # `initialize`, but before option parsing, setup or command execution. It is
+  # usually not necessary to override this method.
+  # @return [void]
+  # @api public
   def preinit
   end
 
-  def initialize(command_line = Puppet::Util::CommandLine.new)
-    @command_line = CommandLineArgs.new(command_line.subcommand_name, command_line.args.dup)
-    @options = {}
-  end
-
-  # call in setup of subclass to deprecate an application
+  # Call in setup of subclass to deprecate an application.
+  # @return [void]
+  # @api public
   def deprecate
     @deprecated = true
   end
 
+  # Return true if this application is deprecated.
+  # @api public
   def deprecated?
     @deprecated
   end
 
-  # Execute the application.
-  # @api public
+  # Execute the application. This method should not be overridden.
   # @return [void]
+  # @api public
   def run
 
     # I don't really like the names of these lifecycle phases.  It would be nice to change them to some more meaningful
@@ -382,18 +421,34 @@ class Application
     exit_on_fail(_("Could not run"))                                          { run_command }
   end
 
+  # This method must be overridden and perform whatever action is required for
+  # the application. The `command_line` reader contains the actions and
+  # arguments.
+  # @return [void]
+  # @api public
   def main
     raise NotImplementedError, _("No valid command or main")
   end
 
+  # Run the application. By default, it calls {#main}.
+  # @return [void]
+  # @api public
   def run_command
     main
   end
 
+  # Setup the application. It is usually not necessary to override this method.
+  # @return [void]
+  # @api public
   def setup
     setup_logs
   end
 
+  # Setup logging. By default the `console` log destination will only be created
+  # if `debug` or `verbose` is specified on the command line. Override to customize
+  # the logging behavior.
+  # @return [void]
+  # @api public
   def setup_logs
     handle_logdest_arg(Puppet[:logdest]) if !options[:setdest]
 
@@ -440,11 +495,10 @@ class Application
   # Output basic information about the runtime environment for debugging
   # purposes.
   #
-  # @api public
-  #
   # @param extra_info [Hash{String => #to_s}] a flat hash of extra information
   #   to log. Intended to be passed to super by subclasses.
   # @return [void]
+  # @api public
   def log_runtime_environment(extra_info=nil)
     runtime_info = {
       'puppet_version' => Puppet.version,
@@ -457,6 +511,21 @@ class Application
     Puppet.debug 'Runtime environment: ' + runtime_info.map{|k,v| k + '=' + v.to_s}.join(', ')
   end
 
+  # Options defined with the `option` method are parsed from settings and the command line.
+  # Refer to {OptionParser} documentation for the exact format. Options are parsed as follows:
+  #
+  # * If the option method is given a block, then it will be called whenever the option is encountered in the command-line argument.
+  # * If the option method has no block, then the default option handler will store the argument in the `options` instance variable.
+  # * If a given option was not defined by an `option` method, but it exists as a Puppet setting:
+  #   * if `unknown` was used with a block, it will be called with the option name and argument.
+  #   * if `unknown` wasn't used, then the option/argument is handed to Puppet.settings.handlearg for
+  #     a default behavior.
+  #  * The `-h` and `--help` options are automatically handled by the command line before creating the application.
+  #
+  # Options specified on the command line override settings. It is usually not
+  # necessary to override this method.
+  # @return [void]
+  # @api public
   def parse_options
     # Create an option parser
     option_parser = OptionParser.new(self.class.banner)
@@ -504,6 +573,9 @@ class Application
     self.class.to_s.sub(/.*::/,"").downcase.to_sym
   end
 
+  # Return the text to display when running `puppet help`.
+  # @return [String] The help to display
+  # @api public
   def help
     _("No help available for puppet %{app_name}") % { app_name: name }
   end
@@ -511,6 +583,8 @@ class Application
   # The description used in top level `puppet help` output
   # If left empty in implementations, we will attempt to extract
   # the summary from the help text itself.
+  # @return [String]
+  # @api public
   def summary
     ""
   end