From c58c704834ebec56abc9b8302df5e82bd7fe8f79 Mon Sep 17 00:00:00 2001 From: Aria Li Date: Fri, 25 Aug 2023 12:28:37 -0700 Subject: [PATCH] (maint) Update documentation for voxpupuli-puppet-lint-plugins --- REFERENCE.md | 668 +++++++++--------- lib/puppet/functions/any_resources_of_type.rb | 5 + .../parser/functions/uri_host_from_string.rb | 2 +- .../functions/windows_msi_installargs.rb | 2 +- .../parser/functions/windows_native_path.rb | 3 +- .../puppet_agent_end_run.rb | 2 + .../puppet_agent_upgrade_error.rb | 6 + manifests/configure.pp | 3 + manifests/init.pp | 54 +- manifests/install.pp | 14 +- manifests/install/darwin.pp | 12 + manifests/install/solaris.pp | 12 + manifests/install/suse.pp | 12 + manifests/install/windows.pp | 13 + manifests/osfamily/aix.pp | 2 + manifests/osfamily/darwin.pp | 2 + manifests/osfamily/debian.pp | 2 + manifests/osfamily/redhat.pp | 2 + manifests/osfamily/solaris.pp | 2 + manifests/osfamily/suse.pp | 2 + manifests/osfamily/windows.pp | 2 + manifests/prepare.pp | 3 +- manifests/prepare/package.pp | 4 +- manifests/prepare/puppet_config.pp | 4 + types/arch.pp | 1 + types/config.pp | 1 + 26 files changed, 467 insertions(+), 368 deletions(-) diff --git a/REFERENCE.md b/REFERENCE.md index 8650e9ce0..e77345279 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -6,25 +6,25 @@ ### Classes -* [`puppet_agent`](#puppet_agent): == Class: puppet_agent Upgrades Puppet 4 and newer to the requested version. === Parameters [arch] The package architecture. Defaults to -* [`puppet_agent::configure`](#puppet_agent--configure) -* [`puppet_agent::install`](#puppet_agent--install): == Class puppet_agent::install This class is called from puppet_agent for install. === Parameters [version] The puppet-agent version to -* [`puppet_agent::install::darwin`](#puppet_agent--install--darwin): == Class puppet_agent::install::darwin Private class called from puppet_agent class Manage the install process for Darwin OSes specifically -* [`puppet_agent::install::solaris`](#puppet_agent--install--solaris): == Class puppet_agent::install::solaris Private class called from puppet_agent class Manage the install process for solaris specifically -* [`puppet_agent::install::suse`](#puppet_agent--install--suse): == Class puppet_agent::install::suse Private class called from puppet_agent class Manage the install process for SUSE OSes specifically -* [`puppet_agent::install::windows`](#puppet_agent--install--windows): == Class puppet_agent::install::windows Private class called from puppet_agent class Manage the install process for windows specifically -* [`puppet_agent::osfamily::aix`](#puppet_agent--osfamily--aix) -* [`puppet_agent::osfamily::darwin`](#puppet_agent--osfamily--darwin) -* [`puppet_agent::osfamily::debian`](#puppet_agent--osfamily--debian) -* [`puppet_agent::osfamily::redhat`](#puppet_agent--osfamily--redhat) -* [`puppet_agent::osfamily::solaris`](#puppet_agent--osfamily--solaris) -* [`puppet_agent::osfamily::suse`](#puppet_agent--osfamily--suse) -* [`puppet_agent::osfamily::windows`](#puppet_agent--osfamily--windows) -* [`puppet_agent::params`](#puppet_agent--params): == Class puppet_agent::params This class is meant to be called from puppet_agent It sets variables according to platform. -* [`puppet_agent::prepare`](#puppet_agent--prepare): == Class puppet_agent::prepare This class is called from puppet_agent to prepare for the upgrade. === Parameters [version] The puppet-ag -* [`puppet_agent::prepare::package`](#puppet_agent--prepare--package): == Class puppet_agent::prepare::package The only job this class has is to ensure that the correct puppet-agent package is downloaded locally -* [`puppet_agent::prepare::puppet_config`](#puppet_agent--prepare--puppet_config): == Class puppet_agent::prepare::puppet_config Private class called from puppet_agent::prepare class -* [`puppet_agent::service`](#puppet_agent--service): == Class puppet_agent::service This class is meant to be called from puppet_agent. It ensures that managed services are running. +* [`puppet_agent`](#puppet_agent): == Class: puppet_agent Upgrades Puppet 4 and newer to the requested version. === Parameters example for clients in dmz:s that need to us +* [`puppet_agent::configure`](#puppet_agentconfigure): This class uses $puppet_agent::config to manage settings in +* [`puppet_agent::install`](#puppet_agentinstall): == Class puppet_agent::install This class is called from puppet_agent for install. === Parameters +* [`puppet_agent::install::darwin`](#puppet_agentinstalldarwin): == Class puppet_agent::install::darwin Private class called from puppet_agent class Manage the install process for Darwin OSes specifically +* [`puppet_agent::install::solaris`](#puppet_agentinstallsolaris): == Class puppet_agent::install::solaris Private class called from puppet_agent class Manage the install process for solaris specifically = +* [`puppet_agent::install::suse`](#puppet_agentinstallsuse): == Class puppet_agent::install::suse Private class called from puppet_agent class Manage the install process for SUSE OSes specifically == +* [`puppet_agent::install::windows`](#puppet_agentinstallwindows): == Class puppet_agent::install::windows Private class called from puppet_agent class Manage the install process for windows specifically = +* [`puppet_agent::osfamily::aix`](#puppet_agentosfamilyaix): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::darwin`](#puppet_agentosfamilydarwin): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::debian`](#puppet_agentosfamilydebian): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::redhat`](#puppet_agentosfamilyredhat): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::solaris`](#puppet_agentosfamilysolaris): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::suse`](#puppet_agentosfamilysuse): This private class is used to determine the puppet-agent package +* [`puppet_agent::osfamily::windows`](#puppet_agentosfamilywindows): This private class is used to determine the puppet-agent package +* [`puppet_agent::params`](#puppet_agentparams): == Class puppet_agent::params This class is meant to be called from puppet_agent It sets variables according to platform. +* [`puppet_agent::prepare`](#puppet_agentprepare): == Class puppet_agent::prepare This class is called from puppet_agent to prepare for the upgrade. === Parameters +* [`puppet_agent::prepare::package`](#puppet_agentpreparepackage): == Class puppet_agent::prepare::package The only job this class has is to ensure that the correct puppet-agent package is downloaded locally +* [`puppet_agent::prepare::puppet_config`](#puppet_agentpreparepuppet_config): == Class puppet_agent::prepare::puppet_config Private class called from puppet_agent::prepare class === Parameters +* [`puppet_agent::service`](#puppet_agentservice): == Class puppet_agent::service This class is meant to be called from puppet_agent. It ensures that managed services are running. ### Resource types @@ -33,16 +33,16 @@ ### Functions -* [`any_resources_of_type`](#any_resources_of_type) -* [`uri_host_from_string`](#uri_host_from_string): Return a uri host from a string -* [`windows_msi_installargs`](#windows_msi_installargs): Return the $install_options parameter as a string usable in an msiexec command -* [`windows_native_path`](#windows_native_path): Return a windows native path +* [`any_resources_of_type`](#any_resources_of_type): A function used to determine if there are any +* [`uri_host_from_string`](#uri_host_from_string) +* [`windows_msi_installargs`](#windows_msi_installargs) +* [`windows_native_path`](#windows_native_path) ### Data types -* [`Puppet_agent::Arch`](#Puppet_agent--Arch) -* [`Puppet_agent::Config`](#Puppet_agent--Config) -* [`Puppet_agent::Config_setting`](#Puppet_agent--Config_setting): An enumerated list of settings which are permitted to be managed by this module. +* [`Puppet_agent::Arch`](#puppet_agentarch): This type stores all possible architecture patterns +* [`Puppet_agent::Config`](#puppet_agentconfig): This Puppet type alias +* [`Puppet_agent::Config_setting`](#puppet_agentconfig_setting): An enumerated list of settings which are permitted to be managed by this module. ### Tasks @@ -58,7 +58,7 @@ ### Plans -* [`puppet_agent::run`](#puppet_agent--run): Starts a Puppet agent run on the specified targets. Note: This plan may cause issues when run in Puppet Enterprise. +* [`puppet_agent::run`](#puppet_agentrun): Starts a Puppet agent run on the specified targets. Note: This plan may cause issues when run in Puppet Enterprise. ## Classes @@ -70,354 +70,309 @@ Upgrades Puppet 4 and newer to the requested version. === Parameters -[arch] - The package architecture. Defaults to the architecture fact. -[collection] - The Puppet Collection to track. Defaults to 'PC1'. -[is_pe] - Install from Puppet Enterprise repos. Enabled if communicating with a PE master. -[manage_pki_dir] - Whether or not to manage the /etc/pki directory. Defaults to true. - Managing the /etc/pki directory inside the puppet_agent module can be problematic for - organizations that manage gpg keys and settings in other modules. -[manage_repo] - Boolean to determine whether to configure repositories - This is intended to provide the ability to disable configuring a local repo - in support of systems that manage external repositories (i.e. spacewalk/satellite) - to enable users to add the proper packages to their internal repos - and to utilize default package providers for the install -[package_name] - The package to upgrade to, i.e. `puppet-agent`. -[package_version] - The package version to upgrade to. Explicitly specify the version to upgrade to, - or set to 'auto' to specify the version of the compiling master. -[service_names] - An array of services to start, normally `puppet`. - None will be started if the array is empty. -[source] - **INCLUDED FOR COMPATIBILITY WITH MODULE VERSIONS 1.0/2.0. PREFER USE OF "absolute_source", - "apt_source", "deb_source" etc. OVER USE OF "source".** - - The location to find packages. Replaces base URL for unix/MacOS agents, used as fully - qualified path in windows -[absolute_source] - The exact location of the package to install. The entire path to the package must be - provided with this parameter. -[yum_source] - Base URL of the location of mirrors of yum.puppet.com downloads sites. Directories under - the URL "yum_source" should match the structure of the yum.puppet.com -[apt_source] - Base URL of the location of mirrors of apt.puppet.com downloads sites. Directories under - the URL "apt_source" should match the structure of the apt.puppet.com -[mac_source] - Base URL of the location of mirrors of downloads.puppet.com downloads site that serves - MacOS packages. Directories under the URL "mac_source" should match the structure of the - downloads.puppet.com site -[windows_source] - Base URL of the location of mirrors of downloads.puppet.com downloads site that serves - Windows packages. Directories under the URL "windows_source" should match the structure of - the downloads.puppet.com site -[solaris_source] - Base URL of the location of a mirror for Solaris packages. Currently, solaris packages can - only be made available by using puppetlabs-pe_repo. This means the mirror must be of a - PE master package serve. -[aix_source] - Base URL of the location of a mirror for AIX packages. Currently, AIX packages can - only be made available by using puppetlabs-pe_repo. This means the mirror must be of a - PE master package serve. -[use_alternate_sources] - **ONLY APPLICABLE WHEN WORKING WITH PE INSTALLTIONS** - When set to true will force downloads to come from the values of $apt_source, $deb_source - $mac_source etc. rather than from the default PE master package serve. Note that this will - also force downloads to ignore alternate_pe_source -[alternate_pe_source] - Base URL of the location where packages are located in the same structure that's served - by a PE master (the directory structure in PE for serving packages is created by the - puppetlabs-pe_repo module). The general structure served by PE is: - /packages/${pe_server_version}/${platform_tag}/${package_name} -[install_dir] - The directory the puppet agent should be installed to. This is only applicable for - windows operating systems. This only applies when upgrading the agent to a new - version; it will not cause re-installation of the same version to a new location. -[install_options] - An array of additional options to pass when installing puppet-agent. Each option in - the array can either be a string or a hash. Each option will automatically be quoted - when passed to the install command. With Windows packages, note that file paths in an - install option must use backslashes. (Since install options are passed directly to - the installation command, forward slashes won't be automatically converted like they - are in `file` resources.) Note also that backslashes in double-quoted strings _must_ - be escaped and backslashes in single-quoted strings _can_ be escaped. -[msi_move_locked_files] - This is only applicable for Windows operating systems. There may be instances where - file locks cause unncessary service restarts. By setting to true, the module - will move files prior to installation that are known to cause file locks. -[wait_for_pxp_agent_exit] - This parameter is only applicable for Windows operating systems and pertains to the - /files/install_agent.ps1 script. This parameterizes the module to define the wait time - for the PXP agent to end successfully. The default value is set 2 minutes. -[wait_for_puppet_run] - This parameter is only applicable for Windows operating systems and pertains to the - /files/install_agent.ps1 script. This parameterizes the module to define the wait time - for the current puppet agent run to end successfully. The default value is set 2 minutes. -[config] - An array of configuration data to enforce. Each configuration data item must be a - Puppet_agent::Config hash, which has keys for puppet.conf section, setting, and value. - This parameter is constrained to managing only a predetermined set of configuration - settings, e.g. runinterval. + example for clients in dmz:s that need to use proxy to reach the repo + provided by puppetserver. #### Parameters The following parameters are available in the `puppet_agent` class: -* [`arch`](#-puppet_agent--arch) -* [`collection`](#-puppet_agent--collection) -* [`is_pe`](#-puppet_agent--is_pe) -* [`manage_pki_dir`](#-puppet_agent--manage_pki_dir) -* [`manage_repo`](#-puppet_agent--manage_repo) -* [`package_name`](#-puppet_agent--package_name) -* [`package_version`](#-puppet_agent--package_version) -* [`service_names`](#-puppet_agent--service_names) -* [`source`](#-puppet_agent--source) -* [`absolute_source`](#-puppet_agent--absolute_source) -* [`yum_source`](#-puppet_agent--yum_source) -* [`apt_source`](#-puppet_agent--apt_source) -* [`mac_source`](#-puppet_agent--mac_source) -* [`windows_source`](#-puppet_agent--windows_source) -* [`solaris_source`](#-puppet_agent--solaris_source) -* [`aix_source`](#-puppet_agent--aix_source) -* [`use_alternate_sources`](#-puppet_agent--use_alternate_sources) -* [`alternate_pe_source`](#-puppet_agent--alternate_pe_source) -* [`install_dir`](#-puppet_agent--install_dir) -* [`disable_proxy`](#-puppet_agent--disable_proxy) -* [`proxy`](#-puppet_agent--proxy) -* [`install_options`](#-puppet_agent--install_options) -* [`skip_if_unavailable`](#-puppet_agent--skip_if_unavailable) -* [`msi_move_locked_files`](#-puppet_agent--msi_move_locked_files) -* [`wait_for_pxp_agent_exit`](#-puppet_agent--wait_for_pxp_agent_exit) -* [`wait_for_puppet_run`](#-puppet_agent--wait_for_puppet_run) -* [`config`](#-puppet_agent--config) - -##### `arch` +* [`arch`](#arch) +* [`collection`](#collection) +* [`is_pe`](#is_pe) +* [`manage_pki_dir`](#manage_pki_dir) +* [`manage_repo`](#manage_repo) +* [`package_name`](#package_name) +* [`package_version`](#package_version) +* [`service_names`](#service_names) +* [`source`](#source) +* [`absolute_source`](#absolute_source) +* [`yum_source`](#yum_source) +* [`apt_source`](#apt_source) +* [`mac_source`](#mac_source) +* [`windows_source`](#windows_source) +* [`solaris_source`](#solaris_source) +* [`aix_source`](#aix_source) +* [`use_alternate_sources`](#use_alternate_sources) +* [`alternate_pe_source`](#alternate_pe_source) +* [`install_dir`](#install_dir) +* [`install_options`](#install_options) +* [`msi_move_locked_files`](#msi_move_locked_files) +* [`wait_for_pxp_agent_exit`](#wait_for_pxp_agent_exit) +* [`wait_for_puppet_run`](#wait_for_puppet_run) +* [`config`](#config) +* [`proxy`](#proxy) +* [`skip_if_unavailable`](#skip_if_unavailable) +* [`disable_proxy`](#disable_proxy) + +##### `arch` Data type: `Any` - +The package architecture. Defaults to the architecture fact. Default value: `$facts['os']['architecture']` -##### `collection` +##### `collection` Data type: `Any` - +The Puppet Collection to track. Defaults to 'PC1'. Default value: `$::puppet_agent::params::collection` -##### `is_pe` +##### `is_pe` Data type: `Any` - +Install from Puppet Enterprise repos. Enabled if communicating with a PE master. Default value: `$::puppet_agent::params::_is_pe` -##### `manage_pki_dir` +##### `manage_pki_dir` Data type: `Any` +Whether or not to manage the /etc/pki directory. Defaults to true. +Managing the /etc/pki directory inside the puppet_agent module can be problematic for +organizations that manage gpg keys and settings in other modules. +Default value: ``true`` -Default value: `true` - -##### `manage_repo` +##### `manage_repo` Data type: `Any` +Boolean to determine whether to configure repositories +This is intended to provide the ability to disable configuring a local repo +in support of systems that manage external repositories (i.e. spacewalk/satellite) +to enable users to add the proper packages to their internal repos +and to utilize default package providers for the install +Default value: ``true`` -Default value: `true` - -##### `package_name` +##### `package_name` Data type: `Any` - +The package to upgrade to, i.e. `puppet-agent`. Default value: `'puppet-agent'` -##### `package_version` +##### `package_version` Data type: `Any` +The package version to upgrade to. Explicitly specify the version to upgrade to, +or set to 'auto' to specify the version of the compiling master. +Default value: ``undef`` -Default value: `undef` - -##### `service_names` +##### `service_names` Data type: `Any` - +An array of services to start, normally `puppet`. +None will be started if the array is empty. Default value: `$::puppet_agent::params::service_names` -##### `source` +##### `source` Data type: `Any` +**INCLUDED FOR COMPATIBILITY WITH MODULE VERSIONS 1.0/2.0. PREFER USE OF "absolute_source", +"apt_source", "deb_source" etc. OVER USE OF "source".** +The location to find packages. Replaces base URL for unix/MacOS agents, used as fully +qualified path in windows -Default value: `undef` +Default value: ``undef`` -##### `absolute_source` +##### `absolute_source` Data type: `Any` +The exact location of the package to install. The entire path to the package must be +provided with this parameter. +Default value: ``undef`` -Default value: `undef` - -##### `yum_source` +##### `yum_source` Data type: `Any` - +Base URL of the location of mirrors of yum.puppet.com downloads sites. Directories under +the URL "yum_source" should match the structure of the yum.puppet.com Default value: `'http://yum.puppet.com'` -##### `apt_source` +##### `apt_source` Data type: `Any` - +Base URL of the location of mirrors of apt.puppet.com downloads sites. Directories under +the URL "apt_source" should match the structure of the apt.puppet.com Default value: `'https://apt.puppet.com'` -##### `mac_source` +##### `mac_source` Data type: `Any` - +Base URL of the location of mirrors of downloads.puppet.com downloads site that serves +MacOS packages. Directories under the URL "mac_source" should match the structure of the +downloads.puppet.com site Default value: `'https://downloads.puppet.com'` -##### `windows_source` +##### `windows_source` Data type: `Any` - +Base URL of the location of mirrors of downloads.puppet.com downloads site that serves +Windows packages. Directories under the URL "windows_source" should match the structure of +the downloads.puppet.com site Default value: `'https://downloads.puppet.com'` -##### `solaris_source` +##### `solaris_source` Data type: `Any` - +Base URL of the location of a mirror for Solaris packages. Currently, solaris packages can +only be made available by using puppetlabs-pe_repo. This means the mirror must be of a +PE master package serve. Default value: `'puppet:///pe_packages'` -##### `aix_source` +##### `aix_source` Data type: `Any` - +Base URL of the location of a mirror for AIX packages. Currently, AIX packages can +only be made available by using puppetlabs-pe_repo. This means the mirror must be of a +PE master package serve. Default value: `'puppet:///pe_packages'` -##### `use_alternate_sources` +##### `use_alternate_sources` Data type: `Any` +**ONLY APPLICABLE WHEN WORKING WITH PE INSTALLTIONS** +When set to true will force downloads to come from the values of $apt_source, $deb_source +$mac_source etc. rather than from the default PE master package serve. Note that this will +also force downloads to ignore alternate_pe_source +Default value: ``false`` -Default value: `false` - -##### `alternate_pe_source` +##### `alternate_pe_source` Data type: `Any` +Base URL of the location where packages are located in the same structure that's served +by a PE master (the directory structure in PE for serving packages is created by the +puppetlabs-pe_repo module). The general structure served by PE is: +/packages/${pe_server_version}/${platform_tag}/${package_name} +Default value: ``undef`` -Default value: `undef` - -##### `install_dir` +##### `install_dir` Data type: `Optional[Stdlib::Absolutepath]` +The directory the puppet agent should be installed to. This is only applicable for +windows operating systems. This only applies when upgrading the agent to a new +version; it will not cause re-installation of the same version to a new location. +Default value: ``undef`` -Default value: `undef` - -##### `disable_proxy` +##### `install_options` Data type: `Any` +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. +Default value: `[]` -Default value: `false` - -##### `proxy` +##### `msi_move_locked_files` Data type: `Any` +This is only applicable for Windows operating systems. There may be instances where +file locks cause unncessary service restarts. By setting to true, the module +will move files prior to installation that are known to cause file locks. +Default value: ``false`` -Default value: `undef` - -##### `install_options` +##### `wait_for_pxp_agent_exit` Data type: `Any` +This parameter is only applicable for Windows operating systems and pertains to the +/files/install_agent.ps1 script. This parameterizes the module to define the wait time +for the PXP agent to end successfully. The default value is set 2 minutes. +Default value: ``undef`` -Default value: `[]` - -##### `skip_if_unavailable` +##### `wait_for_puppet_run` Data type: `Any` +This parameter is only applicable for Windows operating systems and pertains to the +/files/install_agent.ps1 script. This parameterizes the module to define the wait time +for the current puppet agent run to end successfully. The default value is set 2 minutes. +Default value: ``undef`` -Default value: `'absent'` - -##### `msi_move_locked_files` - -Data type: `Any` +##### `config` +Data type: `Array[Puppet_agent::Config]` +An array of configuration data to enforce. Each configuration data item must be a +Puppet_agent::Config hash, which has keys for puppet.conf section, setting, and value. +This parameter is constrained to managing only a predetermined set of configuration +settings, e.g. runinterval. -Default value: `false` +Default value: `[]` -##### `wait_for_pxp_agent_exit` +##### `proxy` Data type: `Any` +This is to be able to configure yum-repo with proxy, needed for +Default value: ``undef`` -Default value: `undef` - -##### `wait_for_puppet_run` +##### `skip_if_unavailable` Data type: `Any` -Default value: `undef` +Default value: `'absent'` -##### `config` +##### `disable_proxy` -Data type: `Array[Puppet_agent::Config]` +Data type: `Any` -Default value: `[]` +Default value: ``false`` -### `puppet_agent::configure` +### `puppet_agent::configure` -The puppet_agent::configure class. +puppet.conf, and will always be present. It does not require management of +the agent package. -### `puppet_agent::install` +### `puppet_agent::install` == Class puppet_agent::install @@ -425,42 +380,46 @@ This class is called from puppet_agent for install. === Parameters -[version] - The puppet-agent version to install. - #### Parameters The following parameters are available in the `puppet_agent::install` class: -* [`package_version`](#-puppet_agent--install--package_version) -* [`install_dir`](#-puppet_agent--install--install_dir) -* [`install_options`](#-puppet_agent--install--install_options) +* [`package_version`](#package_version) +* [`install_dir`](#install_dir) +* [`install_options`](#install_options) -##### `package_version` +##### `package_version` Data type: `Any` - +The puppet-agent version to install. Default value: `'present'` -##### `install_dir` +##### `install_dir` Data type: `Any` +The directory the puppet agent should be installed to. This is only applicable for +windows operating systems. +Default value: ``undef`` -Default value: `undef` - -##### `install_options` +##### `install_options` Data type: `Any` - +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. Default value: `[]` -### `puppet_agent::install::darwin` +### `puppet_agent::install::darwin` == Class puppet_agent::install::darwin @@ -468,28 +427,36 @@ Private class called from puppet_agent class Manage the install process for Darwin OSes specifically +=== Parameters + #### Parameters The following parameters are available in the `puppet_agent::install::darwin` class: -* [`package_version`](#-puppet_agent--install--darwin--package_version) -* [`install_options`](#-puppet_agent--install--darwin--install_options) +* [`package_version`](#package_version) +* [`install_options`](#install_options) -##### `package_version` +##### `package_version` Data type: `Any` +The puppet-agent version to install. - -##### `install_options` +##### `install_options` Data type: `Any` - +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. Default value: `[]` -### `puppet_agent::install::solaris` +### `puppet_agent::install::solaris` == Class puppet_agent::install::solaris @@ -497,28 +464,36 @@ Private class called from puppet_agent class Manage the install process for solaris specifically +=== Parameters + #### Parameters The following parameters are available in the `puppet_agent::install::solaris` class: -* [`package_version`](#-puppet_agent--install--solaris--package_version) -* [`install_options`](#-puppet_agent--install--solaris--install_options) +* [`package_version`](#package_version) +* [`install_options`](#install_options) -##### `package_version` +##### `package_version` Data type: `Any` +The puppet-agent version to install. - -##### `install_options` +##### `install_options` Data type: `Any` - +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. Default value: `[]` -### `puppet_agent::install::suse` +### `puppet_agent::install::suse` == Class puppet_agent::install::suse @@ -526,28 +501,36 @@ Private class called from puppet_agent class Manage the install process for SUSE OSes specifically +=== Parameters + #### Parameters The following parameters are available in the `puppet_agent::install::suse` class: -* [`package_version`](#-puppet_agent--install--suse--package_version) -* [`install_options`](#-puppet_agent--install--suse--install_options) +* [`package_version`](#package_version) +* [`install_options`](#install_options) -##### `package_version` +##### `package_version` Data type: `Any` +The puppet-agent version to install. - -##### `install_options` +##### `install_options` Data type: `Any` - +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. Default value: `[]` -### `puppet_agent::install::windows` +### `puppet_agent::install::windows` == Class puppet_agent::install::windows @@ -555,65 +538,74 @@ Private class called from puppet_agent class Manage the install process for windows specifically +=== Parameters + #### Parameters The following parameters are available in the `puppet_agent::install::windows` class: -* [`install_dir`](#-puppet_agent--install--windows--install_dir) -* [`install_options`](#-puppet_agent--install--windows--install_options) +* [`install_options`](#install_options) +* [`install_dir`](#install_dir) -##### `install_dir` +##### `install_options` Data type: `Any` +An array of additional options to pass when installing puppet-agent. Each option in +the array can either be a string or a hash. Each option will automatically be quoted +when passed to the install command. With Windows packages, note that file paths in an +install option must use backslashes. (Since install options are passed directly to +the installation command, forward slashes won't be automatically converted like they +are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +be escaped and backslashes in single-quoted strings _can_ be escaped. +Default value: `[]` -Default value: `undef` - -##### `install_options` +##### `install_dir` Data type: `Any` +The directory the puppet agent should be installed to. This is only applicable for +windows operating systems. +Default value: ``undef`` -Default value: `[]` - -### `puppet_agent::osfamily::aix` +### `puppet_agent::osfamily::aix` -The puppet_agent::osfamily::aix class. +location for AIX OSes -### `puppet_agent::osfamily::darwin` +### `puppet_agent::osfamily::darwin` -The puppet_agent::osfamily::darwin class. +location for Darwin OSes -### `puppet_agent::osfamily::debian` +### `puppet_agent::osfamily::debian` -The puppet_agent::osfamily::debian class. +location for Debain OSes -### `puppet_agent::osfamily::redhat` +### `puppet_agent::osfamily::redhat` -The puppet_agent::osfamily::redhat class. +location for RedHat OSes -### `puppet_agent::osfamily::solaris` +### `puppet_agent::osfamily::solaris` -The puppet_agent::osfamily::solaris class. +location for Solaris OSes -### `puppet_agent::osfamily::suse` +### `puppet_agent::osfamily::suse` -The puppet_agent::osfamily::suse class. +location for SUSE OSes -### `puppet_agent::osfamily::windows` +### `puppet_agent::osfamily::windows` -The puppet_agent::osfamily::windows class. +location for Windows OSes -### `puppet_agent::params` +### `puppet_agent::params` == Class puppet_agent::params This class is meant to be called from puppet_agent It sets variables according to platform. -### `puppet_agent::prepare` +### `puppet_agent::prepare` == Class puppet_agent::prepare @@ -621,24 +613,21 @@ This class is called from puppet_agent to prepare for the upgrade. === Parameters -[version] - The puppet-agent version to install. - #### Parameters The following parameters are available in the `puppet_agent::prepare` class: -* [`package_version`](#-puppet_agent--prepare--package_version) +* [`package_version`](#package_version) -##### `package_version` +##### `package_version` Data type: `Any` +The puppet-agent version to install. +Default value: ``undef`` -Default value: `undef` - -### `puppet_agent::prepare::package` +### `puppet_agent::prepare::package` == Class puppet_agent::prepare::package @@ -646,40 +635,41 @@ The only job this class has is to ensure that the correct puppet-agent package is downloaded locally for installation. This is used on platforms without package managers capable of working with a remote https repository. -[package_file_name] - The puppet-agent package file to retrieve from the master. +=== Parameters #### Parameters The following parameters are available in the `puppet_agent::prepare::package` class: -* [`source`](#-puppet_agent--prepare--package--source) +* [`source`](#source) -##### `source` +##### `source` Data type: `Any` -### `puppet_agent::prepare::puppet_config` +### `puppet_agent::prepare::puppet_config` == Class puppet_agent::prepare::puppet_config Private class called from puppet_agent::prepare class +=== Parameters + #### Parameters The following parameters are available in the `puppet_agent::prepare::puppet_config` class: -* [`package_version`](#-puppet_agent--prepare--puppet_config--package_version) +* [`package_version`](#package_version) -##### `package_version` +##### `package_version` Data type: `Any` +The puppet-agent version to install. - -### `puppet_agent::service` +### `puppet_agent::service` == Class puppet_agent::service @@ -711,16 +701,16 @@ Stops the current puppet run The following parameters are available in the `puppet_agent_end_run` type. -* [`name`](#-puppet_agent_end_run--name) -* [`provider`](#-puppet_agent_end_run--provider) +* [`name`](#name) +* [`provider`](#provider) -##### `name` +##### `name` namevar The desired puppet-agent version -##### `provider` +##### `provider` The specific backend to use for this `puppet_agent_end_run` resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. @@ -743,16 +733,16 @@ whether or not the error log exists The following parameters are available in the `puppet_agent_upgrade_error` type. -* [`name`](#-puppet_agent_upgrade_error--name) -* [`provider`](#-puppet_agent_upgrade_error--provider) +* [`name`](#name) +* [`provider`](#provider) -##### `name` +##### `name` namevar The name of the failure log to check for in puppet's $statedir. If this log exists the resource will fail. -##### `provider` +##### `provider` The specific backend to use for this `puppet_agent_upgrade_error` resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform. @@ -763,73 +753,77 @@ Puppet will usually discover the appropriate provider for your platform. Type: Ruby 4.x API -The any_resources_of_type function. +Puppet::Parser::Resource instances of the passed in resource type #### `any_resources_of_type(String $resource_type, Optional[Hash[Any, Any]] $parameters)` -The any_resources_of_type function. +Puppet::Parser::Resource instances of the passed in resource type -Returns: `Any` +Returns: `Boolean` Whether there are any instances of resource_type ##### `resource_type` Data type: `String` - +Resource type that is being looked for ##### `parameters` Data type: `Optional[Hash[Any, Any]]` - +Optional parameters ### `uri_host_from_string` Type: Ruby 3.x API -Return a uri host from a string +The uri_host_from_string function. #### `uri_host_from_string()` -Return a uri host from a string +The uri_host_from_string function. -Returns: `Any` +Returns: `Any` Return a uri host from a string ### `windows_msi_installargs` Type: Ruby 3.x API -Return the $install_options parameter as a string usable in an msiexec command +The windows_msi_installargs function. #### `windows_msi_installargs()` -Return the $install_options parameter as a string usable in an msiexec command +The windows_msi_installargs function. -Returns: `Any` +Returns: `String` Return the $install_options parameter as a string usable in an msiexec command ### `windows_native_path` Type: Ruby 3.x API -Return a windows native path +The windows_native_path function. #### `windows_native_path()` -Return a windows native path +The windows_native_path function. -Returns: `Any` +Returns: `Any` Return a windows native path ## Data types -### `Puppet_agent::Arch` +### `Puppet_agent::Arch` + +This type stores all possible architecture patterns -The Puppet_agent::Arch data type. +Alias of -Alias of `Pattern[/^x86$/, /^x64$/, /^i386$/, /^i86pc$/, /^amd64$/, /^x86_64$/, /^power$/, /^sun4[uv]$/, /^ppc64le$/, /^aarch64$/, /PowerPC_POWER/]` +```puppet +Pattern[/^x86$/, /^x64$/, /^i386$/, /^i86pc$/, /^amd64$/, /^x86_64$/, /^power$/, /^sun4[uv]$/, /^ppc64le$/, /^aarch64$/, /PowerPC_POWER/] +``` -### `Puppet_agent::Config` +### `Puppet_agent::Config` -The Puppet_agent::Config data type. +This Puppet type alias Alias of @@ -842,12 +836,16 @@ Variant[Struct[{ section => Enum[main, server, agent, user, master], Optional[ensure] => Enum[absent] }]] ``` -### `Puppet_agent::Config_setting` +### `Puppet_agent::Config_setting` An enumerated list of settings which are permitted to be managed by this module. -Alias of `Enum[agent_catalog_run_lockfile, agent_disabled_lockfile, allow_duplicate_certs, always_retry_plugins, autoflush, autosign, basemodulepath, binder_config, bucketdir, ca_fingerprint, ca_name, ca_port, ca_server, ca_ttl, cacert, cacrl, cadir, cakey, capub, catalog_cache_terminus, catalog_terminus, cert_inventory, certdir, certificate_revocation, certname, ciphers, classfile, client_datadir, clientbucketdir, clientyamldir, code, codedir, color, confdir, config, config_file_name, config_version, configprint, crl_refresh_interval, csr_attributes, csrdir, daemonize, data_binding_terminus, default_file_terminus, default_manifest, default_schedules, deviceconfdir, deviceconfig, devicedir, diff, diff_args, digest_algorithm, disable_i18n, disable_per_environment_manifest, disable_warnings, dns_alt_names, document_all, environment, environment_data_provider, environment_timeout, environment_timeout_mode, environmentpath, evaltrace, external_nodes, fact_name_length_soft_limit, fact_value_length_soft_limit, facterng, factpath, facts_terminus, fileserverconfig, filetimeout, forge_authorization, freeze_main, func3x_check, future_features, genconfig, genmanifest, graph, graphdir, group, hiera_config, hostcert, hostcrl, hostcsr, hostprivkey, hostpubkey, http_connect_timeout, http_debug, http_extra_headers, http_keepalive_timeout, http_proxy_host, http_proxy_password, http_proxy_port, http_proxy_user, http_read_timeout, http_user_agent, ignore_plugin_errors, ignoremissingtypes, ignoreschedules, key_type, keylength, lastrunfile, lastrunreport, ldapattrs, ldapbase, ldapclassattrs, ldapparentattr, ldappassword, ldapport, ldapserver, ldapssl, ldapstackedattrs, ldapstring, ldaptls, ldapuser, libdir, localcacert, localedest, localesource, log_level, logdest, logdir, manage_internal_file_permissions, manifest, masterport, max_deprecations, max_errors, max_warnings, maximum_uid, maxwaitforcert, maxwaitforlock, merge_dependency_warnings, mkusers, module_groups, module_repository, module_working_dir, modulepath, name, named_curve, no_proxy, node_cache_terminus, node_name, node_name_fact, node_name_value, node_terminus, noop, number_of_facts_soft_limit, onetime, passfile, path, payload_soft_limit, pidfile, plugindest, pluginfactdest, pluginfactsource, pluginsignore, pluginsource, pluginsync, postrun_command, preferred_serialization_format, prerun_command, preview_outputdir, priority, privatedir, privatekeydir, profile, publickeydir, puppet_trace, puppetdlog, report, report_include_system_store, report_port, report_server, reportdir, reports, reporturl, requestdir, resourcefile, rest_authconfig, resubmit_facts, rich_data, route_file, rundir, runinterval, runtimeout, serial, server, server_datadir, server_list, serverport, show_diff, signeddir, skip_tags, sourceaddress, splay, splaylimit, srv_domain, ssl_client_ca_auth, ssl_client_header, ssl_client_verify_header, ssl_lockfile, ssl_server_ca_auth, ssl_trust_store, ssldir, statedir, statefile, statettl, static_catalogs, storeconfigs, storeconfigs_backend, strict, strict_environment_mode, strict_hostname_checking, strict_variables, summarize, supported_checksum_types, syslogfacility, tags, tasks, top_level_facts_soft_limit, trace, transactionstorefile, trusted_external_command, trusted_oid_mapping_file, use_cached_catalog, use_srv_records, usecacheonfailure, user, vardir, vendormoduledir, versioned_environment_dirs, waitforcert, waitforlock, yamldir]` +Alias of + +```puppet +Enum[agent_catalog_run_lockfile, agent_disabled_lockfile, allow_duplicate_certs, always_retry_plugins, autoflush, autosign, basemodulepath, binder_config, bucketdir, ca_fingerprint, ca_name, ca_port, ca_server, ca_ttl, cacert, cacrl, cadir, cakey, capub, catalog_cache_terminus, catalog_terminus, cert_inventory, certdir, certificate_revocation, certname, ciphers, classfile, client_datadir, clientbucketdir, clientyamldir, code, codedir, color, confdir, config, config_file_name, config_version, configprint, crl_refresh_interval, csr_attributes, csrdir, daemonize, data_binding_terminus, default_file_terminus, default_manifest, default_schedules, deviceconfdir, deviceconfig, devicedir, diff, diff_args, digest_algorithm, disable_i18n, disable_per_environment_manifest, disable_warnings, dns_alt_names, document_all, environment, environment_data_provider, environment_timeout, environment_timeout_mode, environmentpath, evaltrace, external_nodes, fact_name_length_soft_limit, fact_value_length_soft_limit, facterng, factpath, facts_terminus, fileserverconfig, filetimeout, forge_authorization, freeze_main, func3x_check, future_features, genconfig, genmanifest, graph, graphdir, group, hiera_config, hostcert, hostcrl, hostcsr, hostprivkey, hostpubkey, http_connect_timeout, http_debug, http_extra_headers, http_keepalive_timeout, http_proxy_host, http_proxy_password, http_proxy_port, http_proxy_user, http_read_timeout, http_user_agent, ignore_plugin_errors, ignoremissingtypes, ignoreschedules, key_type, keylength, lastrunfile, lastrunreport, ldapattrs, ldapbase, ldapclassattrs, ldapparentattr, ldappassword, ldapport, ldapserver, ldapssl, ldapstackedattrs, ldapstring, ldaptls, ldapuser, libdir, localcacert, localedest, localesource, log_level, logdest, logdir, manage_internal_file_permissions, manifest, masterport, max_deprecations, max_errors, max_warnings, maximum_uid, maxwaitforcert, maxwaitforlock, merge_dependency_warnings, mkusers, module_groups, module_repository, module_working_dir, modulepath, name, named_curve, no_proxy, node_cache_terminus, node_name, node_name_fact, node_name_value, node_terminus, noop, number_of_facts_soft_limit, onetime, passfile, path, payload_soft_limit, pidfile, plugindest, pluginfactdest, pluginfactsource, pluginsignore, pluginsource, pluginsync, postrun_command, preferred_serialization_format, prerun_command, preview_outputdir, priority, privatedir, privatekeydir, profile, publickeydir, puppet_trace, puppetdlog, report, report_include_system_store, report_port, report_server, reportdir, reports, reporturl, requestdir, resourcefile, rest_authconfig, resubmit_facts, rich_data, route_file, rundir, runinterval, runtimeout, serial, server, server_datadir, server_list, serverport, show_diff, signeddir, skip_tags, sourceaddress, splay, splaylimit, srv_domain, ssl_client_ca_auth, ssl_client_header, ssl_client_verify_header, ssl_lockfile, ssl_server_ca_auth, ssl_trust_store, ssldir, statedir, statefile, statettl, static_catalogs, storeconfigs, storeconfigs_backend, strict, strict_environment_mode, strict_hostname_checking, strict_variables, summarize, supported_checksum_types, syslogfacility, tags, tasks, top_level_facts_soft_limit, trace, transactionstorefile, trusted_external_command, trusted_oid_mapping_file, use_cached_catalog, use_srv_records, usecacheonfailure, user, vardir, vendormoduledir, versioned_environment_dirs, waitforcert, waitforlock, yamldir] +``` ## Tasks @@ -1123,7 +1121,7 @@ Get the version of the Puppet agent package installed. Returns nothing if none p ## Plans -### `puppet_agent::run` +### `puppet_agent::run` Starts a Puppet agent run on the specified targets. Note: This plan may cause issues when run in Puppet Enterprise. @@ -1132,29 +1130,29 @@ Note: This plan may cause issues when run in Puppet Enterprise. The following parameters are available in the `puppet_agent::run` plan: -* [`targets`](#-puppet_agent--run--targets) -* [`noop`](#-puppet_agent--run--noop) -* [`environment`](#-puppet_agent--run--environment) +* [`targets`](#targets) +* [`noop`](#noop) +* [`environment`](#environment) -##### `targets` +##### `targets` Data type: `TargetSpec` The targets to start a Puppet agent run on. -##### `noop` +##### `noop` Data type: `Boolean` if true, all runs will use --noop -Default value: `false` +Default value: ``false`` -##### `environment` +##### `environment` Data type: `Optional[String[1]]` the desired puppet code environment -Default value: `undef` +Default value: ``undef`` diff --git a/lib/puppet/functions/any_resources_of_type.rb b/lib/puppet/functions/any_resources_of_type.rb index 4efa6503c..a9d0554d8 100644 --- a/lib/puppet/functions/any_resources_of_type.rb +++ b/lib/puppet/functions/any_resources_of_type.rb @@ -1,4 +1,9 @@ +# @summary A function used to determine if there are any +# Puppet::Parser::Resource instances of the passed in resource type Puppet::Functions.create_function(:any_resources_of_type, Puppet::Functions::InternalFunction) do + # @return [Boolean] Whether there are any instances of resource_type + # @param resource_type Resource type that is being looked for + # @param parameters Optional parameters dispatch :any_resources_of_type do scope_param diff --git a/lib/puppet/parser/functions/uri_host_from_string.rb b/lib/puppet/parser/functions/uri_host_from_string.rb index 78dfdcd4e..3f100ac17 100644 --- a/lib/puppet/parser/functions/uri_host_from_string.rb +++ b/lib/puppet/parser/functions/uri_host_from_string.rb @@ -2,7 +2,7 @@ module Puppet::Parser::Functions newfunction(:uri_host_from_string, arity: 1, type: :rvalue, doc: <<-EOS - Return a uri host from a string + @return Return a uri host from a string EOS ) do |args| uri = URI(args[0]) diff --git a/lib/puppet/parser/functions/windows_msi_installargs.rb b/lib/puppet/parser/functions/windows_msi_installargs.rb index 2160ff35a..6ca8e742e 100644 --- a/lib/puppet/parser/functions/windows_msi_installargs.rb +++ b/lib/puppet/parser/functions/windows_msi_installargs.rb @@ -1,6 +1,6 @@ module Puppet::Parser::Functions newfunction(:windows_msi_installargs, arity: 1, type: :rvalue, doc: <<-EOS - Return the $install_options parameter as a string usable in an msiexec command + @return [String] Return the $install_options parameter as a string usable in an msiexec command EOS ) do |args| install_args = args[0] diff --git a/lib/puppet/parser/functions/windows_native_path.rb b/lib/puppet/parser/functions/windows_native_path.rb index 3205729e2..0b0f490f1 100644 --- a/lib/puppet/parser/functions/windows_native_path.rb +++ b/lib/puppet/parser/functions/windows_native_path.rb @@ -1,6 +1,7 @@ module Puppet::Parser::Functions + # @return Windows native path newfunction(:windows_native_path, arity: 1, type: :rvalue, doc: <<-EOS - Return a windows native path + @return Return a windows native path EOS ) do |args| path = args[0] diff --git a/lib/puppet/provider/puppet_agent_end_run/puppet_agent_end_run.rb b/lib/puppet/provider/puppet_agent_end_run/puppet_agent_end_run.rb index 2df01c986..d49c1b096 100644 --- a/lib/puppet/provider/puppet_agent_end_run/puppet_agent_end_run.rb +++ b/lib/puppet/provider/puppet_agent_end_run/puppet_agent_end_run.rb @@ -1,4 +1,6 @@ + Puppet::Type.type(:puppet_agent_end_run).provide :puppet_agent_end_run do + desc '@summary This provider will stop the puppet agent run after a Puppet upgrade is performed' def end_run false end diff --git a/lib/puppet/provider/puppet_agent_upgrade_error/puppet_agent_upgrade_error.rb b/lib/puppet/provider/puppet_agent_upgrade_error/puppet_agent_upgrade_error.rb index 777d7b5ff..bf29fc0fb 100644 --- a/lib/puppet/provider/puppet_agent_upgrade_error/puppet_agent_upgrade_error.rb +++ b/lib/puppet/provider/puppet_agent_upgrade_error/puppet_agent_upgrade_error.rb @@ -1,4 +1,10 @@ Puppet::Type.type(:puppet_agent_upgrade_error).provide :puppet_agent_upgrade_error do + desc <<-DESC + @summary This provider checks an error log from a previous puppet agent + installation and will fail if the error log exists. The provider will delete + the existing error log before failing so that after the failed puppet run the + user can attempt the upgrade again. + DESC def ensure_notexist logfile = File.join(Puppet['statedir'].to_s, @resource[:name]) Puppet.debug "Checking for Error logfile #{logfile}" diff --git a/manifests/configure.pp b/manifests/configure.pp index e55f7a782..41f7a1081 100644 --- a/manifests/configure.pp +++ b/manifests/configure.pp @@ -1,3 +1,6 @@ +# @summary This class uses $puppet_agent::config to manage settings in +# puppet.conf, and will always be present. It does not require management of +# the agent package. class puppet_agent::configure { assert_private() diff --git a/manifests/init.pp b/manifests/init.pp index c3a97b525..359dd5963 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -4,76 +4,76 @@ # # === Parameters # -# [arch] +# @param arch # The package architecture. Defaults to the architecture fact. -# [collection] +# @param collection # The Puppet Collection to track. Defaults to 'PC1'. -# [is_pe] +# @param is_pe # Install from Puppet Enterprise repos. Enabled if communicating with a PE master. -# [manage_pki_dir] +# @param manage_pki_dir # Whether or not to manage the /etc/pki directory. Defaults to true. # Managing the /etc/pki directory inside the puppet_agent module can be problematic for # organizations that manage gpg keys and settings in other modules. -# [manage_repo] +# @param manage_repo # Boolean to determine whether to configure repositories # This is intended to provide the ability to disable configuring a local repo # in support of systems that manage external repositories (i.e. spacewalk/satellite) # to enable users to add the proper packages to their internal repos # and to utilize default package providers for the install -# [package_name] +# @param package_name # The package to upgrade to, i.e. `puppet-agent`. -# [package_version] +# @param package_version # The package version to upgrade to. Explicitly specify the version to upgrade to, # or set to 'auto' to specify the version of the compiling master. -# [service_names] +# @param service_names # An array of services to start, normally `puppet`. # None will be started if the array is empty. -# [source] +# @param source # **INCLUDED FOR COMPATIBILITY WITH MODULE VERSIONS 1.0/2.0. PREFER USE OF "absolute_source", # "apt_source", "deb_source" etc. OVER USE OF "source".** # # The location to find packages. Replaces base URL for unix/MacOS agents, used as fully # qualified path in windows -# [absolute_source] +# @param absolute_source # The exact location of the package to install. The entire path to the package must be # provided with this parameter. -# [yum_source] +# @param yum_source # Base URL of the location of mirrors of yum.puppet.com downloads sites. Directories under # the URL "yum_source" should match the structure of the yum.puppet.com -# [apt_source] +# @param apt_source # Base URL of the location of mirrors of apt.puppet.com downloads sites. Directories under # the URL "apt_source" should match the structure of the apt.puppet.com -# [mac_source] +# @param mac_source # Base URL of the location of mirrors of downloads.puppet.com downloads site that serves # MacOS packages. Directories under the URL "mac_source" should match the structure of the # downloads.puppet.com site -# [windows_source] +# @param windows_source # Base URL of the location of mirrors of downloads.puppet.com downloads site that serves # Windows packages. Directories under the URL "windows_source" should match the structure of # the downloads.puppet.com site -# [solaris_source] +# @param solaris_source # Base URL of the location of a mirror for Solaris packages. Currently, solaris packages can # only be made available by using puppetlabs-pe_repo. This means the mirror must be of a # PE master package serve. -# [aix_source] +# @param aix_source # Base URL of the location of a mirror for AIX packages. Currently, AIX packages can # only be made available by using puppetlabs-pe_repo. This means the mirror must be of a # PE master package serve. -# [use_alternate_sources] +# @param use_alternate_sources # **ONLY APPLICABLE WHEN WORKING WITH PE INSTALLTIONS** # When set to true will force downloads to come from the values of $apt_source, $deb_source # $mac_source etc. rather than from the default PE master package serve. Note that this will # also force downloads to ignore alternate_pe_source -# [alternate_pe_source] +# @param alternate_pe_source # Base URL of the location where packages are located in the same structure that's served # by a PE master (the directory structure in PE for serving packages is created by the # puppetlabs-pe_repo module). The general structure served by PE is: # /packages/${pe_server_version}/${platform_tag}/${package_name} -# [install_dir] +# @param install_dir # The directory the puppet agent should be installed to. This is only applicable for # windows operating systems. This only applies when upgrading the agent to a new # version; it will not cause re-installation of the same version to a new location. -# [install_options] +# @param install_options # An array of additional options to pass when installing puppet-agent. Each option in # the array can either be a string or a hash. Each option will automatically be quoted # when passed to the install command. With Windows packages, note that file paths in an @@ -81,23 +81,29 @@ # the installation command, forward slashes won't be automatically converted like they # are in `file` resources.) Note also that backslashes in double-quoted strings _must_ # be escaped and backslashes in single-quoted strings _can_ be escaped. -# [msi_move_locked_files] +# @param msi_move_locked_files # This is only applicable for Windows operating systems. There may be instances where # file locks cause unncessary service restarts. By setting to true, the module # will move files prior to installation that are known to cause file locks. -# [wait_for_pxp_agent_exit] +# @param wait_for_pxp_agent_exit # This parameter is only applicable for Windows operating systems and pertains to the # /files/install_agent.ps1 script. This parameterizes the module to define the wait time # for the PXP agent to end successfully. The default value is set 2 minutes. -# [wait_for_puppet_run] +# @param wait_for_puppet_run # This parameter is only applicable for Windows operating systems and pertains to the # /files/install_agent.ps1 script. This parameterizes the module to define the wait time # for the current puppet agent run to end successfully. The default value is set 2 minutes. -# [config] +# @param config # An array of configuration data to enforce. Each configuration data item must be a # Puppet_agent::Config hash, which has keys for puppet.conf section, setting, and value. # This parameter is constrained to managing only a predetermined set of configuration # settings, e.g. runinterval. +# @param proxy +# This is to be able to configure yum-repo with proxy, needed for +# example for clients in dmz:s that need to use proxy to reach the repo +# provided by puppetserver. +# @param skip_if_unavailable +# @param disable_proxy class puppet_agent ( $arch = $facts['os']['architecture'], $collection = $::puppet_agent::params::collection, diff --git a/manifests/install.pp b/manifests/install.pp index 0d80aedf3..62dddbf9c 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -4,9 +4,19 @@ # # === Parameters # -# [version] +# @param package_version # The puppet-agent version to install. -# +# @param install_dir +# The directory the puppet agent should be installed to. This is only applicable for +# windows operating systems. +# @param install_options +# An array of additional options to pass when installing puppet-agent. Each option in +# the array can either be a string or a hash. Each option will automatically be quoted +# when passed to the install command. With Windows packages, note that file paths in an +# install option must use backslashes. (Since install options are passed directly to +# the installation command, forward slashes won't be automatically converted like they +# are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +# be escaped and backslashes in single-quoted strings _can_ be escaped. class puppet_agent::install ( $package_version = 'present', $install_dir = undef, diff --git a/manifests/install/darwin.pp b/manifests/install/darwin.pp index 1ec48df02..8f398e7db 100644 --- a/manifests/install/darwin.pp +++ b/manifests/install/darwin.pp @@ -4,6 +4,18 @@ # # Manage the install process for Darwin OSes specifically # +# === Parameters +# +# @param package_version +# The puppet-agent version to install. +# @param install_options +# An array of additional options to pass when installing puppet-agent. Each option in +# the array can either be a string or a hash. Each option will automatically be quoted +# when passed to the install command. With Windows packages, note that file paths in an +# install option must use backslashes. (Since install options are passed directly to +# the installation command, forward slashes won't be automatically converted like they +# are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +# be escaped and backslashes in single-quoted strings _can_ be escaped. class puppet_agent::install::darwin ( $package_version, $install_options = [], diff --git a/manifests/install/solaris.pp b/manifests/install/solaris.pp index acd137bb2..e89f705bc 100644 --- a/manifests/install/solaris.pp +++ b/manifests/install/solaris.pp @@ -4,6 +4,18 @@ # # Manage the install process for solaris specifically # +# === Parameters +# +# @param package_version +# The puppet-agent version to install. +# @param install_options +# An array of additional options to pass when installing puppet-agent. Each option in +# the array can either be a string or a hash. Each option will automatically be quoted +# when passed to the install command. With Windows packages, note that file paths in an +# install option must use backslashes. (Since install options are passed directly to +# the installation command, forward slashes won't be automatically converted like they +# are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +# be escaped and backslashes in single-quoted strings _can_ be escaped. class puppet_agent::install::solaris ( $package_version, $install_options = [], diff --git a/manifests/install/suse.pp b/manifests/install/suse.pp index 36764757e..5657809bb 100644 --- a/manifests/install/suse.pp +++ b/manifests/install/suse.pp @@ -4,6 +4,18 @@ # # Manage the install process for SUSE OSes specifically # +# === Parameters +# +# @param package_version +# The puppet-agent version to install. +# @param install_options +# An array of additional options to pass when installing puppet-agent. Each option in +# the array can either be a string or a hash. Each option will automatically be quoted +# when passed to the install command. With Windows packages, note that file paths in an +# install option must use backslashes. (Since install options are passed directly to +# the installation command, forward slashes won't be automatically converted like they +# are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +# be escaped and backslashes in single-quoted strings _can_ be escaped. class puppet_agent::install::suse ( $package_version, $install_options = [], diff --git a/manifests/install/windows.pp b/manifests/install/windows.pp index 2ce15964b..01348a11e 100644 --- a/manifests/install/windows.pp +++ b/manifests/install/windows.pp @@ -4,6 +4,19 @@ # # Manage the install process for windows specifically # +# === Parameters +# +# @param install_options +# An array of additional options to pass when installing puppet-agent. Each option in +# the array can either be a string or a hash. Each option will automatically be quoted +# when passed to the install command. With Windows packages, note that file paths in an +# install option must use backslashes. (Since install options are passed directly to +# the installation command, forward slashes won't be automatically converted like they +# are in `file` resources.) Note also that backslashes in double-quoted strings _must_ +# be escaped and backslashes in single-quoted strings _can_ be escaped. +# @param install_dir +# The directory the puppet agent should be installed to. This is only applicable for +# windows operating systems. class puppet_agent::install::windows ( $install_dir = undef, $install_options = [], diff --git a/manifests/osfamily/aix.pp b/manifests/osfamily/aix.pp index ccb9ecaa9..355233094 100644 --- a/manifests/osfamily/aix.pp +++ b/manifests/osfamily/aix.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for AIX OSes class puppet_agent::osfamily::aix { assert_private() diff --git a/manifests/osfamily/darwin.pp b/manifests/osfamily/darwin.pp index db9895901..7fa8bd8dc 100644 --- a/manifests/osfamily/darwin.pp +++ b/manifests/osfamily/darwin.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for Darwin OSes class puppet_agent::osfamily::darwin { assert_private() diff --git a/manifests/osfamily/debian.pp b/manifests/osfamily/debian.pp index 67fdeb1dc..b24854e7a 100644 --- a/manifests/osfamily/debian.pp +++ b/manifests/osfamily/debian.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for Debain OSes class puppet_agent::osfamily::debian { assert_private() diff --git a/manifests/osfamily/redhat.pp b/manifests/osfamily/redhat.pp index 5f9d1917e..76be09104 100644 --- a/manifests/osfamily/redhat.pp +++ b/manifests/osfamily/redhat.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for RedHat OSes class puppet_agent::osfamily::redhat { assert_private() diff --git a/manifests/osfamily/solaris.pp b/manifests/osfamily/solaris.pp index dd45cb365..b6ed93ab3 100644 --- a/manifests/osfamily/solaris.pp +++ b/manifests/osfamily/solaris.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for Solaris OSes class puppet_agent::osfamily::solaris { assert_private() diff --git a/manifests/osfamily/suse.pp b/manifests/osfamily/suse.pp index 15049504b..7e4a0525a 100644 --- a/manifests/osfamily/suse.pp +++ b/manifests/osfamily/suse.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for SUSE OSes class puppet_agent::osfamily::suse { assert_private() diff --git a/manifests/osfamily/windows.pp b/manifests/osfamily/windows.pp index bf65766c8..f4c63a319 100644 --- a/manifests/osfamily/windows.pp +++ b/manifests/osfamily/windows.pp @@ -1,3 +1,5 @@ +# @summary This private class is used to determine the puppet-agent package +# location for Windows OSes class puppet_agent::osfamily::windows { assert_private() diff --git a/manifests/prepare.pp b/manifests/prepare.pp index 3e6b063c8..b03077cc8 100644 --- a/manifests/prepare.pp +++ b/manifests/prepare.pp @@ -4,9 +4,8 @@ # # === Parameters # -# [version] +# @param package_version # The puppet-agent version to install. -# class puppet_agent::prepare ( $package_version = undef ) { diff --git a/manifests/prepare/package.pp b/manifests/prepare/package.pp index 9ffe76167..8500566ba 100644 --- a/manifests/prepare/package.pp +++ b/manifests/prepare/package.pp @@ -4,9 +4,9 @@ # package is downloaded locally for installation. This is used on platforms # without package managers capable of working with a remote https repository. # -# [package_file_name] -# The puppet-agent package file to retrieve from the master. +# === Parameters # +# @param source class puppet_agent::prepare::package ( $source, ) { diff --git a/manifests/prepare/puppet_config.pp b/manifests/prepare/puppet_config.pp index 57183dbba..100bc45f3 100644 --- a/manifests/prepare/puppet_config.pp +++ b/manifests/prepare/puppet_config.pp @@ -2,6 +2,10 @@ # # Private class called from puppet_agent::prepare class # +# === Parameters +# +# @param package_version +# The puppet-agent version to install. class puppet_agent::prepare::puppet_config ( $package_version, ) { diff --git a/types/arch.pp b/types/arch.pp index dbfddb202..a1c194001 100644 --- a/types/arch.pp +++ b/types/arch.pp @@ -1 +1,2 @@ +# @summary This type stores all possible architecture patterns type Puppet_agent::Arch = Pattern[/^x86$/,/^x64$/,/^i386$/,/^i86pc$/,/^amd64$/,/^x86_64$/,/^power$/,/^sun4[uv]$/, /^ppc64le$/, /^aarch64$/, /PowerPC_POWER/] diff --git a/types/config.pp b/types/config.pp index d9f5a227b..df547275e 100644 --- a/types/config.pp +++ b/types/config.pp @@ -1,3 +1,4 @@ +# @summary This Puppet type alias type Puppet_agent::Config = Variant[Struct[{ section => Enum[main, server, agent, user, master], setting => Puppet_agent::Config_setting, value => String,