Skip to content

Latest commit

 

History

History
1233 lines (700 loc) · 43 KB

REFERENCE.md

File metadata and controls

1233 lines (700 loc) · 43 KB
Raw

Reference

Table of Contents

Classes

Defined types

Functions

Plans

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

Data type: Boolean

Whether to manage installation and configuration of InfluxDB.

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host.

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

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

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

initial_org

Data type: String

Name of the InfluxDB organization to configure.

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

initial_bucket

Data type: String

Name of the InfluxDB bucket to configure and query.

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

influxdb_bucket_retention_rules

Data type: Array

Value for the initial InfluxDB bucket retention rules, Values are the same as in the influx_bucket type of the InfluxDB module.

Default value: [{ 'type' => 'expire', 'everySeconds' => 7776000, 'shardGroupDurationSeconds' => 604800 }]

influxdb_token

Data type: Optional[Sensitive[String]]

InfluxDB admin token in Sensitive format. 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.

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.

Default value: true

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: true

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: lookup(influxdb::use_system_store, undef, undef, false)

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

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value:

$settings::module_groups ? {
    /pe_only/ => true,
    default   => false
manage_system_board

Data type: Boolean

Whether the System Performance dashboard should be added to grafana

Default value: true

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

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

Data type: Array[String]

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

Default value: puppet_operational_dashboards::pe_profiles_on_host()

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

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

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.

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

grafana_port

Data type: Integer

Port used by the Grafana service.

Default value: 3000

grafana_use_ssl

Data type: Boolean

Enable use of HTTPS/SSL for Grafana.

Default value: false

manage_grafana_ssl

Data type: Boolean

Whether to manage the SSL certificate files when using the grafana_use_ssl parameter.

Default value: true

grafana_cert_file

Data type: Stdlib::Absolutepath

SSL certificate file to use when 'grafana_use_ssl' and 'manage_grafana' are enabled.

Default value: '/etc/grafana/client.pem'

grafana_key_file

Data type: Stdlib::Absolutepath

SSL private key file to use when 'grafana_use_ssl' and 'manage_grafana' are enabled.

Default value: '/etc/grafana/client.key'

grafana_cert_file_source

Data type: Stdlib::Absolutepath

SSL certificate file to use as the source for the grafana_cert_file parameter.

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

grafana_key_file_source

Data type: Stdlib::Absolutepath

SSL certificate file to use as the source for the grafana_key_file parameter.

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

grafana_timeout

Data type: Integer

How long to wait for the Grafana service to start.

Default value: 10

grafana_password

Data type: Sensitive[String]

Grafana admin password in Sensitive format.

Default value: Sensitive('admin')

grafana_version

Data type: String

Version of the Grafana package to install.

Default value: '8.5.27'

grafana_datasource

Data type: String

Name to use for the Grafana datasource.

Default value: 'influxdb_puppet'

grafana_install

Data type: String

Method to use for installing Grafana.

Default value:

$facts['os']['family'] ? {
    /(RedHat|Debian)/ => 'repo',
    default           => 'package'
use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: $puppet_operational_dashboards::use_ssl

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: $puppet_operational_dashboards::use_system_store

manage_grafana

Data type: Boolean

Whether to manage installation and configuration of Grafana.

Default value: true

manage_grafana_repo

Data type: Boolean

Whether to manage the Grafana repository definition.

Default value: true

influxdb_host

Data type: String

FQDN of the InfluxDB host.

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query.

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: Stdlib::Absolutepath

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: Stdlib::Absolutepath

Location on disk to store datasource definition

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

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value: $puppet_operational_dashboards::include_pe_metrics

manage_system_board

Data type: Boolean

Whether the System Performance dashboard should be created

Default value: $puppet_operational_dashboards::manage_system_board

system_dashboard_version

Data type: Enum['v1', 'v2', 'all']

Version of the system dashboard to manage. v2 is compatible with puppet_metrics_collector version 7 and up

Default value: 'v2'

puppet_operational_dashboards::profile::foss_postgres_access

Allows Telegraf to connect and collect metrics from postgres nodes

Examples

Basic usage
include puppet_operational_dashboards::profile::foss_postgres_access

Parameters

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

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')

telegraf_user

Data type: String

Username for the Telegraf client to use in the postgres connection string

Default value: 'telegraf'

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

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

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.

Default value: $puppet_operational_dashboards::influxdb_host

influxdb_port

Data type: Integer

Port used by the InfluxDB service.

Default value: $puppet_operational_dashboards::influxdb_port

influxdb_org

Data type: String

Name of the InfluxDB organization.

Default value: $puppet_operational_dashboards::initial_org

influxdb_bucket

Data type: String

Name of the InfluxDB bucket to query.

Default value: $puppet_operational_dashboards::initial_bucket

use_ssl

Data type: Boolean

Whether to use SSL when querying InfluxDB.

Default value: $puppet_operational_dashboards::use_ssl

use_system_store

Data type: Boolean

Whether to use the system CA bundle.

Default value: $puppet_operational_dashboards::use_system_store

manage_ssl

Data type: Boolean

Whether to manage Telegraf ssl configuration.

Default value: true

manage_repo

Data type: Boolean

Whether to install Telegraf from a repository.

manage_archive

Data type: Boolean

Whether to install Telegraf from an archive source.

Default value: !$manage_repo

manage_user

Data type: Boolean

Whether to manage the telegraf user when installing from archive.

Default value: true

ssl_cert_file

Data type: Stdlib::Absolutepath

SSL certificate to be used by the telegraf service.

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

ssl_key_file

Data type: Stdlib::Absolutepath

Private key used in the CSR for the certificate specified by $ssl_cert_file.

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

ssl_ca_file

Data type: Stdlib::Absolutepath

CA certificate issued by the CA which signed the certificate specified by $ssl_cert_file.

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

puppet_ssl_cert_file

Data type: Stdlib::Absolutepath

SSL certificate to be used by the telegraf inputs.

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

puppet_ssl_key_file

Data type: Stdlib::Absolutepath

Private key used in the CSR for the certificate specified by $puppet_ssl_cert_file.

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

puppet_ssl_ca_file

Data type: Stdlib::Absolutepath

CA certificate issued by the CA which signed the certificate specified by $puppet_ssl_cert_file.

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

insecure_skip_verify

Data type: Boolean

Skip verification of SSL certificate.

Default value: true

version

Data type: String

Version of the Telegraf package to install.

archive_location

Data type: String

URL containing an archive source for the telegraf package. Defaults to downloading $version from dl.influxdata.com

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.

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.

Default value: '10m'

puppetserver_hosts

Data type: Array

Array of Puppet server hosts to collect metrics from. 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. 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. FOSS users need to supply a list of FQDNs.

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

orchestrator_hosts

Data type: Array

Array of Orchestrator hosts to collect metrics from. FOSS users need to supply a list of FQDNs.

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

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

include_pe_metrics

Data type: Boolean

Whether to include Filesync and Orchestrator dashboards

Default value: $puppet_operational_dashboards::include_pe_metrics

telegraf_user

Data type: String

Username for the Telegraf client to use in the postgres connection string

Default value: 'telegraf'

telegraf_postgres_password

Data type: Optional[Sensitive[String]]

Optional Sensitive password for the Telegraf client to use in the postgres connection string

Default value: undef

postgres_port

Data type: Integer

Port for the Telegraf client to use in the postgres connection string

Default value: 5432

postgres_options

Data type: Hash

Hash of options for the Telegraf client to use as connection parameters in the postgres connection string

Default value:

{
    'sslmode'     => 'verify-full',
    'sslkey'      => '/etc/telegraf/puppet_key.pem',
    'sslcert'     => '/etc/telegraf/puppet_cert.pem',
    'sslrootcert' => '/etc/telegraf/puppet_ca.pem',
  }
template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: $puppet_operational_dashboards::template_format

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

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

template_format

Data type: Enum['yaml','toml']

Template format to use for puppet template toml or yaml config

Default value: 'toml'

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

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'

retention_rules

Data type: Array[Hash]

Default value:

[{
      'type' => 'expire',
      'everySeconds' => 3456000,
      'shardGroupDurationSeconds' => 604800,
  }]
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

Data type: TargetSpec

The targets to run on.