From b4720fc3ff19326689fa6422aa511e70205f6781 Mon Sep 17 00:00:00 2001 From: Julien Godin Date: Thu, 2 Nov 2023 09:41:58 +0100 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=92=9A=20Add=20documentation=20for=20?= =?UTF-8?q?blackbox=5Fexporter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julien Godin --- manifests/blackbox_exporter.pp | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/manifests/blackbox_exporter.pp b/manifests/blackbox_exporter.pp index 12930094c..5fffa8df4 100644 --- a/manifests/blackbox_exporter.pp +++ b/manifests/blackbox_exporter.pp @@ -29,6 +29,16 @@ # Whether to create user or rely on external code for that # @param modules # Structured, array of blackbox module definitions for different probe types +# @param export_scrape_job +# Whether to export a scrape job for this service +# @param scrape_host +# Hostname or IP address to scrape +# @param scrape_port +# Host port to scrape +# @param scrape_job_name +# Name of the scrape job to export, if export_scrape_job is true +# @param scrape_job_labels +# Labels to add to the scrape job, if export_scrape_job is true # @param os # Operating system (linux is the only one supported) # @param package_ensure From 4b93d40ab8daa141038c1e930b2b51e333d7a6a2 Mon Sep 17 00:00:00 2001 From: Julien Godin Date: Thu, 2 Nov 2023 09:45:43 +0100 Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=92=9A=20Add=20documentation=20for=20?= =?UTF-8?q?custom=20types?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julien Godin --- manifests/alertmanager.pp | 4 ++++ manifests/blackbox_exporter.pp | 5 ++--- types/gsuri.pp | 1 + types/initstyle.pp | 1 + types/s3uri.pp | 1 + types/uri.pp | 1 + 6 files changed, 10 insertions(+), 3 deletions(-) diff --git a/manifests/alertmanager.pp b/manifests/alertmanager.pp index 9cc2102e2..a85512adb 100644 --- a/manifests/alertmanager.pp +++ b/manifests/alertmanager.pp @@ -68,6 +68,8 @@ # If package, then use this for package ensure default 'latest' # @param package_name # The binary package name - not available yet +# @param config_dir +# The directory to put the configuration files # @param purge_config_dir # Purge config files no longer generated by Puppet # @param manage_config @@ -83,6 +85,8 @@ # - to: 'root@localhost' # @param restart_on_change # Should puppet restart the service on configuration change? (default true) +# @param reload_on_change +# Should puppet reload the service on configuration change? (default false) # @param route # The top level route. # Example (also default): diff --git a/manifests/blackbox_exporter.pp b/manifests/blackbox_exporter.pp index 5fffa8df4..466ce24f0 100644 --- a/manifests/blackbox_exporter.pp +++ b/manifests/blackbox_exporter.pp @@ -63,9 +63,7 @@ # Optional proxy server, with port number if needed. ie: https://example.com:8080 # @param proxy_type # Optional proxy server type (none|http|https|ftp) -# Example for configuring named blackbox modules via hiera -# details of the format: https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md -# @example +# @example Example for configuring named blackbox modules via hiera # prometheus::blackbox_exporter::modules: # simple_ssl: # prober: http @@ -76,6 +74,7 @@ # prober: tcp # tcp: # preferred_ip_protocol: ip4 +# @ see https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md class prometheus::blackbox_exporter ( Stdlib::Absolutepath $config_file = '/etc/blackbox-exporter.yaml', String $download_extension = 'tar.gz', diff --git a/types/gsuri.pp b/types/gsuri.pp index 6f2cdeef0..1ab5d0735 100644 --- a/types/gsuri.pp +++ b/types/gsuri.pp @@ -1 +1,2 @@ +# @summary Type for a Google Cloud Storage URI type Prometheus::GsUri = Pattern[/^gs:\/\//] diff --git a/types/initstyle.pp b/types/initstyle.pp index 34c8aa9af..b8e4fc74f 100644 --- a/types/initstyle.pp +++ b/types/initstyle.pp @@ -1,3 +1,4 @@ +# @summary A type to represent the init style of a Prometheus service type Prometheus::Initstyle = Enum[ 'sysv', 'systemd', diff --git a/types/s3uri.pp b/types/s3uri.pp index cd2c9487d..cebec4520 100644 --- a/types/s3uri.pp +++ b/types/s3uri.pp @@ -1 +1,2 @@ +# @summary Type for S3 URIs type Prometheus::S3Uri = Pattern[/^s3:\/\//] diff --git a/types/uri.pp b/types/uri.pp index 39f831c12..c191b667b 100644 --- a/types/uri.pp +++ b/types/uri.pp @@ -1,3 +1,4 @@ +# @summary A URI that can be used to fetch a Prometheus configuration file type Prometheus::Uri = Variant[ Stdlib::Filesource, Stdlib::HTTPUrl, From cfc1cfb290961b2c8202570f2befcd63eb3f08ae Mon Sep 17 00:00:00 2001 From: Julien Godin Date: Thu, 2 Nov 2023 10:37:30 +0100 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=92=9A=20Expand=20the=20summary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julien Godin --- manifests/install.pp | 11 ++++++----- manifests/scrape_job.pp | 5 +++-- manifests/unbound_exporter.pp | 5 ++--- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/manifests/install.pp b/manifests/install.pp index ae9fc502e..8ffcb4e8c 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -1,8 +1,9 @@ -# @summary -# Install prometheus via different methods with parameters from init -# Currently only the install from url is implemented, when Prometheus will deliver packages for some Linux distros I will -# implement the package install method as well -# The package method needs specific yum or apt repo settings which are not made yet by the module +# @summary Install prometheus +# +# @note Install prometheus via different methods with parameters from init +# Currently only the install from url is implemented, when Prometheus will deliver packages for some Linux distros I will +# implement the package install method as well +# The package method needs specific yum or apt repo settings which are not made yet by the module class prometheus::install { assert_private() diff --git a/manifests/scrape_job.pp b/manifests/scrape_job.pp index 782a19689..c1edf37ec 100644 --- a/manifests/scrape_job.pp +++ b/manifests/scrape_job.pp @@ -1,5 +1,6 @@ -# @summary -# This define is used to export prometheus scrape settings from nodes to be scraped to the node +# @summary This module manages prometheus scrape jobs. +# +# @note This define is used to export prometheus scrape settings from nodes to be scraped to the node # running prometheus itself. # This can be used to make prometheus find instances of your running service or application. # @param job_name diff --git a/manifests/unbound_exporter.pp b/manifests/unbound_exporter.pp index 917436681..144a08711 100644 --- a/manifests/unbound_exporter.pp +++ b/manifests/unbound_exporter.pp @@ -1,6 +1,5 @@ -# -# @summary This module manages prometheus unbound exporter. The exporter needs to be compiled by hand! (https://github.com/kumina/unbound_exporter/issues/21) -# +# @summary This module manages prometheus unbound exporter. +# @note The exporter needs to be compiled by hand! (https://github.com/kumina/unbound_exporter/issues/21) # @param arch # Architecture # @param bin_dir From a3f205ac4670dc6f2c79bcd769c61db0e9253e4f Mon Sep 17 00:00:00 2001 From: Julien Godin Date: Thu, 2 Nov 2023 11:40:47 +0100 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=92=9A=20automatically=20Update=20ref?= =?UTF-8?q?erence.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Julien Godin --- REFERENCE.md | 170 ++++++++++++++++++++++--------------------- manifests/install.pp | 4 +- 2 files changed, 92 insertions(+), 82 deletions(-) diff --git a/REFERENCE.md b/REFERENCE.md index b87067ff2..a71a3a93f 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -23,10 +23,7 @@ * [`prometheus::graphite_exporter`](#prometheus--graphite_exporter): This module manages prometheus node graphite_exporter * [`prometheus::grok_exporter`](#prometheus--grok_exporter): This module manages prometheus grok_exporter * [`prometheus::haproxy_exporter`](#prometheus--haproxy_exporter): This module manages prometheus haproxy_exporter -* [`prometheus::install`](#prometheus--install): Install prometheus via different methods with parameters from init -Currently only the install from url is implemented, when Prometheus will deliver packages for some Linux distros I will -implement the package install method as well -The package method needs specific yum or apt repo settings which are not made yet by the module +* [`prometheus::install`](#prometheus--install): Install prometheus * [`prometheus::ipmi_exporter`](#prometheus--ipmi_exporter): This module manages prometheus node ipmi_exporter (https://github.com/soundcloud/ipmi_exporter) * [`prometheus::ipsec_exporter`](#prometheus--ipsec_exporter): This module manages prometheus node ipsec_exporter * [`prometheus::jmx_exporter`](#prometheus--jmx_exporter): Installs and configures the Prometheus JMX exporter @@ -56,7 +53,7 @@ The package method needs specific yum or apt repo settings which are not made ye * [`prometheus::ssh_exporter`](#prometheus--ssh_exporter): This module manages prometheus ssh_exporter (https://github.com/treydock/ssh_exporter) * [`prometheus::ssl_exporter`](#prometheus--ssl_exporter): This module manages prometheus ssl_exporter (https://github.com/ribbybibby/ssl_exporter) * [`prometheus::statsd_exporter`](#prometheus--statsd_exporter): This module manages prometheus statsd_exporter -* [`prometheus::unbound_exporter`](#prometheus--unbound_exporter): This module manages prometheus unbound exporter. The exporter needs to be compiled by hand! (https://github.com/kumina/unbound_exporter/issues/21) +* [`prometheus::unbound_exporter`](#prometheus--unbound_exporter): This module manages prometheus unbound exporter. * [`prometheus::varnish_exporter`](#prometheus--varnish_exporter): This module manages prometheus varnish_exporter #### Private Classes @@ -68,17 +65,15 @@ restarting the whole service when a config changes * [`prometheus::alerts`](#prometheus--alerts): This module manages prometheus alert files for prometheus * [`prometheus::daemon`](#prometheus--daemon): This define managed prometheus daemons that don't have their own class -* [`prometheus::scrape_job`](#prometheus--scrape_job): This define is used to export prometheus scrape settings from nodes to be scraped to the node -running prometheus itself. -This can be used to make prometheus find instances of your running service or application. +* [`prometheus::scrape_job`](#prometheus--scrape_job): This module manages prometheus scrape jobs. ### Data types -* [`Prometheus::GsUri`](#Prometheus--GsUri) -* [`Prometheus::Initstyle`](#Prometheus--Initstyle) +* [`Prometheus::GsUri`](#Prometheus--GsUri): Type for a Google Cloud Storage URI +* [`Prometheus::Initstyle`](#Prometheus--Initstyle): A type to represent the init style of a Prometheus service * [`Prometheus::Install`](#Prometheus--Install): type to enforce the different installation methods for our exporters. -* [`Prometheus::S3Uri`](#Prometheus--S3Uri) -* [`Prometheus::Uri`](#Prometheus--Uri) +* [`Prometheus::S3Uri`](#Prometheus--S3Uri): Type for S3 URIs +* [`Prometheus::Uri`](#Prometheus--Uri): A URI that can be used to fetch a Prometheus configuration file ## Classes @@ -980,11 +975,13 @@ The following parameters are available in the `prometheus::alertmanager` class: * [`os`](#-prometheus--alertmanager--os) * [`package_ensure`](#-prometheus--alertmanager--package_ensure) * [`package_name`](#-prometheus--alertmanager--package_name) +* [`config_dir`](#-prometheus--alertmanager--config_dir) * [`purge_config_dir`](#-prometheus--alertmanager--purge_config_dir) * [`manage_config`](#-prometheus--alertmanager--manage_config) * [`validate_config`](#-prometheus--alertmanager--validate_config) * [`receivers`](#-prometheus--alertmanager--receivers) * [`restart_on_change`](#-prometheus--alertmanager--restart_on_change) +* [`reload_on_change`](#-prometheus--alertmanager--reload_on_change) * [`route`](#-prometheus--alertmanager--route) * [`service_enable`](#-prometheus--alertmanager--service_enable) * [`service_ensure`](#-prometheus--alertmanager--service_ensure) @@ -995,8 +992,6 @@ The following parameters are available in the `prometheus::alertmanager` class: * [`version`](#-prometheus--alertmanager--version) * [`proxy_server`](#-prometheus--alertmanager--proxy_server) * [`proxy_type`](#-prometheus--alertmanager--proxy_type) -* [`config_dir`](#-prometheus--alertmanager--config_dir) -* [`reload_on_change`](#-prometheus--alertmanager--reload_on_change) ##### `arch` @@ -1172,6 +1167,12 @@ Data type: `String[1]` The binary package name - not available yet +##### `config_dir` + +Data type: `Stdlib::Absolutepath` + +The directory to put the configuration files + ##### `purge_config_dir` Data type: `Boolean` @@ -1215,6 +1216,14 @@ Should puppet restart the service on configuration change? (default true) Default value: `true` +##### `reload_on_change` + +Data type: `Boolean` + +Should puppet reload the service on configuration change? (default false) + +Default value: `false` + ##### `route` Data type: `Hash` @@ -1295,20 +1304,6 @@ Optional proxy server type (none|http|https|ftp) Default value: `undef` -##### `config_dir` - -Data type: `Stdlib::Absolutepath` - - - -##### `reload_on_change` - -Data type: `Boolean` - - - -Default value: `false` - ### `prometheus::apache_exporter` This module manages prometheus apache_exporter @@ -2514,8 +2509,6 @@ Default value: `undef` ### `prometheus::blackbox_exporter` -Example for configuring named blackbox modules via hiera -details of the format: https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md prometheus::blackbox_exporter::modules: simple_ssl: prober: http @@ -2526,6 +2519,15 @@ prometheus::blackbox_exporter::modules: prober: tcp tcp: preferred_ip_protocol: ip4 +@ see https://github.com/prometheus/blackbox_exporter/blob/master/CONFIGURATION.md + +#### Examples + +##### Example for configuring named blackbox modules via hiera + +```puppet + +``` #### Parameters @@ -2546,6 +2548,11 @@ The following parameters are available in the `prometheus::blackbox_exporter` cl * [`manage_service`](#-prometheus--blackbox_exporter--manage_service) * [`manage_user`](#-prometheus--blackbox_exporter--manage_user) * [`modules`](#-prometheus--blackbox_exporter--modules) +* [`export_scrape_job`](#-prometheus--blackbox_exporter--export_scrape_job) +* [`scrape_host`](#-prometheus--blackbox_exporter--scrape_host) +* [`scrape_port`](#-prometheus--blackbox_exporter--scrape_port) +* [`scrape_job_name`](#-prometheus--blackbox_exporter--scrape_job_name) +* [`scrape_job_labels`](#-prometheus--blackbox_exporter--scrape_job_labels) * [`os`](#-prometheus--blackbox_exporter--os) * [`package_ensure`](#-prometheus--blackbox_exporter--package_ensure) * [`package_name`](#-prometheus--blackbox_exporter--package_name) @@ -2558,11 +2565,6 @@ The following parameters are available in the `prometheus::blackbox_exporter` cl * [`config_mode`](#-prometheus--blackbox_exporter--config_mode) * [`proxy_server`](#-prometheus--blackbox_exporter--proxy_server) * [`proxy_type`](#-prometheus--blackbox_exporter--proxy_type) -* [`export_scrape_job`](#-prometheus--blackbox_exporter--export_scrape_job) -* [`scrape_host`](#-prometheus--blackbox_exporter--scrape_host) -* [`scrape_port`](#-prometheus--blackbox_exporter--scrape_port) -* [`scrape_job_name`](#-prometheus--blackbox_exporter--scrape_job_name) -* [`scrape_job_labels`](#-prometheus--blackbox_exporter--scrape_job_labels) ##### `arch` @@ -2684,6 +2686,46 @@ Structured, array of blackbox module definitions for different probe types Default value: `{}` +##### `export_scrape_job` + +Data type: `Boolean` + +Whether to export a scrape job for this service + +Default value: `false` + +##### `scrape_host` + +Data type: `Optional[Stdlib::Host]` + +Hostname or IP address to scrape + +Default value: `undef` + +##### `scrape_port` + +Data type: `Stdlib::Port` + +Host port to scrape + +Default value: `9115` + +##### `scrape_job_name` + +Data type: `String[1]` + +Name of the scrape job to export, if export_scrape_job is true + +Default value: `'blackbox'` + +##### `scrape_job_labels` + +Data type: `Optional[Hash]` + +Labels to add to the scrape job, if export_scrape_job is true + +Default value: `undef` + ##### `os` Data type: `String[1]` @@ -2778,46 +2820,6 @@ Data type: `Optional[Enum['none', 'http', 'https', 'ftp']]` Optional proxy server type (none|http|https|ftp) -Default value: `undef` - -##### `export_scrape_job` - -Data type: `Boolean` - - - -Default value: `false` - -##### `scrape_host` - -Data type: `Optional[Stdlib::Host]` - - - -Default value: `undef` - -##### `scrape_port` - -Data type: `Stdlib::Port` - - - -Default value: `9115` - -##### `scrape_job_name` - -Data type: `String[1]` - - - -Default value: `'blackbox'` - -##### `scrape_job_labels` - -Data type: `Optional[Hash]` - - - Default value: `undef` ### `prometheus::collectd_exporter` @@ -4826,8 +4828,10 @@ Default value: `undef` ### `prometheus::install` Install prometheus via different methods with parameters from init + Currently only the install from url is implemented, when Prometheus will deliver packages for some Linux distros I will implement the package install method as well + The package method needs specific yum or apt repo settings which are not made yet by the module ### `prometheus::ipmi_exporter` @@ -13327,7 +13331,9 @@ Default value: `undef` ### `prometheus::unbound_exporter` -This module manages prometheus unbound exporter. The exporter needs to be compiled by hand! (https://github.com/kumina/unbound_exporter/issues/21) +This module manages prometheus unbound exporter. + +* **Note** The exporter needs to be compiled by hand! (https://github.com/kumina/unbound_exporter/issues/21) * **See also** * https://github.com/kumina/unbound_exporter @@ -14285,7 +14291,9 @@ Default value: `$prometheus::usershell` ### `prometheus::scrape_job` -This define is used to export prometheus scrape settings from nodes to be scraped to the node +This module manages prometheus scrape jobs. + +* **Note** This define is used to export prometheus scrape settings from nodes to be scraped to the node running prometheus itself. This can be used to make prometheus find instances of your running service or application. @@ -14332,13 +14340,13 @@ Default value: `undef` ### `Prometheus::GsUri` -The Prometheus::GsUri data type. +Type for a Google Cloud Storage URI Alias of `Pattern[/^gs:\/\//]` ### `Prometheus::Initstyle` -The Prometheus::Initstyle data type. +A type to represent the init style of a Prometheus service Alias of `Enum['sysv', 'systemd', 'sles', 'launchd', 'upstart', 'none']` @@ -14350,13 +14358,13 @@ Alias of `Enum['url', 'package', 'none']` ### `Prometheus::S3Uri` -The Prometheus::S3Uri data type. +Type for S3 URIs Alias of `Pattern[/^s3:\/\//]` ### `Prometheus::Uri` -The Prometheus::Uri data type. +A URI that can be used to fetch a Prometheus configuration file Alias of `Variant[Stdlib::Filesource, Stdlib::HTTPUrl, Stdlib::HTTPSUrl, Prometheus::S3Uri, Prometheus::GsUri]` diff --git a/manifests/install.pp b/manifests/install.pp index 8ffcb4e8c..cd63d385b 100644 --- a/manifests/install.pp +++ b/manifests/install.pp @@ -1,8 +1,10 @@ # @summary Install prometheus # -# @note Install prometheus via different methods with parameters from init +# Install prometheus via different methods with parameters from init +# # Currently only the install from url is implemented, when Prometheus will deliver packages for some Linux distros I will # implement the package install method as well +# # The package method needs specific yum or apt repo settings which are not made yet by the module class prometheus::install { assert_private()