Skip to content

Latest commit

 

History

History
2244 lines (1338 loc) · 75.5 KB

REFERENCE.md

File metadata and controls

2244 lines (1338 loc) · 75.5 KB
Raw

Reference

Table of Contents

Classes

Public Classes

Private Classes

  • puppetdb::database::ssl_configuration: configure SSL for the PuppetDB postgresql database
  • puppetdb::master::puppetdb_conf: manage the puppetdb.conf file on the puppet primary
  • puppetdb::master::report_processor: manage the installation of the report processor on the primary
  • puppetdb::master::routes: manages the routes configuration file on the master
  • puppetdb::master::storeconfigs: configure the puppet master to enable storeconfigs and to use puppetdb as the storeconfigs backend
  • puppetdb::params: default configuration settings
  • puppetdb::server::command_processing: manage puppetdb config ini
  • puppetdb::server::database: manage puppetdb database ini
  • puppetdb::server::firewall: manage puppetdb firewall rules
  • puppetdb::server::global: manage puppetdb global setting
  • puppetdb::server::jetty: configures puppetdb jetty ini
  • puppetdb::server::puppetdb: manage puppetdb ini
  • puppetdb::server::read_database: manage puppetdb read_database ini
  • puppetdb::server::validate_db: validates the database connection
  • puppetdb::server::validate_read_db: validates the read only database connection

Defined types

Private Defined types

  • puppetdb::database::default_read_grant: grant read permissions to $database_read_only_username by default, for new tables created by $database_username
  • puppetdb::database::postgresql_ssl_rules: manage the pg_ident.conf and pg_hba.conf files
  • puppetdb::database::read_grant: grant read-only permissions to $database_read_only_username for all objects in $schema of $database_name
  • puppetdb::database::read_only_user: manage the creation of a read-only postgres users

Resource types

  • puppetdb_conn_validator: Verify that a connection can be successfully established between a node and the puppetdb server. Its primary use is as a precondition to pre

Functions

Data types

Classes

puppetdb

manage PuppetDB

Parameters

The following parameters are available in the puppetdb class:

listen_address

Data type: Any

The address that the web server should bind to for HTTP requests. Defaults to localhost. Set to 0.0.0.0 to listen on all addresses.

Default value: $puppetdb::params::listen_address

listen_port

Data type: Any

The port on which the puppetdb web server should accept HTTP requests. Defaults to 8080.

Default value: $puppetdb::params::listen_port

disable_cleartext

Data type: Any

If true, the puppetdb web server will only serve HTTPS and not HTTP requests (defaults to false).

Default value: $puppetdb::params::disable_cleartext

open_listen_port

Data type: Any

If true, open the http_listen_port on the firewall. Defaults to false.

Default value: $puppetdb::params::open_listen_port

ssl_listen_address

Data type: Any

The address that the web server should bind to for HTTPS requests. Defaults to 0.0.0.0 to listen on all addresses.

Default value: $puppetdb::params::ssl_listen_address

ssl_listen_port

Data type: Any

The port on which the puppetdb web server should accept HTTPS requests. Defaults to 8081.

Default value: $puppetdb::params::ssl_listen_port

disable_ssl

Data type: Any

If true, the puppetdb web server will only serve HTTP and not HTTPS requests. Defaults to false.

Default value: $puppetdb::params::disable_ssl

open_ssl_listen_port

Data type: Any

If true, open the ssl_listen_port on the firewall. Defaults to undef.

Default value: $puppetdb::params::open_ssl_listen_port

ssl_protocols

Data type: Any

Specify the supported SSL protocols for PuppetDB (e.g. TLSv1, TLSv1.1, TLSv1.2.)

Default value: $puppetdb::params::ssl_protocols

postgresql_ssl_on

Data type: Any

If true, it configures SSL connections between PuppetDB and the PostgreSQL database. Defaults to false.

Default value: $puppetdb::params::postgresql_ssl_on

postgresql_ssl_folder

Data type: Any

Path to the Postgresql SSL folder.

Default value: $puppetdb::params::postgresql_ssl_folder

postgresql_ssl_cert_path

Data type: Any

Path to the Postgresql SSL certificate.

Default value: $puppetdb::params::postgresql_ssl_cert_path

postgresql_ssl_key_path

Data type: Any

Path to the Postgresql SSL key.

Default value: $puppetdb::params::postgresql_ssl_key_path

postgresql_ssl_ca_cert_path

Data type: Any

Path to the Postgresql SSL CA.

Default value: $puppetdb::params::postgresql_ssl_ca_cert_path

cipher_suites

Data type: Any

Configure jetty's supported cipher-suites (e.g. SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384). Defaults to undef.

Default value: $puppetdb::params::cipher_suites

migrate

Data type: Any

If true, puppetdb will automatically migrate to the latest database format at startup. If false, if the database format supplied by this version of PuppetDB doesn't match the version expected (whether newer or older), PuppetDB will exit with an error status. Defaults to true.

Default value: $puppetdb::params::migrate

manage_dbserver

Data type: Any

If true, the PostgreSQL server will be managed by this module. Defaults to true.

Default value: $puppetdb::params::manage_dbserver

manage_database

Data type: Any

If true, the PostgreSQL database will be managed by this module. Defaults to true.

Default value: $puppetdb::params::manage_database

manage_package_repo

Data type: Any

If true, the official postgresql.org repo will be added and postgres won't be installed from the regular repository. Defaults to true.

Default value: $puppetdb::params::manage_pg_repo

postgres_version

Data type: Any

If the postgresql.org repo is installed, you can install several versions of postgres. Defaults to 11 with PuppetDB version 7.0.0 or newer, and 9.6 in older versions.

Default value: $puppetdb::params::postgres_version

database_host

Data type: Any

Hostname to use for the database connection. For single case installations this should be left as the default. Defaults to localhost.

Default value: $puppetdb::params::database_host

database_port

Data type: Any

The port that the database server listens on. Defaults to 5432.

Default value: $puppetdb::params::database_port

database_username

Data type: Any

The name of the database user to connect as. Defaults to puppetdb.

Default value: $puppetdb::params::database_username

database_password

Data type: Variant[String[1], Sensitive[String[1]]]

The password for the database user. Defaults to puppetdb.

Default value: $puppetdb::params::database_password

manage_db_password

Data type: Any

Whether or not the database password in database.ini will be managed by this module. Set this to false if you want to set the password some other way. Defaults to true

Default value: $puppetdb::params::manage_db_password

database_name

Data type: Any

The name of the database instance to connect to. Defaults to puppetdb.

Default value: $puppetdb::params::database_name

jdbc_ssl_properties

Data type: Any

The text to append to the JDBC connection URI. This should begin with a '?' character. For example, to use SSL for the PostgreSQL connection, set this parameter's value to ?ssl=true.

Default value: $puppetdb::params::jdbc_ssl_properties

database_listen_address

Data type: Any

A comma-separated list of hostnames or IP addresses on which the postgres server should listen for incoming connections. This defaults to localhost. This parameter maps directly to PostgreSQL's listen_addresses config option. Use a * to allow connections on any accessible address.

Default value: $puppetdb::params::postgres_listen_addresses

database_validate

Data type: Any

If true, the module will attempt to connect to the database using the specified settings and fail if it is not able to do so. Defaults to true.

Default value: $puppetdb::params::database_validate

node_ttl

Data type: Any

The length of time a node can go without receiving any new data before it's automatically deactivated. (defaults to '7d', which is a 7-day period. Set to '0d' to disable auto-deactivation). This option is supported in PuppetDB >= 1.1.0.

Default value: $puppetdb::params::node_ttl

node_purge_ttl

Data type: Any

The length of time a node can be deactivated before it's deleted from the database. (defaults to '14d', which is a 14-day period. Set to '0d' to disable purging). This option is supported in PuppetDB >= 1.2.0.

Default value: $puppetdb::params::node_purge_ttl

report_ttl

Data type: Any

The length of time reports should be stored before being deleted. (defaults to 14d, which is a 14-day period). This option is supported in PuppetDB >= 1.1.0.

Default value: $puppetdb::params::report_ttl

facts_blacklist

Data type: Optional[Array]

A list of fact names to be ignored whenever submitted.

Default value: $puppetdb::params::facts_blacklist

gc_interval

Data type: Any

This controls how often (in minutes) to compact the database. The compaction process reclaims space and deletes unnecessary rows. If not supplied, the default is every 60 minutes. This option is supported in PuppetDB >= 0.9.

Default value: $puppetdb::params::gc_interval

node_purge_gc_batch_limit

Data type: Any

Nodes will be purged in batches of this size, one batch per gc-interval.

Default value: $puppetdb::params::node_purge_gc_batch_limit

conn_max_age

Data type: Any

The maximum time (in minutes) for a pooled connection to remain unused before it is closed off.

If not supplied, we default to 60 minutes. This option is supported in PuppetDB >= 1.1.

Default value: $puppetdb::params::conn_max_age

conn_lifetime

Data type: Any

The maximum time (in minutes) a pooled connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone. This option is supported in PuppetDB >= 1.4.

Default value: $puppetdb::params::conn_lifetime

puppetdb_package

Data type: Any

The PuppetDB package name in the package manager. Defaults to present.

Default value: $puppetdb::params::puppetdb_package

puppetdb_service

Data type: Any

The name of the PuppetDB service. Defaults to puppetdb.

Default value: $puppetdb::params::puppetdb_service

puppetdb_service_status

Data type: Any

Sets whether the service should be running or stopped. When set to stopped the service doesn't start on boot either. Valid values are true, running, false, and stopped.

Default value: $puppetdb::params::puppetdb_service_status

puppetdb_user

Data type: Any

Puppetdb service user

Default value: $puppetdb::params::puppetdb_user

puppetdb_group

Data type: Any

Puppetdb service group

Default value: $puppetdb::params::puppetdb_group

puppetdb_server

Data type: Any

Puppetdb server hostname or IP address.

Default value: $puppetdb::params::puppetdb_server

confdir

Data type: Any

The PuppetDB configuration directory. Defaults to /etc/puppetdb/conf.d.

Default value: $puppetdb::params::confdir

vardir

Data type: Any

The parent directory for the MQ's data directory.

Default value: $puppetdb::params::vardir

java_args

Data type: Any

Java VM options used for overriding default Java VM options specified in PuppetDB package. Defaults to {}. See PuppetDB Configuration to get more details about the current defaults.

For example, to set -Xmx512m -Xms256m options use:

{
    '-Xmx' => '512m',
    '-Xms' => '256m',
}

Default value: $puppetdb::params::java_args

merge_default_java_args

Data type: Any

Sets whether the provided java args should be merged with the defaults, or should override the defaults. This setting is necessary if any of the defaults are to be removed. Defaults to true. If false, the java_args in the PuppetDB init config file will reflect only what is passed via the java_args param.

Default value: $puppetdb::params::merge_default_java_args

max_threads

Data type: Any

Jetty option to explicitly set max-threads. Defaults to undef, so the PuppetDB-Jetty default is used.

Default value: $puppetdb::params::max_threads

read_database_host

Data type: Any

This parameter must be set to use another PuppetDB instance for queries.

The hostname or IP address of the read database server. If set to undef, and manage_database is set to true, it will use the value of the database_host parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_host

read_database_port

Data type: Any

The port that the read database server listens on. If read_database_host is set to undef, and manage_database is set to true, it will use the value of the database_port parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_port

read_database_username

Data type: Any

The name of the read database user to connect as. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_username

read_database_password

Data type: Variant[String[1], Sensitive[String[1]]]

The password for the read database user. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_password

manage_read_db_password

Data type: Any

Whether or not the database password in read-database.ini will be managed by this module. Set this to false if you want to set the password some other way. Defaults to true

Default value: $puppetdb::params::manage_read_db_password

read_database_jdbc_ssl_properties

Data type: Any

The text to append to the JDBC connection URI. This should begin with a '?' character. For example, to use SSL for the PostgreSQL connection, set this parameter's value to ?ssl=true.

Default value: $puppetdb::params::read_database_jdbc_ssl_properties

read_database_validate

Data type: Any

If true, the module will attempt to connect to the database using the specified settings and fail if it is not able to do so. Defaults to true.

Default value: $puppetdb::params::read_database_validate

read_database_name

Data type: Any

The name of the read database instance to connect to. If read_database_host is set to undef, and manage_database is set to true, it will use the value of the database_name parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_name

read_conn_max_age

Data type: Any

The maximum time (in minutes) for a pooled read database connection to remain unused before it is closed off.

If not supplied, we default to 60 minutes. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_conn_max_age

read_conn_lifetime

Data type: Any

The maximum time (in minutes) a pooled read database connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_conn_lifetime

ssl_dir

Data type: Any

Base directory for PuppetDB SSL configuration. Defaults to /etc/puppetdb/ssl or /etc/puppetlabs/puppetdb/ssl for FOSS and PE respectively.

Default value: $puppetdb::params::ssl_dir

ssl_set_cert_paths

Data type: Any

A switch to enable or disable the management of SSL certificates in your jetty.ini configuration file.

Default value: $puppetdb::params::ssl_set_cert_paths

ssl_cert_path

Data type: Any

Path to your SSL certificate for populating jetty.ini.

Default value: $puppetdb::params::ssl_cert_path

ssl_key_pk8_path

Data type: Any

Path to the SSL pk8 key for populating jetty.ini, will be generated from the SSL key as needed automatically.

Default value: $puppetdb::params::ssl_key_pk8_path

ssl_key_path

Data type: Any

Path to your SSL key for populating jetty.ini.

Default value: $puppetdb::params::ssl_key_path

ssl_ca_cert_path

Data type: Any

Path to your SSL CA for populating jetty.ini.

Default value: $puppetdb::params::ssl_ca_cert_path

ssl_deploy_certs

Data type: Any

A boolean switch to enable or disable the management of SSL keys in your ssl_dir. Default is false.

Default value: $puppetdb::params::ssl_deploy_certs

ssl_key

Data type: Any

Contents of your SSL key, as a string.

Default value: $puppetdb::params::ssl_key

ssl_cert

Data type: Any

Contents of your SSL certificate, as a string.

Default value: $puppetdb::params::ssl_cert

ssl_ca_cert

Data type: Any

Contents of your SSL CA certificate, as a string.

Default value: $puppetdb::params::ssl_ca_cert

manage_firewall

Data type: Any

If true, puppet will manage your iptables rules for PuppetDB via the puppetlabs-firewall class.

Default value: $puppetdb::params::manage_firewall

command_threads

Data type: Any

The number of command processing threads to use. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::command_threads

concurrent_writes

Data type: Any

The number of threads allowed to write to disk at any one time. Defaults to undef, which uses the PuppetDB built-in default.

Default value: $puppetdb::params::concurrent_writes

store_usage

Data type: Any

The amount of disk space (in MB) to allow for persistent message storage. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::store_usage

temp_usage

Data type: Any

The amount of disk space (in MB) to allow for temporary message storage. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::temp_usage

disable_update_checking

Data type: Any

Setting this to true disables checking for updated versions of PuppetDB and sending basic analytics data to Puppet. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::disable_update_checking

certificate_whitelist_file

Data type: Any

The name of the certificate whitelist file to set up and configure in PuppetDB. Defaults to /etc/puppetdb/certificate-whitelist or /etc/puppetlabs/puppetdb/certificate-whitelist for FOSS and PE respectively.

Default value: $puppetdb::params::certificate_whitelist_file

certificate_whitelist

Data type: Any

Array of the X.509 certificate Common Names of clients allowed to connect to PuppetDB. Defaults to empty. Be aware that this permits full access to all Puppet clients to download anything contained in PuppetDB, including the full catalogs of all nodes, which possibly contain sensitive information. Set to [ $::servername ] to allow access only from your (single) Puppet master, which is enough for normal operation. Set to a list of Puppet masters if you have multiple.

Default value: $puppetdb::params::certificate_whitelist

database_max_pool_size

Data type: Any

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out. Note that PuppetDB will use one pool for writes and another for reads, so the total number of connections used will be twice this setting.

Default value: $puppetdb::params::database_max_pool_size

read_database_max_pool_size

Data type: Any

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out. Note that PuppetDB will use one pool for writes and another for reads, so the total number of connections used will be twice this setting.

Default value: $puppetdb::params::read_database_max_pool_size

automatic_dlo_cleanup

Data type: Boolean

PuppetDB creates Dead Letter Office. Those are reports of failed requests. They spill up the disk. This parameter is a boolean and defaults to false. You can enable automatic cleanup of DLO reports by setting this to true.

Default value: $puppetdb::params::automatic_dlo_cleanup

cleanup_timer_interval

Data type: String[1]

The DLO cleanup is a systemd timer if systemd is available, otherwise a cronjob. The variable configures the systemd.timer option onCalender. It defaults to *-*-* ${fqdn_rand(24)}:${fqdn_rand(60)}:00. This will start the cleanup service on a daily basis. The exact minute and hour is random per node based on the fqdn_rand method. On non-systemd systems, the cron runs daily and the $puppetdb_user needs to be able to run cron jobs. On systemd systems you need the camptocamp/systemd module, which is an optional dependency and not automatically installed!

Default value: $puppetdb::params::cleanup_timer_interval

dlo_max_age

Data type: Integer[1]

This is a positive integer. It describes the amount of days you want to keep the DLO reports. The default value is 90 days.

Default value: $puppetdb::params::dlo_max_age

java_bin

Data type: Optional[Stdlib::Absolutepath]

java binary path for PuppetDB. If undef, default will be used.

Default value: $puppetdb::params::java_bin

postgresql_password_encryption

Data type: Postgresql::Pg_password_encryption

PostgreSQL password authentication method, either md5 or scram-sha-256

Default value: $puppetdb::params::password_encryption

puppetdb::database::postgresql

create the PuppetDB postgresql database

Parameters

The following parameters are available in the puppetdb::database::postgresql class:

listen_addresses

Data type: Any

The listen_address is a comma-separated list of hostnames or IP addresses on which the postgres server should listen for incoming connections. This defaults to localhost. This parameter maps directly to PostgreSQL's listen_addresses config option. Use a * to allow connections on any accessible address.

Default value: $puppetdb::params::database_host

puppetdb_server

Data type: Any

Hostname or IP address to configure for SSL rules.

Default value: $puppetdb::params::puppetdb_server

database_name

Data type: Any

Sets the name of the database. Defaults to puppetdb.

Default value: $puppetdb::params::database_name

database_username

Data type: Any

Creates a user for access the database. Defaults to puppetdb.

Default value: $puppetdb::params::database_username

database_password

Data type: Variant[String[1], Sensitive[String[1]]]

Sets the password for the database user above. Defaults to puppetdb.

Default value: $puppetdb::params::database_password

database_port

Data type: Any

The port that the database server listens on. Defaults to 5432.

Default value: $puppetdb::params::database_port

manage_database

Data type: Any

If true, the PostgreSQL database will be managed by this module. Defaults to true.

Default value: $puppetdb::params::manage_database

manage_server

Data type: Any

Conditionally manages the PostgreSQL server via postgresql::server. Defaults to true. If set to false, this class will create the database and user via postgresql::server::db but not attempt to install or manage the server itself.

Default value: $puppetdb::params::manage_dbserver

manage_package_repo

Data type: Any

If true, the official postgresql.org repo will be added and postgres won't be installed from the regular repository. Defaults to true.

Default value: $puppetdb::params::manage_pg_repo

postgres_version

Data type: Any

If the postgresql.org repo is installed, you can install several versions of postgres. Defaults to 11 with PuppetDB version 7.0.0 or newer, and 9.6 in older versions.

Default value: $puppetdb::params::postgres_version

postgresql_ssl_on

Data type: Any

If true, it configures SSL connections between PuppetDB and the PostgreSQL database. Defaults to false.

Default value: $puppetdb::params::postgresql_ssl_on

postgresql_ssl_cert_path

Data type: Any

Path to the Postgresql SSL certificate.

Default value: $puppetdb::params::postgresql_ssl_cert_path

postgresql_ssl_key_path

Data type: Any

Path to the Postgresql SSL key.

Default value: $puppetdb::params::postgresql_ssl_key_path

postgresql_ssl_ca_cert_path

Data type: Any

Path to the Postgresql SSL CA.

Default value: $puppetdb::params::postgresql_ssl_ca_cert_path

read_database_username

Data type: Any

The name of the read database user to connect as. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_username

read_database_password

Data type: Variant[String[1], Sensitive[String[1]]]

The password for the read database user. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_password

read_database_host

Data type: Any

This parameter must be set to use another PuppetDB instance for queries.

The hostname or IP address of the read database server. If set to undef, and manage_database is set to true, it will use the value of the database_host parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_host

password_sensitive

Data type: Boolean

Whether password should be of Datatype Sensitive[String]

Default value: false

password_encryption

Data type: Postgresql::Pg_password_encryption

PostgreSQL password authentication method, either md5 or scram-sha-256

Default value: $puppetdb::params::password_encryption

puppetdb::globals

global configuration class for PuppetDB

Parameters

The following parameters are available in the puppetdb::globals class:

version

Data type: Any

The version of the puppetdb package that should be installed. You may specify an explicit version number, 'present', or 'latest' (defaults to 'present').

Default value: 'present'

puppet_confdir

Data type: Stdlib::Absolutepath

Puppet's config directory. Defaults to /etc/puppetlabs/puppet.

Default value: $settings::confdir

puppetdb::master::config

manage the puppet configuration on the primary

Parameters

The following parameters are available in the puppetdb::master::config class:

puppetdb_server

Data type: Any

The dns name or ip of the PuppetDB server. Defaults to the hostname of the current node, i.e. $::fqdn.

Default value: fact('networking.fqdn')

puppetdb_port

Data type: Any

The port that the PuppetDB server is running on. Defaults to 8081.

Default value:

defined(Class['puppetdb']) ? {
    true    => $puppetdb::disable_ssl ? {
      true => 8080,
      default => 8081,
    },
    default => 8081
puppetdb_disable_ssl

Data type: Any

If true, use plain HTTP to talk to PuppetDB. Defaults to the value of disable_ssl if PuppetDB is on the same server as the Puppet Master, or else false. If you set this, you probably need to set puppetdb_port to match the HTTP port of the PuppetDB.

Default value:

defined(Class['puppetdb']) ? {
    true    => $puppetdb::disable_ssl,
    default => false
puppetdb_soft_write_failure

Data type: Any

Boolean to fail in a soft manner if PuppetDB is not accessible for command submission Defaults to false.

Default value: false

manage_routes

Data type: Any

If true, the module will overwrite the Puppet master's routes file to configure it to use PuppetDB. Defaults to true.

Default value: true

manage_storeconfigs

Data type: Any

If true, the module will manage the Puppet master's storeconfig settings. Defaults to true.

Default value: true

manage_report_processor

Data type: Any

If true, the module will manage the 'reports' field in the puppet.conf file to enable or disable the PuppetDB report processor. Defaults to false.

Default value: false

manage_config

Data type: Any

If true, the module will store values from puppetdb_server and puppetdb_port parameters in the PuppetDB configuration file. If false, an existing PuppetDB configuration file will be used to retrieve server and port values.

Default value: true

create_puppet_service_resource

Data type: Any

If true, AND if restart_puppet is true, then the module will create a service resource for puppet_service_name if it has not been defined. Defaults to true. If you are already declaring the puppet_service_name service resource in another part of your code, setting this to false will avoid creation of that service resource by this module, avoiding potential duplicate resource errors.

Default value: true

strict_validation

Data type: Any

If true, the module will fail if PuppetDB is not reachable, otherwise it will preconfigure PuppetDB without checking.

Default value: true

enable_reports

Data type: Any

Ignored unless manage_report_processor is true, in which case this setting will determine whether or not the PuppetDB report processor is enabled (true) or disabled (false) in the puppet.conf file.

Default value: false

enable_storeconfigs

Data type: Any

Ignored unless manage_storeconfigs is true, in which case this setting will determine whether or not client configuration storage is enabled (true) or disabled (false) in the puppet.conf file.

Default value: true

puppet_confdir

Data type: Any

Puppet's config directory. Defaults to /etc/puppetlabs/puppet.

Default value: $puppetdb::params::puppet_confdir

puppet_conf

Data type: Any

Puppet's config file. Defaults to ${puppet_confdir}/puppet.conf.

Default value: $puppetdb::params::puppet_conf

masterless

Data type: Any

A boolean switch to enable or disable the masterless setup of PuppetDB. Defaults to false.

Default value: $puppetdb::params::masterless

terminus_package

Data type: Any

Name of the package to use that represents the PuppetDB terminus code. Defaults to puppetdb-termini, when puppetdb_version is set to <= 2.3.x the default changes to puppetdb-terminus.

Default value: $puppetdb::params::terminus_package

puppet_service_name

Data type: Any

Name of the service that represents Puppet. You can change this to apache2 or httpd depending on your operating system, if you plan on having Puppet run using Apache/Passenger for example.

Default value: $puppetdb::params::puppet_service_name

puppetdb_startup_timeout

Data type: Any

The maximum amount of time that the module should wait for PuppetDB to start up. This is most important during the initial install of PuppetDB (defaults to 15 seconds).

Default value: $puppetdb::params::puppetdb_startup_timeout

test_url

Data type: Any

The URL to use for testing if the PuppetDB instance is running.

Default value: $puppetdb::params::test_url

restart_puppet

Data type: Any

If true, the module will restart the Puppet master when PuppetDB configuration files are changed by the module. Defaults to true. If set to false, you must restart the service manually in order to pick up changes to the config files (other than puppet.conf).

Default value: true

puppetdb::server

manage the PuppetDB server

Parameters

The following parameters are available in the puppetdb::server class:

listen_address

Data type: Any

The address that the web server should bind to for HTTP requests. Defaults to localhost. Set to 0.0.0.0 to listen on all addresses.

Default value: $puppetdb::params::listen_address

listen_port

Data type: Any

The port on which the puppetdb web server should accept HTTP requests. Defaults to 8080.

Default value: $puppetdb::params::listen_port

disable_cleartext

Data type: Any

If true, the puppetdb web server will only serve HTTPS and not HTTP requests (defaults to false).

Default value: $puppetdb::params::disable_cleartext

open_listen_port

Data type: Any

If true, open the http_listen_port on the firewall. Defaults to false.

Default value: $puppetdb::params::open_listen_port

ssl_listen_address

Data type: Any

The address that the web server should bind to for HTTPS requests. Defaults to 0.0.0.0 to listen on all addresses.

Default value: $puppetdb::params::ssl_listen_address

ssl_listen_port

Data type: Any

The port on which the puppetdb web server should accept HTTPS requests. Defaults to 8081.

Default value: $puppetdb::params::ssl_listen_port

disable_ssl

Data type: Any

If true, the puppetdb web server will only serve HTTP and not HTTPS requests. Defaults to false.

Default value: $puppetdb::params::disable_ssl

open_ssl_listen_port

Data type: Any

If true, open the ssl_listen_port on the firewall. Defaults to undef.

Default value: $puppetdb::params::open_ssl_listen_port

ssl_protocols

Data type: Any

Specify the supported SSL protocols for PuppetDB (e.g. TLSv1, TLSv1.1, TLSv1.2.)

Default value: $puppetdb::params::ssl_protocols

postgresql_ssl_on

Data type: Any

If true, it configures SSL connections between PuppetDB and the PostgreSQL database. Defaults to false.

Default value: $puppetdb::params::postgresql_ssl_on

cipher_suites

Data type: Any

Configure jetty's supported cipher-suites (e.g. SSL_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384). Defaults to undef.

Default value: $puppetdb::params::cipher_suites

migrate

Data type: Any

If true, puppetdb will automatically migrate to the latest database format at startup. If false, if the database format supplied by this version of PuppetDB doesn't match the version expected (whether newer or older), PuppetDB will exit with an error status. Defaults to true.

Default value: $puppetdb::params::migrate

manage_database

Data type: Any

If true, the PostgreSQL database will be managed by this module. Defaults to true.

Default value: $puppetdb::params::manage_database

database_host

Data type: Any

Hostname to use for the database connection. For single case installations this should be left as the default. Defaults to localhost.

Default value: $puppetdb::params::database_host

database_port

Data type: Any

The port that the database server listens on. Defaults to 5432.

Default value: $puppetdb::params::database_port

database_username

Data type: Any

The name of the database user to connect as. Defaults to puppetdb.

Default value: $puppetdb::params::database_username

database_password

Data type: Variant[String[1], Sensitive[String[1]]]

The password for the database user. Defaults to puppetdb.

Default value: $puppetdb::params::database_password

manage_db_password

Data type: Any

Whether or not the database password in database.ini will be managed by this module. Set this to false if you want to set the password some other way. Defaults to true

Default value: $puppetdb::params::manage_db_password

database_name

Data type: Any

The name of the database instance to connect to. Defaults to puppetdb.

Default value: $puppetdb::params::database_name

jdbc_ssl_properties

Data type: Any

The text to append to the JDBC connection URI. This should begin with a '?' character. For example, to use SSL for the PostgreSQL connection, set this parameter's value to ?ssl=true.

Default value: $puppetdb::params::jdbc_ssl_properties

database_validate

Data type: Any

If true, the module will attempt to connect to the database using the specified settings and fail if it is not able to do so. Defaults to true.

Default value: $puppetdb::params::database_validate

node_ttl

Data type: Any

The length of time a node can go without receiving any new data before it's automatically deactivated. (defaults to '7d', which is a 7-day period. Set to '0d' to disable auto-deactivation). This option is supported in PuppetDB >= 1.1.0.

Default value: $puppetdb::params::node_ttl

node_purge_ttl

Data type: Any

The length of time a node can be deactivated before it's deleted from the database. (defaults to '14d', which is a 14-day period. Set to '0d' to disable purging). This option is supported in PuppetDB >= 1.2.0.

Default value: $puppetdb::params::node_purge_ttl

report_ttl

Data type: Any

The length of time reports should be stored before being deleted. (defaults to 14d, which is a 14-day period). This option is supported in PuppetDB >= 1.1.0.

Default value: $puppetdb::params::report_ttl

facts_blacklist

Data type: Optional[Array]

A list of fact names to be ignored whenever submitted.

Default value: $puppetdb::params::facts_blacklist

gc_interval

Data type: Any

This controls how often (in minutes) to compact the database. The compaction process reclaims space and deletes unnecessary rows. If not supplied, the default is every 60 minutes. This option is supported in PuppetDB >= 0.9.

Default value: $puppetdb::params::gc_interval

node_purge_gc_batch_limit

Data type: Any

Nodes will be purged in batches of this size, one batch per gc-interval.

Default value: $puppetdb::params::node_purge_gc_batch_limit

conn_max_age

Data type: Any

The maximum time (in minutes) for a pooled connection to remain unused before it is closed off.

If not supplied, we default to 60 minutes. This option is supported in PuppetDB >= 1.1.

Default value: $puppetdb::params::conn_max_age

conn_lifetime

Data type: Any

The maximum time (in minutes) a pooled connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone. This option is supported in PuppetDB >= 1.4.

Default value: $puppetdb::params::conn_lifetime

puppetdb_package

Data type: Any

The PuppetDB package name in the package manager. Defaults to present.

Default value: $puppetdb::params::puppetdb_package

puppetdb_service

Data type: Any

The name of the PuppetDB service. Defaults to puppetdb.

Default value: $puppetdb::params::puppetdb_service

puppetdb_service_status

Data type: Any

Sets whether the service should be running or stopped. When set to stopped the service doesn't start on boot either. Valid values are true, running, false, and stopped.

Default value: $puppetdb::params::puppetdb_service_status

puppetdb_user

Data type: Any

Puppetdb service user

Default value: $puppetdb::params::puppetdb_user

puppetdb_group

Data type: Any

Puppetdb service group

Default value: $puppetdb::params::puppetdb_group

confdir

Data type: Any

The PuppetDB configuration directory. Defaults to /etc/puppetdb/conf.d.

Default value: $puppetdb::params::confdir

vardir

Data type: Any

The parent directory for the MQ's data directory.

Default value: $puppetdb::params::vardir

java_args

Data type: Any

Java VM options used for overriding default Java VM options specified in PuppetDB package. Defaults to {}. See PuppetDB Configuration to get more details about the current defaults.

For example, to set -Xmx512m -Xms256m options use:

{
    '-Xmx' => '512m',
    '-Xms' => '256m',
}

Default value: $puppetdb::params::java_args

merge_default_java_args

Data type: Any

Sets whether the provided java args should be merged with the defaults, or should override the defaults. This setting is necessary if any of the defaults are to be removed. Defaults to true. If false, the java_args in the PuppetDB init config file will reflect only what is passed via the java_args param.

Default value: $puppetdb::params::merge_default_java_args

max_threads

Data type: Any

Jetty option to explicitly set max-threads. Defaults to undef, so the PuppetDB-Jetty default is used.

Default value: $puppetdb::params::max_threads

read_database_host

Data type: Any

This parameter must be set to use another PuppetDB instance for queries.

The hostname or IP address of the read database server. If set to undef, and manage_database is set to true, it will use the value of the database_host parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_host

read_database_port

Data type: Any

The port that the read database server listens on. If read_database_host is set to undef, and manage_database is set to true, it will use the value of the database_port parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_port

read_database_username

Data type: Any

The name of the read database user to connect as. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_username

read_database_password

Data type: Variant[String[1], Sensitive[String[1]]]

The password for the read database user. Defaults to puppetdb-read. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_password

manage_read_db_password

Data type: Any

Whether or not the database password in read-database.ini will be managed by this module. Set this to false if you want to set the password some other way. Defaults to true

Default value: $puppetdb::params::manage_read_db_password

read_database_jdbc_ssl_properties

Data type: Any

The text to append to the JDBC connection URI. This should begin with a '?' character. For example, to use SSL for the PostgreSQL connection, set this parameter's value to ?ssl=true.

Default value: $puppetdb::params::read_database_jdbc_ssl_properties

read_database_validate

Data type: Any

If true, the module will attempt to connect to the database using the specified settings and fail if it is not able to do so. Defaults to true.

Default value: $puppetdb::params::read_database_validate

read_database_name

Data type: Any

The name of the read database instance to connect to. If read_database_host is set to undef, and manage_database is set to true, it will use the value of the database_name parameter. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_database_name

read_conn_max_age

Data type: Any

The maximum time (in minutes) for a pooled read database connection to remain unused before it is closed off.

If not supplied, we default to 60 minutes. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_conn_max_age

read_conn_lifetime

Data type: Any

The maximum time (in minutes) a pooled read database connection should remain open. Any connections older than this setting will be closed off. Connections currently in use will not be affected until they are returned to the pool.

If not supplied, we won't terminate connections based on their age alone. This option is supported in PuppetDB >= 1.6.

Default value: $puppetdb::params::read_conn_lifetime

ssl_dir

Data type: Stdlib::Absolutepath

Base directory for PuppetDB SSL configuration. Defaults to /etc/puppetdb/ssl or /etc/puppetlabs/puppetdb/ssl for FOSS and PE respectively.

Default value: $puppetdb::params::ssl_dir

ssl_set_cert_paths

Data type: Boolean

A switch to enable or disable the management of SSL certificates in your jetty.ini configuration file.

Default value: $puppetdb::params::ssl_set_cert_paths

ssl_cert_path

Data type: Stdlib::Absolutepath

Path to your SSL certificate for populating jetty.ini.

Default value: $puppetdb::params::ssl_cert_path

ssl_key_pk8_path

Data type: Stdlib::Absolutepath

Path to the SSL pk8 key for populating jetty.ini, will be generated from the SSL key as needed automatically.

Default value: $puppetdb::params::ssl_key_pk8_path

ssl_key_path

Data type: Stdlib::Absolutepath

Path to your SSL key for populating jetty.ini.

Default value: $puppetdb::params::ssl_key_path

ssl_ca_cert_path

Data type: Stdlib::Absolutepath

Path to your SSL CA for populating jetty.ini.

Default value: $puppetdb::params::ssl_ca_cert_path

ssl_deploy_certs

Data type: Boolean

A boolean switch to enable or disable the management of SSL keys in your ssl_dir. Default is false.

Default value: $puppetdb::params::ssl_deploy_certs

ssl_key

Data type: Any

Contents of your SSL key, as a string.

Default value: $puppetdb::params::ssl_key

ssl_cert

Data type: Any

Contents of your SSL certificate, as a string.

Default value: $puppetdb::params::ssl_cert

ssl_ca_cert

Data type: Any

Contents of your SSL CA certificate, as a string.

Default value: $puppetdb::params::ssl_ca_cert

manage_firewall

Data type: Any

If true, puppet will manage your iptables rules for PuppetDB via the puppetlabs-firewall class.

Default value: $puppetdb::params::manage_firewall

command_threads

Data type: Any

The number of command processing threads to use. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::command_threads

concurrent_writes

Data type: Any

The number of threads allowed to write to disk at any one time. Defaults to undef, which uses the PuppetDB built-in default.

Default value: $puppetdb::params::concurrent_writes

store_usage

Data type: Any

The amount of disk space (in MB) to allow for persistent message storage. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::store_usage

temp_usage

Data type: Any

The amount of disk space (in MB) to allow for temporary message storage. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::temp_usage

disable_update_checking

Data type: Any

Setting this to true disables checking for updated versions of PuppetDB and sending basic analytics data to Puppet. Defaults to undef, using the PuppetDB built-in default.

Default value: $puppetdb::params::disable_update_checking

certificate_whitelist_file

Data type: Any

The name of the certificate whitelist file to set up and configure in PuppetDB. Defaults to /etc/puppetdb/certificate-whitelist or /etc/puppetlabs/puppetdb/certificate-whitelist for FOSS and PE respectively.

Default value: $puppetdb::params::certificate_whitelist_file

certificate_whitelist

Data type: Any

Array of the X.509 certificate Common Names of clients allowed to connect to PuppetDB. Defaults to empty. Be aware that this permits full access to all Puppet clients to download anything contained in PuppetDB, including the full catalogs of all nodes, which possibly contain sensitive information. Set to [ $::servername ] to allow access only from your (single) Puppet master, which is enough for normal operation. Set to a list of Puppet masters if you have multiple.

Default value: $puppetdb::params::certificate_whitelist

database_max_pool_size

Data type: Any

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out. Note that PuppetDB will use one pool for writes and another for reads, so the total number of connections used will be twice this setting.

Default value: $puppetdb::params::database_max_pool_size

read_database_max_pool_size

Data type: Any

When the pool reaches this size, and no idle connections are available, attempts to get a connection will wait for connection-timeout milliseconds before timing out. Note that PuppetDB will use one pool for writes and another for reads, so the total number of connections used will be twice this setting.

Default value: $puppetdb::params::read_database_max_pool_size

automatic_dlo_cleanup

Data type: Boolean

PuppetDB creates Dead Letter Office. Those are reports of failed requests. They spill up the disk. This parameter is a boolean and defaults to false. You can enable automatic cleanup of DLO reports by setting this to true.

Default value: $puppetdb::params::automatic_dlo_cleanup

cleanup_timer_interval

Data type: String[1]

The DLO cleanup is a systemd timer if systemd is available, otherwise a cronjob. The variable configures the systemd.timer option onCalender. It defaults to *-*-* ${fqdn_rand(24)}:${fqdn_rand(60)}:00. This will start the cleanup service on a daily basis. The exact minute and hour is random per node based on the fqdn_rand method. On non-systemd systems, the cron runs daily and the $puppetdb_user needs to be able to run cron jobs. On systemd systems you need the camptocamp/systemd module, which is an optional dependency and not automatically installed!

Default value: $puppetdb::params::cleanup_timer_interval

dlo_max_age

Data type: Integer[1]

This is a positive integer. It describes the amount of days you want to keep the DLO reports. The default value is 90 days.

Default value: $puppetdb::params::dlo_max_age

java_bin

Data type: Optional[Stdlib::Absolutepath]

java binary path for PuppetDB. If undef, default will be used.

Default value: $puppetdb::params::java_bin

Resource types

puppetdb_conn_validator

Verify that a connection can be successfully established between a node and the puppetdb server. Its primary use is as a precondition to prevent configuration changes from being applied if the puppetdb server cannot be reached, but it could potentially be used for other purposes such as monitoring.

Properties

The following properties are available in the puppetdb_conn_validator type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the puppetdb_conn_validator type.

name

namevar

An arbitrary name used as the identity of the resource.

provider

The specific backend to use for this puppetdb_conn_validator resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

puppetdb_port

The port that the puppetdb server should be listening on.

puppetdb_server

The DNS name or IP address of the server where puppetdb should be running.

test_url

URL to use for testing if the PuppetDB database is up

timeout

The max number of seconds that the validator should wait before giving up and deciding that puppetdb is not running; defaults to 15 seconds.

Default value: 15

use_ssl

Whether the connection will be attempted using https

Default value: true

Functions

puppetdb::create_subsetting_resource_hash

Type: Ruby 4.x API

The puppetdb::create_subsetting_resource_hash function.

puppetdb::create_subsetting_resource_hash(Hash $java_args, Any $params)

The puppetdb::create_subsetting_resource_hash function.

Returns: Any

java_args

Data type: Hash

params

Data type: Any

puppetdb::flatten_java_args

Type: Ruby 4.x API

The puppetdb::flatten_java_args function.

puppetdb::flatten_java_args(Optional[Hash] $java_args)

The puppetdb::flatten_java_args function.

Returns: String

java_args

Data type: Optional[Hash]

Data types

Puppetdb::Ttl

The Puppetdb::Ttl data type.

Alias of Pattern[/^\d+(d|h|m|s|ms)$/]