Skip to content

Latest commit

 

History

History
729 lines (434 loc) · 20.8 KB

REFERENCE.md

File metadata and controls

729 lines (434 loc) · 20.8 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • puppet_metrics_dashboard::config: Configures dashboard components.
  • puppet_metrics_dashboard::dashboards: Configures Grafana dashboards.
  • puppet_metrics_dashboard::dashboards::graphite: Installs graphite example dashboards
  • puppet_metrics_dashboard::dashboards::puppet_metrics: Installs puppet_metrics example dashboards
  • puppet_metrics_dashboard::dashboards::telegraf: Installs telegraf example dashboards
  • puppet_metrics_dashboard::grafana: Install and configure Grafana
  • puppet_metrics_dashboard::install: Installs InfluxDB components.
  • puppet_metrics_dashboard::post_start_configs: InfluxDB post-start configs
  • puppet_metrics_dashboard::repos: Configures InfluxDB and Grafana repos
  • puppet_metrics_dashboard::service: Manages services
  • puppet_metrics_dashboard::telegraf: Install and configure Telegraf
  • puppet_metrics_dashboard::telegraf::config: Configures Telegraf
  • puppet_metrics_dashboard::telegraf::service: Manages the Telegraf service

Defined types

Functions

Data types

Classes

puppet_metrics_dashboard

Installs and configures a stack for collecting, storing, and displaying Puppet Infrastructure metrics. Refer to data/common.yaml for additional parameter defaults.

Examples

Grafana with no login
class { 'puppet_metrics_dashboard':
  grafana_config => {
    'users'          => {
      'allow_sign_up' => false,
    },
    'auth.anonymous' => {
      'enabled' => true,
    },
  },
}
Configure Telegraf to collect metrics from a list of Masters, PuppetDB, and PostgreSQL servers
class { 'puppet_metrics_dashboard':
  add_dashboard_examples => true,
  overwrite_dashboards   => false,
  configure_telegraf     => true,
  enable_telegraf        => true,
  master_list            => ['master.example.com', ['compiler01.example.com', 9140], ['compiler02.example.com', 9140]],
  puppetdb_list          => ['puppetdb01.example.com', 'puppetdb02.example.com'],
  postgres_host_list     => ['postgres01.example.com', 'postgres02.example.com'],
}
Configure Graphite to accept metrics from a list of Masters
class { 'puppet_metrics_dashboard':
  add_dashboard_examples => true,
  overwrite_dashboards   => false,
  consume_graphite       => true,
  influxdb_database_name => ['graphite'],
  master_list            => ['master', 'master02'],
}
Configure Telegraf, Graphite, and Archive
class { 'puppet_metrics_dashboard':
  add_dashboard_examples => true,
  overwrite_dashboards   => false,
  consume_graphite       => true,
  configure_telegraf     => true,
  enable_telegraf        => true,
  influxdb_database_name => ['telegraf', 'graphite', 'puppet_metrics'],
}

Parameters

The following parameters are available in the puppet_metrics_dashboard class.

manage_repos

Data type: Boolean

Whether to configure apt / yum repositories for required packages.

add_dashboard_examples

Data type: Boolean

Whether to add the example Grafana dashboards for the configured InfluxDB databases. Defaults to false. Note: These dashboards are managed and any changes will be overwritten unless the overwrite_dashboards is set to false.

overwrite_dashboards

Data type: Boolean

Whether to overwrite the example Grafana dashboards. Defaults to true This parameter disables overwriting the example Grafana dashboards. It takes effect after the second Puppet run, and populates a overwrite_dashboards_disabled fact. Only used when add_dashboard_examples is true.

enable_chronograf

Data type: Boolean

Whether to install chronograf. Defaults to false No configuration of chronograf is included at this time.

enable_kapacitor

Data type: Boolean

Whether to install kapacitor. Defaults to false No configuration of kapacitor is included at this time.

enable_telegraf

Data type: Boolean

Whether to install telegraf. Defaults to true No configuration is done unless configure_telegraf is set to true.

configure_telegraf

Data type: Boolean

Whether to configure the Telegraf service. Defaults to true This parameter enables and configures Telegraf to query the *_list hosts for metrics. Metrics will be stored in the telegraf database in InfluxDb. Ensure that influxdb_database_name contains telegraf when using this parameter. Only used when enable_telegraf is true.

consume_graphite

Data type: Boolean

Whether to enable the InfluxDB Graphite plugin. Defaults to false This parameter enables the Graphite plugin for InfluxDB to allow for consuming Graphite metrics. Ensure influxdb_database_name contains graphite when using this parameter. Note: To consume metrics sent from Puppet Server, this must to be set to true.

influxdb_database_name

Data type: Array[String]

An Array of databases that should be created in InfluxDB. Valid values are telegraf, graphite, puppet_metrics, and any other string. Defaults to ["telegraf"] Each database in the array will be created in InfluxDB. telegraf, graphite, and puppet_metrics are specially named and will be used with their associated metric collection method. Any other database name will be created, but not associated with components in this module.

influxdb_urls

Data type: Array[String]

An Array containing urls defining InfluxDB instances for Telegraf.

influx_db_service_name

Data type: String

Name of the InfluxDB service used by the operating system.

influx_db_password

Data type: String

The password for the InfluxDB admin user. Defaults to puppet

telegraf_db_name

Data type: String

The InfluxDB database where Telegraf metrics are stored.

http_response_timeout

Data type: String[2]

Timeout for Telegraf HTTP requests. Defaults to 5s

telegraf_agent_interval

Data type: String[2]

Frequency of Telegraf HTTP queries for metrics. Defaults to 5s

pg_query_interval

Data type: String[2]

Frequency of Telegraf PostgreSQL queries for metrics. Defaults to 10m

use_dashboard_ssl

Data type: Boolean

Whether to enable SSL in Grafana. Valid values are true, false. Defaults to false

tidy_telegraf_configs

Data type: Boolean

Whether or not to remove unmanaged configuration files from /etc/telegraf/telegraf.d. Defaults to false

dashboard_cert_file

Data type: String

The location of the Grafana certficiate. Defaults to /etc/grafana/${clientcert}_cert.pem Only used when use_dashboard_ssl is true.

dashboard_cert_key

Data type: String

The location of the Grafana private key. Defaults to /etc/grafana/${clientcert}_key.pem Only used when use_dashboard_ssl is true.

grafana_http_port

Data type: Integer

The port for the Grafana web interface. Valid values are Integers from 1024 to 65536. Defaults to 3000 This should be a nonprivileged port (above 1024).

grafana_password

Data type: String

The password for the Grafana admin user. Defaults to admin

grafana_version

Data type: String

The version of Grafana to install. Valid values are String versions of Grafana.

overwrite_dashboards_file

Data type: String

File used to populate the overwrite_dashboards fact.

grafana_config

Data type: Hash

Hash of arbitrary configuration settings to pass to Grafana. These are added to grafana.ini with top-level keys becoming sections and their key-value children becoming settings.

master_list

Data type: Puppet_metrics_dashboard::HostList

An Array of servers that Telegraf will collect Puppet Server metrics from. Entries may be:

  • A String that contains a hostname or IP address. (The module will use a default port number of 8140)
  • An Array where the first entry is a String that contains a hostname or IP address, and the second entry is an Integer that specifies the port number. Defaults to the result of a PuppetDB query, or [$trusted['certname']]

Default value: puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile('master')

puppetdb_list

Data type: Puppet_metrics_dashboard::HostList

An Array of servers that Telegraf will collect PuppetDB metrics from. Entries may be:

  • A String that contains a hostname or IP address. (The module will use a default port number of 8081)
  • An Array where the first entry is a String that contains a hostname or IP address, and the second entry is an Integer that specifies the port number. Defaults to the result of a PuppetDB query, or [$trusted['certname']]

Default value: puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile('puppetdb')

postgres_host_list

Data type: Puppet_metrics_dashboard::HostList

An Array of servers that Telegraf will collect PostgreSQL metrics from. Entries may be:

  • A String that contains a hostname or IP address. (The module will use a default port number of 5432)
  • An Array where the first entry is a String that contains a hostname or IP address, and the second entry is an Integer that specifies the port number. Defaults to the results of a PuppetDB query, or [$trusted['certname']]

Default value: puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile('database')

puppetdb_metrics

Data type: Puppet_metrics_dashboard::Puppetdb_metric

An Array of Hashes containing name/url pairs for each PuppetDB metric. Refer to functions/puppetdb_metrics.pp for defaults.

Default value: puppet_metrics_dashboard::puppetdb_metrics()

puppet_metrics_dashboard::profile::dbcompiler::install

Apply this class to compilers running PuppetDB to configure Telegraf and collect puppetserver and puppetdb metrics

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::dbcompiler::install class.

influxdb_urls

Data type: Array[String]

An Array containing urls defining InfluxDB instances for Telegraf.

timeout

Data type: String[2]

Default timeout of http calls. Defaults to 5 seconds

Default value: lookup('puppet_metrics_dashboard::http_response_timeout')

compiler

Data type: Variant[String,Tuple[String, Integer]]

The FQDN of the compiler / master. Defaults to the FQDN of the server where the profile is applied

Default value: $facts['networking']['fqdn']

puppetdb_host

Data type: Variant[String,Tuple[String, Integer]]

Where to query the puppetdb host. Defaults to localhost.

Default value: 'localhost'

cm_port

Data type: Integer[1]

The port that the puppetserver service listens on on your compiler. Defaults to 8140

Default value: 8140

db_port

Data type: Integer[1]

The port that the puppetdb service listens on on your compiler. Defaults to 8081

Default value: 8081

interval

Data type: String[2]

The frequency that telegraf will poll puppetserver metrics. Defaults to '5s'

Default value: '5s'

puppetdb_metrics

Data type: Puppet_metrics_dashboard::Puppetdb_metric

Default value: puppet_metrics_dashboard::puppetdb_metrics()

puppet_metrics_dashboard::profile::master::install

Install requirements for the voxpupuli/puppet-telegraf module.

Examples

Apply this class to the Master and any/all Compilers
include puppet_metrics_dashboard::profile::master::install

puppet_metrics_dashboard::profile::master::postgres_access

Apply this class to a PE PostgreSQL node to allow access by Telegraf.

Examples

Apply this class to PE PostgreSQL nodes
class { 'puppet_metrics_dashboard::profile::master::postgres_access':
  telegraf_host => 'dashboard.example.com',
}

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::master::postgres_access class.

telegraf_host

Data type: Optional[String[1]]

The FQDN of the host running Telegraf. Defaults to an empty string. You can define this parameter, otherwise this class will query PuppetDB for a dashboard host.

Default value: undef

puppet_metrics_dashboard::profile::postgres

This class is deprecated. Please use the Puppet_metrics_dashboard::Profile::Master::Postgres_access class.

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::postgres class.

grafana_host

Data type: String

The FQDN of the host where telegraf runs. Defaults to an empty string. You can explicitly set this parameter or the class attempts to lookup which host has the puppet_metrics_dashboard class applied in PuppetDB. If the parameter is not set and the lookup does not return anything we issue a warning.

Default value: ''

Defined types

puppet_metrics_dashboard::certs

This class creates a set of certificates in /etc/${service}. These certificates are used when configuring Grafana to use SSL and to connect to PE Postgres. The certificates are based on the agent's own Puppet certificates.

Parameters

The following parameters are available in the puppet_metrics_dashboard::certs defined type.

service

Data type: Any

The service name associated with these certificates.

Default value: $name

puppet_metrics_dashboard::profile::compiler

Apply this class to a master or compiler to collect puppetserver metrics

Examples

Add telegraf to a master / compiler
puppet_metrics_dashboard::profile::compiler{ $facts['networking']['fqdn']:
  timeout => '5s',
}

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::compiler defined type.

timeout

Data type: String[2]

Default timeout of http calls. Defaults to 5 seconds

Default value: lookup('puppet_metrics_dashboard::http_response_timeout')

compiler

Data type: Variant[String,Tuple[String, Integer]]

The FQDN of the compiler / master. Defaults to the FQDN of the server where the profile is applied

Default value: $facts['networking']['fqdn']

port

Data type: Integer[1]

The port that the puppetserver service listens on on your compiler. Defaults to 8140

Default value: 8140

interval

Data type: String[2]

The frequency that telegraf will poll for metrics. Defaults to '5s'

Default value: '5s'

puppet_metrics_dashboard::profile::master::postgres

Apply this class to an agent running pe-postgresql to collect postgres metrics

Examples

Add telegraf to a postgres server
puppet_metrics_dashboard::profile::master::postgres{ $facts['networking']['fqdn']:
  query_interval => '10m',
}

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::master::postgres defined type.

query_interval

Data type: String[2]

How often to run the queries in minutes. Defaults to 10 minutes.

Default value: lookup('puppet_metrics_dashboard::pg_query_interval')

postgres_host

Data type: Variant[String,Tuple[String, Integer]]

The FQDN of the postgres host. Defaults to the FQDN of the server where the profile is applied

Default value: $facts['networking']['fqdn']

port

Data type: Integer[1]

The port that the postgres service listens on. Defaults to 5432

Default value: 5432

databases

Data type: Array[String[1]]

An Array of databases to query on. Defaults to ['pe-puppetdb','pe-rbac','pe-activity','pe-classifier']

Default value: ['pe-puppetdb','pe-rbac','pe-activity','pe-classifier']

puppet_metrics_dashboard::profile::puppetdb

Apply this class to a node running puppetdb to collect puppetdb metrics

Examples

Add telegraf to a puppetdb node
puppet_metrics_dashboard::profile::puppetdb{ $facts['networking']['fqdn']:
  timeout          => '5s',
  puppetdb_metrics => puppet_metrics_dashboard::puppetdb_metrics(), # this is the default value
}

Parameters

The following parameters are available in the puppet_metrics_dashboard::profile::puppetdb defined type.

timeout

Data type: String[2]

Default timeout of http calls. Defaults to 5 seconds

Default value: lookup('puppet_metrics_dashboard::http_response_timeout')

puppetdb_metrics

Data type: Puppet_metrics_dashboard::Puppetdb_metric

An array of hashes containing name / url pairs for each puppetdb metric. See functions/puppetdb_metrics.pp for defaults.

Default value: puppet_metrics_dashboard::puppetdb_metrics()

puppetdb_host

Data type: Variant[String,Tuple[String, Integer]]

Where to query the puppetdb host. Defaults to localhost.

Default value: 'localhost'

port

Data type: Integer[1]

The port that the puppetdb service listens on on your compiler. Defaults to 8081

Default value: 8081

interval

Data type: String[2]

The frequency that telegraf will poll for metrics. Defaults to '5s'

Default value: '5s'

enable_client_cert

Data type: Boolean

A boolean to enable using the client certificate for the PuppetDB queries. Defaults to true

Default value: true

Functions

puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile

Type: Puppet Language

The puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile function.

puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile(String $profile)

The puppet_metrics_dashboard::localhost_or_hosts_with_pe_profile function.

Returns: Array

profile

Data type: String

puppet_metrics_dashboard::puppetdb_metrics

Type: Puppet Language

The list of metrics to pull from PuppetDB depends on the PE version. To avoid having a data file for each version we utilize this function to build the needed array of hashes.

puppet_metrics_dashboard::puppetdb_metrics()

The list of metrics to pull from PuppetDB depends on the PE version. To avoid having a data file for each version we utilize this function to build the needed array of hashes.

Returns: Array[Hash] An array of hashes containing name / url pairs for each puppetdb metric.

puppet_metrics_dashboard::puppetdb_no_remote_metrics

Type: Puppet Language

The puppet_metrics_dashboard::puppetdb_no_remote_metrics function.

puppet_metrics_dashboard::puppetdb_no_remote_metrics()

The puppet_metrics_dashboard::puppetdb_no_remote_metrics function.

Returns: Boolean

Data types

Puppet_metrics_dashboard::HostList

A list of hostnames, or pairs of hostname and port.

Alias of Array[Variant[ String, Tuple[String, Integer] ]]

Puppet_metrics_dashboard::Puppetdb_metric

A metric name corresponding to an endpoint (url)

Alias of Tuple[Struct[{ name => String[1], url => String[1] }], 1, default]