Document classes and defines

ekohl · mmoll · commit 659253df5703 · 2019-01-10T21:19:14.000+01:00
diff --git a/manifests/agent.pp b/manifests/agent.pp
@@ -1,4 +1,5 @@
 # Puppet agent
+# @api private
 class puppet::agent {
   contain puppet::agent::install
   contain puppet::agent::config
diff --git a/manifests/agent/config.pp b/manifests/agent/config.pp
@@ -1,4 +1,5 @@
 # Puppet agent configuration
+# @api private
 class puppet::agent::config inherits puppet::config {
   puppet::config::agent{
     'classfile':         value => $::puppet::classfile;
diff --git a/manifests/agent/install.pp b/manifests/agent/install.pp
@@ -1,4 +1,5 @@
-# Install the puppet client installation
+# Install the puppet agent package
+# @api private
 class puppet::agent::install(
   $manage_packages = $::puppet::manage_packages,
   $package_name = $::puppet::client_package,
diff --git a/manifests/agent/service.pp b/manifests/agent/service.pp
@@ -1,4 +1,5 @@
-# Set up the puppet client as a service
+# Set up the puppet agent as a service
+# @api private
 class puppet::agent::service {
 
   case $::puppet::runmode {
diff --git a/manifests/agent/service/cron.pp b/manifests/agent/service/cron.pp
@@ -1,3 +1,5 @@
+# Set up running the agent via cron
+# @api private
 class puppet::agent::service::cron (
   Boolean $enabled = false,
 ) {
diff --git a/manifests/agent/service/daemon.pp b/manifests/agent/service/daemon.pp
@@ -1,3 +1,5 @@
+# Set up running the agent as a daemon
+# @api private
 class puppet::agent::service::daemon (
   Boolean $enabled = false,
 ) {
diff --git a/manifests/agent/service/systemd.pp b/manifests/agent/service/systemd.pp
@@ -1,3 +1,5 @@
+# Set up running the agent via a systemd timer
+# @api private
 class puppet::agent::service::systemd (
   Boolean $enabled = false,
 ) {
diff --git a/manifests/config.pp b/manifests/config.pp
@@ -1,4 +1,5 @@
 # Set up the puppet config
+# @api private
 class puppet::config(
   $allow_any_crl_auth  = $::puppet::allow_any_crl_auth,
   $auth_allowed        = $::puppet::auth_allowed,
diff --git a/manifests/config/agent.pp b/manifests/config/agent.pp
@@ -1,3 +1,11 @@
+# Set a config entry in the [agent] section
+#
+# @param value
+#   The value for the config entry
+# @param key
+#   The key of the config entry
+# @param joiner
+#   How to join an array value into a string
 define puppet::config::agent (
   Variant[Array[String], Boolean, String, Integer] $value,
   String $key    = $name,
diff --git a/manifests/config/entry.pp b/manifests/config/entry.pp
@@ -1,3 +1,16 @@
+# Set a config entry
+#
+# @param key
+#   The key of the config entry
+# @param value
+#   The value for the config entry
+# @param section
+#   The section for the config entry
+# @param sectionorder
+#   How to order the section. This is only used on the first definition of the
+#   section via ensure_resource.
+# @param joiner
+#   How to join an array value into a string
 define puppet::config::entry (
   String $key,
   Variant[Array[String], Boolean, String, Integer] $value,
diff --git a/manifests/config/main.pp b/manifests/config/main.pp
@@ -1,3 +1,11 @@
+# Set a config entry in the [main] section
+#
+# @param value
+#   The value for the config entry
+# @param key
+#   The key of the config entry
+# @param joiner
+#   How to join an array value into a string
 define puppet::config::main (
   Variant[Array[String], Boolean, String, Integer] $value,
   String $key    = $name,
diff --git a/manifests/config/master.pp b/manifests/config/master.pp
@@ -1,3 +1,11 @@
+# Set a config entry in the [master] section
+#
+# @param value
+#   The value for the config entry
+# @param key
+#   The key of the config entry
+# @param joiner
+#   How to join an array value into a string
 define puppet::config::master (
   Variant[Array[String], Boolean, String, Integer] $value,
   String $key    = $name,
diff --git a/manifests/params.pp b/manifests/params.pp
@@ -1,4 +1,5 @@
 # Default parameters
+# @api private
 class puppet::params {
 
   # Basic config
diff --git a/manifests/server.pp b/manifests/server.pp
@@ -119,6 +119,8 @@
 #
 # === Advanced server parameters:
 #
+# $codedir::                           Override the puppet code directory.
+#
 # $config_version::                    How to determine the configuration version. When
 #                                      using git_repo, by default a git describe
 #                                      approach will be installed.
@@ -137,13 +139,12 @@
 #
 # $puppet_basedir::                    Where is the puppet code base located
 #
-# $enc_api::                           What version of enc script to deploy. Valid
-#                                      values are 'v2' for latest, and 'v1'
-#                                      for Foreman =< 1.2
+# $enc_api::                           What version of enc script to deploy.
 #
 # $report_api::                        What version of report processor to deploy.
-#                                      Valid values are 'v2' for latest, and 'v1'
-#                                      for Foreman =< 1.2
+#
+# $compile_mode::                      Used to control JRuby's "CompileMode", which may improve performance.
+#
 #
 # $request_timeout::                   Timeout in node.rb script for fetching
 #                                      catalog from Foreman (in seconds).
@@ -194,6 +195,10 @@
 #
 # $puppetserver_vardir::               The path of the puppetserver var dir
 #
+# $puppetserver_rundir::               The path of the puppetserver run dir
+#
+# $puppetserver_logdir::               The path of the puppetserver log dir
+#
 # $puppetserver_dir::                  The path of the puppetserver config dir
 #
 # $puppetserver_version::              The version of puppetserver 2 installed (or being installed)
@@ -206,6 +211,14 @@
 #
 # $max_requests_per_instance::         Max number of requests per jruby instance. Defaults to 0 (disabled)
 #
+# $max_queued_requests::               The maximum number of requests that may be queued waiting to borrow a
+#                                      JRuby from the pool. (Puppetserver 5.x only)
+#                                      Defaults to 0 (disabled) for Puppetserver >= 5.0
+#
+# $max_retry_delay::                   Sets the upper limit for the random sleep set as a Retry-After header on
+#                                      503 responses returned when max-queued-requests is enabled. (Puppetserver 5.x only)
+#                                      Defaults to 1800 for Puppetserver >= 5.0
+#
 # $idle_timeout::                      How long the server will wait for a response on an existing connection
 #
 # $connect_timeout::                   How long the server will wait for a response to a connection attempt
@@ -230,7 +243,7 @@
 #                                      can query the certificate-status endpoint
 #                                      Defaults to [ '127.0.0.1', '::1', $::ipaddress ]
 
-# $server_custom_trusted_oid_mapping:: A hash of custom trusted oid mappings. Defaults to undef
+# $custom_trusted_oid_mapping::        A hash of custom trusted oid mappings.
 #                                      Example: { 1.3.6.1.4.1.34380.1.2.1.1 => { shortname => 'myshortname' } }
 #
 # $admin_api_whitelist::               The whitelist of clients that
@@ -243,6 +256,12 @@
 # $use_legacy_auth_conf::              Should the puppetserver use the legacy puppet auth.conf?
 #                                      Defaults to false (the puppetserver will use its own conf.d/auth.conf)
 #
+# $check_for_updates::                 Should the puppetserver phone home to check for available updates?
+#
+# $environment_class_cache_enabled::   Enable environment class cache in conjunction with the use of the
+#                                      environment_classes API.
+#
+#
 # $allow_header_cert_info::            Allow client authentication over HTTP Headers
 #                                      Defaults to false, is also activated by the $http setting
 #
@@ -283,6 +302,31 @@
 # $ca_enable_infra_crl::               Enable the separate CRL for Puppet infrastructure nodes
 #                                      Defaults to false
 #
+# $acceptor_threads::                  This sets the number of threads that the webserver will dedicate to accepting
+#                                      socket connections for unencrypted HTTP traffic. If not provided, the webserver
+#                                      defaults to the number of virtual cores on the host divided by 8, with a minimum
+#                                      of 1 and maximum of 4.
+#
+# $selector_threads::                  This sets the number of selectors that the webserver will dedicate to processing
+#                                      events on connected sockets for unencrypted HTTPS traffic. If not provided,
+#                                      the webserver defaults to the minimum of: virtual cores on the host divided by 2
+#                                      or max-threads divided by 16, with a minimum of 1.
+#
+# $max_threads::                       This sets the maximum number of threads assigned to responding to HTTP and/or
+#                                      HTTPS requests for a single webserver, effectively changing how many
+#                                      concurrent requests can be made at one time. If not provided, the
+#                                      webserver defaults to 200.
+#
+# $ssl_acceptor_threads::              This sets the number of threads that the webserver will dedicate to accepting
+#                                      socket connections for encrypted HTTPS traffic. If not provided, defaults to
+#                                      the number of virtual cores on the host divided by 8, with a minimum of 1 and maximum of 4.
+#
+# $ssl_selector_threads::              This sets the number of selectors that the webserver will dedicate to processing
+#                                      events on connected sockets for encrypted HTTPS traffic. Defaults to the number of
+#                                      virtual cores on the host divided by 2, with a minimum of 1 and maximum of 4.
+#                                      The number of selector threads actually used by Jetty is twice the number of selectors
+#                                      requested. For example, if a value of 3 is specified for the ssl-selector-threads setting,
+#                                      Jetty will actually use 6 selector threads.
 class puppet::server(
   Variant[Boolean, Stdlib::Absolutepath] $autosign = $::puppet::autosign,
   Array[String] $autosign_entries = $::puppet::autosign_entries,
diff --git a/manifests/server/config.pp b/manifests/server/config.pp
@@ -1,4 +1,5 @@
 # Set up the puppet server config
+# @api private
 class puppet::server::config inherits puppet::config {
   contain 'puppet::server::puppetserver'
   unless empty($::puppet::server::puppetserver_vardir) {
diff --git a/manifests/server/enc.pp b/manifests/server/enc.pp
@@ -1,3 +1,5 @@
+# Set up the ENC config
+# @api private
 class puppet::server::enc(
   $enc_path = $::puppet::server::external_nodes
 ) {
diff --git a/manifests/server/install.pp b/manifests/server/install.pp
@@ -1,4 +1,5 @@
 # Install the puppet server
+# @api private
 class puppet::server::install {
 
   # Mirror the relationship, as defined() is parse-order dependent
diff --git a/manifests/server/puppetserver.pp b/manifests/server/puppetserver.pp
@@ -1,62 +1,58 @@
-# == Class: puppet::server::puppetserver
-#
 # Configures the puppetserver jvm configuration file using augeas.
 #
-# === Parameters:
-#
-# * `java_bin`
-# Path to the java executable to use
+# @api private
 #
-# * `config`
-# Path to the jvm configuration file.
-# This file is usually either /etc/default/puppetserver or
-# /etc/sysconfig/puppetserver depending on your *nix flavor.
+# @param java_bin
+#   Path to the java executable to use
 #
-# * `jvm_min_heap_size`
-# Translates into the -Xms option and is added to the JAVA_ARGS
+# @param config
+#   Path to the jvm configuration file.
+#   This file is usually either /etc/default/puppetserver or
+#   /etc/sysconfig/puppetserver depending on your *nix flavor.
 #
-# * `jvm_max_heap_size`
-# Translates into the -Xmx option and is added to the JAVA_ARGS
+# @param jvm_min_heap_size
+#   Translates into the -Xms option and is added to the JAVA_ARGS
 #
-# * `jvm_extra_args`
-# Custom options to pass through to the java binary. These get added to
-# the end of the JAVA_ARGS variable
+# @param jvm_max_heap_size
+#   Translates into the -Xmx option and is added to the JAVA_ARGS
 #
-# * `jvm_cli_args`
-# Custom options to pass through to the java binary when using a
-# puppetserver subcommand, (eg puppetserver gem). These get used
-# in the JAVA_ARGS_CLI variable.
+# @param jvm_extra_args
+#   Custom options to pass through to the java binary. These get added to
+#   the end of the JAVA_ARGS variable
 #
-# * `server_puppetserver_dir`
-# Puppetserver config directory
+# @param jvm_cli_args
+#   Custom options to pass through to the java binary when using a
+#   puppetserver subcommand, (eg puppetserver gem). These get used
+#   in the JAVA_ARGS_CLI variable.
 #
-# * `server_puppetserver_vardir`
-# Puppetserver var directory
+# @param server_puppetserver_dir
+#   Puppetserver config directory
 #
-# * `server_jruby_gem_home`
-# Puppetserver jruby gemhome
+# @param server_puppetserver_vardir
+#   Puppetserver var directory
 #
-# * `server_cipher_suites`
-# Puppetserver array of acceptable ciphers
+# @param server_jruby_gem_home
+#   Puppetserver jruby gemhome
 #
-# * `server_ssl_protocols`
-# Puppetserver array of acceptable ssl protocols
+# @param server_cipher_suites
+#   Puppetserver array of acceptable ciphers
 #
-# * `server_max_active_instances`
-# Puppetserver number of max jruby instances
+# @param server_ssl_protocols
+#   Puppetserver array of acceptable ssl protocols
 #
-# * `server_max_requests_per_instance`
-# Puppetserver number of max requests per jruby instance
+# @param server_max_active_instances
+#   Puppetserver number of max jruby instances
 #
-# * `server_max_queued_requests`
-# The maximum number of requests that may be queued waiting
-# to borrow a JRuby from the pool.
+# @param server_max_requests_per_instance
+#   Puppetserver number of max requests per jruby instance
 #
-# * `server_max_retry_delay`
-# Sets the upper limit for the random sleep set as a Retry-After
-# header on 503 responses returned when max-queued-requests is enabled.
+# @param server_max_queued_requests
+#   The maximum number of requests that may be queued waiting
+#   to borrow a JRuby from the pool.
 #
-# === Example
+# @param server_max_retry_delay
+#   Sets the upper limit for the random sleep set as a Retry-After
+#   header on 503 responses returned when max-queued-requests is enabled.
 #
 # @example
 #
diff --git a/manifests/server/service.pp b/manifests/server/service.pp
@@ -3,6 +3,7 @@
 # @param $enable Whether to enable the service or not
 # @param $service_name The service name to manage
 #
+# @api private
 class puppet::server::service(
   Boolean $enable = true,
   String $service_name = 'puppetserver',

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`# Puppet agent`
	`2`	`+# @api private`
`2`	`3`	`class puppet::agent {`
`3`	`4`	`contain puppet::agent::install`
`4`	`5`	`contain puppet::agent::config`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`# Puppet agent configuration`
	`2`	`+# @api private`
`2`	`3`	`class puppet::agent::config inherits puppet::config {`
`3`	`4`	`puppet::config::agent{`
`4`	`5`	`'classfile': value => $::puppet::classfile;`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Set up running the agent via cron`
	`2`	`+# @api private`
`1`	`3`	`class puppet::agent::service::cron (`
`2`	`4`	`Boolean $enabled = false,`
`3`	`5`	`) {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Set up running the agent as a daemon`
	`2`	`+# @api private`
`1`	`3`	`class puppet::agent::service::daemon (`
`2`	`4`	`Boolean $enabled = false,`
`3`	`5`	`) {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Set up running the agent via a systemd timer`
	`2`	`+# @api private`
`1`	`3`	`class puppet::agent::service::systemd (`
`2`	`4`	`Boolean $enabled = false,`
`3`	`5`	`) {`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`# Set up the puppet config`
	`2`	`+# @api private`
`2`	`3`	`class puppet::config(`
`3`	`4`	`$allow_any_crl_auth = $::puppet::allow_any_crl_auth,`
`4`	`5`	`$auth_allowed = $::puppet::auth_allowed,`