REFERENCE.md

Reference

Table of Contents

Classes

• puppet_operational_dashboards: Installs Telegraf, InfluxDB, and Grafana to collect and display Puppet metrics
• puppet_operational_dashboards::enterprise_infrastructure: Installs dependancies for Operational dashboards on PE infrastructure components
• puppet_operational_dashboards::profile::dashboards: Installs Grafana and several dashboards to display Puppet metrics. Included via the base class.
• puppet_operational_dashboards::profile::postgres_access: Allows Telegraf to connect and collect metrics from postgres nodes
• puppet_operational_dashboards::telegraf::agent: Installs and configures Telegraf to query hosts in a Puppet infrastructure. Included by the base class

Defined types

• puppet_operational_dashboards::telegraf::config: Defined type to create Telegraf configurations for a given service

Functions

• puppet_operational_dashboards::hosts_with_profile: function used to determine hosts with a profile class
• puppet_operational_dashboards::pe_profiles_on_host: function used to determine hosts with a Puppet Enterprise profile

Plans

• puppet_operational_dashboards::load_metrics: A plan created with bolt plan new.
• puppet_operational_dashboards::provision_dashboard: A plan to provision a non-SSL operational dashboards node

Classes

puppet_operational_dashboards

Installs Telegraf, InfluxDB, and Grafana to collect and display Puppet metrics

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards':
  manage_influxdb => false,
  influxdb_host   => '<influxdb_fqdn>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards class:

• manage_influxdb
• influxdb_host
• influxdb_port
• initial_org
• initial_bucket
• influxdb_token
• telegraf_token_name
• manage_telegraf
• manage_telegraf_token
• use_ssl
• influxdb_token_file
• telegraf_token

manage_influxdb

Data type: Boolean

Whether to manage installation and configuration of InfluxDB. Defaults to true

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host. Defaults to a the value of influxdb::host, or $facts['fqdn'] if unset

Default value: lookup(influxdb::host, undef, undef, $facts['networking']['fqdn'])

influxdb_port

Data type: Integer

Port used by the InfluxDB service. Defaults to the value of influxdb::port, or 8086 if unset

Default value: lookup(influxdb::port, undef, undef, 8086)

initial_org

Data type: String

Name of the InfluxDB organization to configure. Defaults to the value of influxdb::initial_org, or 'puppetlabs' if unset

Default value: lookup(influxdb::initial_org, undef, undef, 'puppetlabs')

initial_bucket

Data type: String

Name of the InfluxDB bucket to configure and query. Defaults to the value of influxdb::initial_bucket, or 'puppet_data' if unset

Default value: lookup(influxdb::initial_bucket, undef, undef, 'puppet_data')

influxdb_token

Data type: Optional[Sensitive[String]]

InfluxDB admin token in Sensitive format. Defaults to the value of influxdb::token. See the puppetlabs/influxdb documentation for more information about this token.

Default value: lookup(influxdb::token, undef, undef, undef)

telegraf_token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $telegraf_token.

Default value: 'puppet telegraf token'

manage_telegraf

Data type: Boolean

Whether to manage installation and configuration of Telegraf. Defaults to true.

Default value: true

manage_telegraf_token

Data type: Boolean

Whether to create and manage a Telegraf token with permissions to query buckets in the default organization. Defaults to true.

Default value: true

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB. Defaults to true

Default value: true

influxdb_token_file

Data type: String

Location on disk of an InfluxDB admin token. This file is written to by the influxdb class during installation and read by the type and providers, as well Deferred functions in this module.

Default value: lookup(influxdb::token_file, undef, undef, $facts['identity']['user'] ? { 'root' => '/root/.influxdb_token', default => "/home/${facts['identity']['user']}/.influxdb_token" })

telegraf_token

Data type: Optional[Sensitive[String]]

Telegraf token in Sensitive format.

Default value: undef

puppet_operational_dashboards::enterprise_infrastructure

When applied to an appropriate node group this class applies the toml gem and database access On appropriate infrastructure nodes in PE

Examples

include puppet_operational_dashboards::enterprise_infrastructure

Parameters

The following parameters are available in the puppet_operational_dashboards::enterprise_infrastructure class:

• profiles

profiles

Data type: Array[String]

Array of PE profiles on the node with this class applied.

Default value: puppet_operational_dashboards::pe_profiles_on_host()

puppet_operational_dashboards::profile::dashboards

Installs Grafana and several dashboards to display Puppet metrics. Included via the base class.

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards::profile::dashboards':
  token         => '<my_sensitive_token>',
  influxdb_host => '<influxdb_fqdn>',
  influxdb_port => 8086,
  initial_bucket => '<my_bucket>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards::profile::dashboards class:

• token
• grafana_host
• grafana_port
• grafana_timeout
• grafana_password
• grafana_version
• grafana_datasource
• grafana_install
• use_ssl
• manage_grafana
• manage_grafana_repo
• influxdb_host
• influxdb_port
• influxdb_bucket
• telegraf_token_name
• influxdb_token_file
• provisioning_datasource_file

token

Data type: Optional[Sensitive[String]]

Token in Sensitive format used to query InfluxDB. The token must grant priviledges to query the associated bucket in InfluxDB

Default value: $puppet_operational_dashboards::telegraf_token

grafana_host

Data type: String

FQDN of the Grafana host. Defaults to the FQDN of the agent receiving the catalog.

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

grafana_port

Data type: Integer

Port used by the Grafana service. Defaults to 3000

Default value: 3000

grafana_timeout

Data type: Integer

How long to wait for the Grafana service to start. Defaults to 10 seconds.

Default value: 10

grafana_password

Data type: Sensitive[String]

Grafana admin password in Sensitive format. Defaults to 'admin'

Default value: Sensitive('admin')

grafana_version

Data type: String

Version of the Grafana package to install. Defaults to '8.2.2'

Default value: '8.2.7'

grafana_datasource

Data type: String

Name to use for the Grafana datasource. Defaults to 'influxdb_puppet'

Default value: 'influxdb_puppet'

grafana_install

Data type: String

Method to use for installing Grafana. Defaults to using a repository on EL and Debian/Ubuntu, and package for other platforms

Default value: $facts['os']['family']

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB. Defaults to true

Default value: $puppet_operational_dashboards::use_ssl

manage_grafana

Data type: Boolean

Whether to manage installation and configuration of Grafana. Defaults to true

Default value: true

manage_grafana_repo

Data type: Boolean

Whether to manage the Grafana repository definition. Defaults to true.

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host. Defaults to the value of the base class, which looks up the value of influxdb::host with a default of $facts['fqdn']

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service. Defaults to the value of the base class, which looks up the value of influxdb::port with a default of 8086

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query. Defaults to the value of the base class, which looks up the value of influxdb::initial_bucket with a default of 'puppet_data'

Default value: $puppet_operational_dashboards::initial_bucket

telegraf_token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $token

Default value: $puppet_operational_dashboards::telegraf_token_name

influxdb_token_file

Data type: String

Location on disk of an InfluxDB admin token. This token is used in this class in a Deferred function call to retrieve a Telegraf token if $token is unset

Default value: $puppet_operational_dashboards::influxdb_token_file

provisioning_datasource_file

Data type: String

Location on disk to store datasource definition

Default value: '/etc/grafana/provisioning/datasources/influxdb.yaml'

puppet_operational_dashboards::profile::postgres_access

Allows Telegraf to connect and collect metrics from postgres nodes

Examples

Basic usage

include puppet_operational_dashboards::profile::postgres_access

Parameters

The following parameters are available in the puppet_operational_dashboards::profile::postgres_access class:

• telegraf_hosts

telegraf_hosts

Data type: Array

A list of FQDNs running Telegraf to allow access to

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_operational_dashboards::Telegraf::Agent')

puppet_operational_dashboards::telegraf::agent

Installs and configures Telegraf to query hosts in a Puppet infrastructure. Included by the base class

Examples

Basic usage

include puppet_operational_dashboards

class {'puppet_operational_dashboards::telegraf::agent':
  token => '<sensitive_telegraf_token>',
}

Parameters

The following parameters are available in the puppet_operational_dashboards::telegraf::agent class:

• token
• influxdb_host
• influxdb_port
• influxdb_org
• influxdb_bucket
• use_ssl
• manage_ssl
• manage_repo
• manage_archive
• manage_user
• ssl_cert_file
• ssl_key_file
• ssl_ca_file
• insecure_skip_verify
• version
• archive_location
• archive_install_dir
• collection_method
• collection_interval
• puppetserver_hosts
• puppetdb_hosts
• postgres_hosts
• profiles
• local_services
• token_name
• influxdb_token_file
• http_timeout_seconds

token

Data type: Optional[Sensitive[String]]

Telegraf token in Sensitive format.

Default value: $puppet_operational_dashboards::telegraf_token

influxdb_host

Data type: String

FQDN of the InfluxDB host. Defaults to $facts['fqdn']

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service. Defaults to 8086.

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_org

Data type: String

Name of the InfluxDB organization. Defaults to 'puppetlabs'.

Default value: $puppet_operational_dashboards::initial_org

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query. Defaults to 'puppet_data'.

Default value: $puppet_operational_dashboards::initial_bucket

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB. Defaults to true

Default value: $puppet_operational_dashboards::use_ssl

manage_ssl

Data type: Boolean

Whether to manage Telegraf ssl configuration. Defaults to true.

Default value: true

manage_repo

Data type: Boolean

Whether to install Telegraf from a repository. Defaults to true on the RedHat family of platforms.

manage_archive

Data type: Boolean

Whether to install Telegraf from an archive source. Defaults to true on platforms other than RedHat.

Default value: !

manage_user

Data type: Boolean

Whether to manage the telegraf user when installing from archive. Defaults to true.

Default value: true

ssl_cert_file

Data type: String

SSL certificate to be used by the telegraf service. Defaults to the agent certificate issued by the Puppet CA for the local machine.

Default value: "/etc/puppetlabs/puppet/ssl/certs/${trusted['certname']}.pem"

ssl_key_file

Data type: String

Private key used in the CSR for the certificate specified by $ssl_cert_file. Defaults to the private key of the local machine for generating a CSR for the Puppet CA

Default value: "/etc/puppetlabs/puppet/ssl/private_keys/${trusted['certname']}.pem"

ssl_ca_file

Data type: String

CA certificate issued by the CA which signed the certificate specified by $ssl_cert_file. Defaults to the Puppet CA.

Default value: '/etc/puppetlabs/puppet/ssl/certs/ca.pem'

insecure_skip_verify

Data type: Boolean

Skip verification of SSL certificate. Defaults to true.

Default value: true

version

Data type: String

Version of the Telegraf package to install. Defaults to '1.24.3'.

archive_location

Data type: String

URL containing an archive source for the telegraf package. Defaults to downloading $version from dl.influxdata.com Version of the Telegraf package to install. Defaults to '1.24.3'.

Default value: "https://dl.influxdata.com/telegraf/releases/telegraf-${version.split('-')[0]}_linux_amd64.tar.gz"

archive_install_dir

Data type: String

Directory to install $archive_location to. Defaults to /opt/telegraf.

Default value: '/opt/telegraf'

collection_method

Data type: Enum['all', 'local', 'none']

Determines how metrics will be collected. 'all' will query all Puppet services across all Puppet infrastructure hosts from the node with this class applied. 'local' will query all Puppet services on the node with this class applied. 'none' will not query any services from the node with this class applied.

Default value: 'all'

collection_interval

Data type: String

How frequently to collect metrics. Defaults to '10m'.

Default value: '10m'

puppetserver_hosts

Data type: Array

Array of Puppet server hosts to collect metrics from. Defaults to all Puppet server hosts in a PE infrastructure. FOSS users need to supply a list of FQDNs

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Master')

puppetdb_hosts

Data type: Array

Array of PuppetDB hosts to collect metrics from. Defaults to all PuppetDB hosts in a PE infrastructure. FOSS users need to supply a list of FQDNs

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Puppetdb')

postgres_hosts

Data type: Array

Array of Postgres hosts to collect metrics from. Defaults to all Postgres in a PE infrastructure. FOSS users need to supply a list of FQDNs.

Default value: puppet_operational_dashboards::hosts_with_profile('Puppet_enterprise::Profile::Database')

profiles

Data type: Array[String]

Array of PE profiles on the node with this class applied. Used when collection_method is set to 'local'. FOSS users can use the $local_services parameter.

Default value: puppet_operational_dashboards::pe_profiles_on_host()

local_services

Data type: Array[String]

Array of FOSS services to collect from when collection_method is set to 'local'.

Default value: []

token_name

Data type: String

Name of the token to retrieve from InfluxDB if not given $token

Default value: $puppet_operational_dashboards::telegraf_token_name

influxdb_token_file

Data type: String

Location on disk of an InfluxDB admin token. This token is used in this class in a Deferred function call to retrieve a Telegraf token if $token is unset

Default value: $puppet_operational_dashboards::influxdb_token_file

http_timeout_seconds

Data type: Integer[1]

Timeout for HTTP Telegraf inputs. Might be usefull in huge environments with slower API responses

Default value: 5

Defined types

puppet_operational_dashboards::telegraf::config

Defined type to create Telegraf configurations for a given service

Parameters

The following parameters are available in the puppet_operational_dashboards::telegraf::config defined type:

• service
• protocol
• hosts
• ensure
• http_timeout_seconds

service

Data type: String

Name of the service to query. Is the title of the resource.

Default value: $title

protocol

Data type: Enum['https', 'http']

Protocol to use in requests, either https or http

hosts

Data type: Array[String[1]]

Array of hosts running the service

ensure

Data type: Enum['present', 'absent']

Whether the resource should be present or absent

Default value: 'present'

http_timeout_seconds

Data type: Integer[1]

Timeout for HTTP Telegraf inputs. Might be usefull in huge environments with slower API responses

Functions

puppet_operational_dashboards::hosts_with_profile

Type: Puppet Language

Queries PuppetDB for hosts with the specified profile. Used by this module to identify hosts with Puppet Enterprise API endpoints and Telegraf hosts

puppet_operational_dashboards::hosts_with_profile(String $profile)

Queries PuppetDB for hosts with the specified profile. Used by this module to identify hosts with Puppet Enterprise API endpoints and Telegraf hosts

Returns: Array[String] An array of certnames from the query

profile

Data type: String

The full name of the profile to query.

puppet_operational_dashboards::pe_profiles_on_host

Type: Puppet Language

Queries PuppetDB for Puppet Enterprise profile on the node including the class. Used by this module to identify Puppet Enterprise API endpoints on the node.

puppet_operational_dashboards::pe_profiles_on_host()

Queries PuppetDB for Puppet Enterprise profile on the node including the class. Used by this module to identify Puppet Enterprise API endpoints on the node.

Returns: Array[String] An array of PE profiles representing the Puppet server, PDB, and postgres services

Plans

puppet_operational_dashboards::load_metrics

The summary sets the description of the plan that will appear in 'bolt plan show' output. Bolt uses puppet-strings to parse the summary and parameters from the plan.

Parameters

The following parameters are available in the puppet_operational_dashboards::load_metrics plan:

• targets
• support_script_file
• metrics_dir
• dest_dir
• cleanup_metrics
• influxdb_org
• influxdb_bucket
• influxdb_port
• grafana_datasource
• telegraf_token
• token_file
• conf_dir
• telegraf_process
• token

targets

Data type: TargetSpec

The targets to run on.

support_script_file

Data type: Optional[String]

Path to a support script tarball

Default value: undef

metrics_dir

Data type: Optional[String]

Path to the 'metrics' directory from a PE support script

Default value: undef

dest_dir

Data type: String

Directory to upload $metrics_dir to

Default value: '/tmp'

cleanup_metrics

Data type: String

Whether to delete metrics after processing

Default value: 'true'

influxdb_org

Data type: String

Name of the InfluxDB organization to configure. Defaults to 'puppetlabs'

Default value: 'puppetlabs'

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to configure and query. Defaults to 'puppet_data'

Default value: 'influxdb_puppet'

influxdb_port

Data type: Integer

Port used by the InfluxDB service. Defaults to the value of influxdb::port, or 8086 if unset

Default value: 8086

grafana_datasource

Data type: String

Name of the Grafana datasource. Must match the name of the InfluxDB bucket

Default value: $influxdb_bucket

telegraf_token

Data type: String

Name of the token to retrieve from InfluxDB. Defaults to 'puppet telegraf token'

Default value: 'puppet telegraf token'

token_file

Data type: String

Location on disk of an InfluxDB admin token. This file is written to by the influxdb class during installation and read by the type and providers, as well Deferred functions in this module.

Default value: '/root/.influxdb_token'

conf_dir

Data type: String

Directory to upload Telegraf configuration files to

Default value: '/tmp/telegraf'

telegraf_process

Data type: Enum['local', 'remote']

Default value: 'remote'

token

Data type: Optional[String]

Default value: undef

puppet_operational_dashboards::provision_dashboard

A plan to provision a non-SSL operational dashboards node

Parameters

The following parameters are available in the puppet_operational_dashboards::provision_dashboard plan:

• targets

targets

Data type: TargetSpec

The targets to run on.