{"id":15022727,"url":"https://github.com/puppetlabs/puppetlabs-puppetdb","last_synced_at":"2025-05-16T06:04:43.773Z","repository":{"id":3589646,"uuid":"4653174","full_name":"puppetlabs/puppetlabs-puppetdb","owner":"puppetlabs","description":"A puppet module for installing and managing puppetdb","archived":false,"fork":false,"pushed_at":"2025-02-04T02:06:00.000Z","size":1043,"stargazers_count":55,"open_issues_count":21,"forks_count":235,"subscribers_count":179,"default_branch":"main","last_synced_at":"2025-05-14T06:13:29.521Z","etag":null,"topics":["maintenance-mode","module"],"latest_commit_sha":null,"homepage":"https://forge.puppetlabs.com/puppetlabs/puppetdb","language":"Puppet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-13T16:17:23.000Z","updated_at":"2024-10-20T06:45:06.000Z","dependencies_parsed_at":"2024-02-26T01:49:50.489Z","dependency_job_id":"744c75b4-c669-4570-b90d-d6029dc98c97","html_url":"https://github.com/puppetlabs/puppetlabs-puppetdb","commit_stats":{"total_commits":417,"total_committers":101,"mean_commits":4.128712871287129,"dds":0.8776978417266187,"last_synced_commit":"c92b64967addf967250dc1e4f0268583d9198a0f"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-puppetdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-puppetdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-puppetdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs%2Fpuppetlabs-puppetdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs","download_url":"https://codeload.github.com/puppetlabs/puppetlabs-puppetdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478186,"owners_count":22077675,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["maintenance-mode","module"],"created_at":"2024-09-24T19:58:19.231Z","updated_at":"2025-05-16T06:04:43.751Z","avatar_url":"https://github.com/puppetlabs.png","language":"Puppet","funding_links":[],"categories":[],"sub_categories":[],"readme":"puppetdb\n=========\n\n#### Table of Contents\n\n1. [Overview - What is the PuppetDB module?](#overview)\n2. [Module Description - What does the module do?](#module-description)\n3. [Setup - The basics of getting started with PuppetDB module](#setup)\n4. [Upgrading - Guide for upgrading from older revisions of this module](#upgrading)\n4. [Usage - The classes and parameters available for configuration](#usage)\n5. [Implementation - An under-the-hood peek at what the module is doing](#implementation)\n6. [Limitations - OS compatibility, etc.](#limitations)\n7. [Development - Guide for contributing to the module](#development)\n8. [Release Notes - Notes on the most recent updates to the module](#release-notes)\n\nOverview\n--------\n\nBy guiding puppetdb setup and configuration with a Puppet master, the PuppetDB\nmodule provides fast, streamlined access to data on puppetized infrastructure.\n\nModule Description\n-------------------\n\nThe PuppetDB module provides a quick way to get started using PuppetDB, an open\nsource inventory resource service that manages storage and retrieval of\nplatform-generated data. The module will install PostgreSQL and PuppetDB if you\ndon't have them, as well as set up the connection to Puppet master. The module\nwill also provide a dashboard you can use to view the current state of your\nsystem.\n\nFor more information about PuppetDB\n[please see the official PuppetDB documentation.](https://puppet.com/docs/puppetdb/latest/)\n\n\nSetup\n-----\n\n**What PuppetDB affects:**\n\n* package/service/configuration files for PuppetDB\n* package/service/configuration files for PostgreSQL (optional, but set as default)\n* Puppet master's runtime (via plugins)\n* Puppet master's configuration\n  * **note**: Using the `puppetdb::master::config` class will cause your\n    routes.yaml file to be overwritten entirely (see **Usage** below for options\n    and more information )\n* system firewall (optional)\n* listened-to ports\n\n**Introductory Questions**\n\nTo begin using PuppetDB, you’ll have to make a few decisions:\n\n* Should I run the database on the same node that I run PuppetDB on?\n* Should I run PuppetDB on the same node that I run my master on?\n\nThe answers to those questions will be largely dependent on your answers to\nquestions about your Puppet environment:\n\n* How many nodes are you managing?\n* What kind of hardware are you running on?\n* Is your current load approaching the limits of your hardware?\n\nDepending on your answers to all of the questions above, you will likely fall\nunder one of these set-up options:\n\n1. [Single Node (Testing and Development)](#single-node-setup)\n2. [Multiple Node (Recommended)](#multiple-node-setup)\n\n### Single Node Setup\n\nThis approach assumes you will use our default database (PostgreSQL) and run\neverything (PostgreSQL, PuppetDB, Puppet master) all on the same node. This\nsetup will be great for a testing or experimental environment. In this case,\nyour manifest will look like:\n\n    node \u003chostname\u003e {\n      # Configure puppetdb and its underlying database\n      class { 'puppetdb': }\n      \n      # Configure the Puppet master to use puppetdb\n      class { 'puppetdb::master::config': }\n    }\n\nYou can provide some parameters for these classes if you’d like more control,\nbut that is literally all that it will take to get you up and running with the\ndefault configuration.\n\n### Multiple Node Setup\n\nThis approach is for those who prefer not to install PuppetDB on the same node\nas the Puppet master. Your environment will be easier to scale if you are able\nto dedicate hardware to the individual system components. You may even choose to\nrun the puppetdb server on a different node from the PostgreSQL database that it\nuses to store its data. So let’s have a look at what a manifest for that\nscenario might look like:\n\n**This is an example of a very basic 3-node setup for PuppetDB.**\n\n    $puppetdb_host = 'puppetdb.example.lan'\n    $postgres_host = 'postgres.example.lan'\n    node 'master.example.lan' {\n      # Here we configure the Puppet master to use PuppetDB,\n      # telling it the hostname of the PuppetDB node\n      class { 'puppetdb::master::config':\n        puppetdb_server =\u003e $puppetdb_host,\n      }\n    }\n    node 'postgres.example.lan' {\n      # Here we install and configure PostgreSQL and the PuppetDB\n      # database instance, and tell PostgreSQL that it should\n      # listen for connections to the `$postgres_host`\n      class { 'puppetdb::database::postgresql':\n        listen_addresses =\u003e $postgres_host,\n      }\n    }\n    node 'puppetdb.example.lan' {\n      # Here we install and configure PuppetDB, and tell it where to\n      # find the PostgreSQL database.\n      class { 'puppetdb::server':\n        database_host =\u003e $postgres_host,\n      }\n    }\n\nThis should be all it takes to get a 3-node, distributed installation of\nPuppetDB up and running. Note that, if you prefer, you could easily move two of\nthese classes to a single node and end up with a 2-node setup instead.\n\n### Enable SSL connections\n\nTo use SSL connections for the single node setup, use the following manifest:\n\n    node \u003chostname\u003e {\n      # Here we configure puppetdb and PostgreSQL to use ssl connections\n      class { 'puppetdb':\n        postgresql_ssl_on =\u003e true,\n        database_host =\u003e '\u003chostname\u003e',\n        database_listen_address =\u003e '0.0.0.0'\n      }\n      \n      # Configure the Puppet master to use puppetdb\n      class { 'puppetdb::master::config': }\n\nTo use SSL connections for the multiple nodes setup, use the following manifest:\n\n    $puppetdb_host = 'puppetdb.example.lan'\n    $postgres_host = 'postgres.example.lan'\n\n    node 'master.example.lan' {\n      # Here we configure the Puppet master to use PuppetDB,\n      # telling it the hostname of the PuppetDB node.\n      class { 'puppetdb::master::config':\n        puppetdb_server =\u003e $puppetdb_host,\n      }\n    }\n\n    node 'postgres.example.lan' {\n      # Here we install and configure PostgreSQL and the PuppetDB\n      # database instance, and tell PostgreSQL that it should\n      # listen for connections to the `$postgres_host`. \n      # We also enable SSL connections.\n      class { 'puppetdb::database::postgresql':\n        listen_addresses =\u003e $postgres_host,\n        postgresql_ssl_on =\u003e true,\n        puppetdb_server =\u003e $puppetdb_host\n      }\n    }\n\n    node 'puppetdb.example.lan' {\n      # Here we install and configure PuppetDB, and tell it where to\n      # find the PostgreSQL database. We also enable SSL connections.\n      class { 'puppetdb::server':\n        database_host =\u003e $postgres_host,\n        postgresql_ssl_on =\u003e true\n      }\n    }\n\n### Beginning with PuppetDB\n\nWhether you choose a single node development setup or a multi-node setup, a\nbasic setup of PuppetDB will cause: PostgreSQL to install on the node if it’s\nnot already there; PuppetDB postgres database instance and user account to be\ncreated; the postgres connection to be validated and, if successful, PuppetDB to\nbe installed and configured; PuppetDB connection to be validated and, if\nsuccessful, the Puppet master config files to be modified to use PuppetDB; and\nthe Puppet master to be restarted so that it will pick up the config changes.\n\nIf your logging level is set to INFO or finer, you should start seeing\nPuppetDB-related log messages appear in both your Puppet master log and your\npuppetdb log as subsequent agent runs occur.\n\n### Cross-node Dependencies\n\nIt is worth noting that there are some cross-node dependencies, which means that\nthe first time you add the module's configurations to your manifests, you may\nsee a few failed puppet runs on the affected nodes.\n\nPuppetDB handles cross-node dependencies by taking a sort of \"eventual\nconsistency\" approach. There’s nothing that the module can do to control the\norder in which your nodes check in, but the module can check to verify that the\nservices it depends on are up and running before it makes configuration\nchanges--so that’s what it does.\n\nWhen your Puppet master node checks in, it will validate the connectivity to the\npuppetdb server before it applies its changes to the Puppet master config files.\nIf it can’t connect to puppetdb, then the puppet run will fail and the previous\nconfig files will be left intact. This prevents your master from getting into a\nbroken state where all incoming puppet runs fail because the master is\nconfigured to use a puppetdb server that doesn’t exist yet. The same strategy is\nused to handle the dependency between the puppetdb server and the postgres\nserver.\n\nHence the failed puppet runs. These failures should be limited to 1 failed run\non the puppetdb node, and up to 2 failed runs on the Puppet master node. After\nthat, all of the dependencies should be satisfied and your puppet runs should\nstart to succeed again.\n\nYou can also manually trigger puppet runs on the nodes in the correct order\n(Postgres, PuppetDB, Puppet master), which will avoid any failed runs.\n\nUpgrading\n---------\n\n### Upgrading from 4.x to 5.x\n\nSignificant parameter changes are listed below:\n\n* The PuppetDB module defaults to Puppet 4 pathing and assumes `puppetserver`\n  is the master service by default\n* The PuppetDB module manages Postgres repos by default. To turn this behavior\n  off, set `manage_package_repo` to `false`.\n* To specify a specific version of PuppetDB to manage, you'll need to use the\n  `puppetdb::globals` class to set the version of PuppetDB you're using\n  explicitly. The ability to configure the version in the `puppetdb::server` and\n  `puppetdb` class have been removed.\n\nFor example if your config looked like this before:\n\n    class {'puppetdb':\n        puppetdb_version =\u003e '3.2.4-1.el7',\n    }\n    class { 'puppetdb::master::config': }\n\nand you'd still like to use the module with PuppetDB 3.2.4, all you'd have to\nchange would be:\n\n    class { 'puppetdb::globals':\n        version =\u003e '3.2.4-1.el7',\n    }\n    class { 'puppetdb' : }\n    class { 'puppetdb::master::config' : }\n\nThe `globals` class above takes into account the following PuppetDB 3 and Puppet\n4 related changes:\n    * The `puppetdb::master:puppetdb_conf` class has added a `$legacy_terminus`\n      to support the PuppetDB 2.x terminus configuration.\n    * The default `test_url` for the `PuppetDBConnValidator` has also been\n      changed to `/pdb/meta/v1/version` but will default to `/v3/version` when\n      using a PuppetDB 2.x version.\n    * The configuration pathing for Puppet and PuppetDB has changed with Puppet\n      4 and PuppetDB 3, using PuppetDB 2.x or older assumes the old\n      configuration pathing.\n\nSee the CHANGELOG file for more detailed information on changes for each release.\n\n### Upgrading from 3.x to 4.x\n\nFor this release, all dependency versions have been bumped to their latest.\nSignificant parameter changes are listed below:\n\n* The PuppetDB module now only supports Puppet 3.7.1 or later\n* `puppetlabs/postgresql` 4.0.0 or later is now required\n* `puppetlabs/inifile` 1.1.3 or later is now required\n* `puppetlabs/firewall` 1.1.3 or later is now required\n* `puppetlabs/stdlib` 4.2.2 or later is now required\n* The parameter `manage_firewall` for the class `puppetdb::database::postgresql`\n  has now been removed, since the PostgreSQL module no longer supports this.\n* The parameter `open_postgres_port` for the class `puppetdb` has also been\n  removed, due to PostgreSQL changes.\n\nSee the CHANGELOG file for more detailed information on changes for each release.\n\n### Upgrading from 2.x to 3.x\n\nFor this release a major dependency has changed. The module\n`pupppetlabs/postgresql` must now be version 3.x. Upgrading the module should\nupgrade the `puppetlabs/postgresql` module for you, but if another module has a\nfixed dependency that module will have to be fixed before you can continue.\n\nSome other changes include:\n\n* The parameter `manage_redhat_firewall` for the class `puppetdb` has now been\n  removed completely in favor of `open_postgres_port` and\n  `open_ssl_listen_port`.\n* The parameter `manage_redhat_firewall` for the class\n  `puppetdb::database::postgresql`, has now been renamed to `manage_firewall`.\n* The parameter `manage_redhat_firewall` for the class `puppetdb::server` has\n  now been removed completely in favor of `open_listen_port` and\n  `open_ssl_listen_port`.\n* The internal class: `puppetdb::database::postgresql_db` has been removed. If\n  you were using this, it is now defunct.\n* The class `puppetdb::server::firewall` has been marked as private, do not use\n  it directly.\n* The class `puppetdb::server::jetty_ini` and `puppetdb::server::database_ini`\n  have been marked as private, do not use it directly.\n\n### Upgrading from 1.x to 2.x\n\nA major dependency has been changed, so now when you upgrade to 2.0 the\ndependency `cprice404/inifile` has been replaced with `puppetlabs/inifile`. This\nmay interfere with other modules as they may depend on the old\n`cprice404/inifile` instead, so upgrading should be done with caution. Check\nthat your other modules use the newer `puppetlabs/inifile` module as\ninteroperation with the old `cprice404/inifile` module will no longer be\nsupported by this module.\n\nDepending on how you install your modules, changing the dependency may require\nmanual intervention. Double check your modules contain the newer\n`puppetlabs/inifile` after installing this latest module.\n\nOtherwise, all existing parameters from 1.x should still work correctly.\n\nUsage\n------\n\nPuppetDB supports a large number of configuration options for both configuring\nthe puppetdb service and connecting that service to the Puppet master.\n\n### puppetdb::globals\n\nThe `puppetdb::globals` class is intended to provide similar functionality to\nthe `postgresql::globals` class in the `puppetlabs-postgresql` module by\nexposing a top-level entry-point into the module so that we can properly set\ndefaults for the `puppetdb::params` class based on the version of `puppetdb` you\nare using. This setting defaults to `present`.\n\nYou must declare the class to use it:\n\n    class { 'puppetdb::globals': }\n\n### puppetdb\n\nThe `puppetdb` class is intended as a high-level abstraction (sort of an\n'all-in-one' class) to help simplify the process of getting your puppetdb server\nup and running. It wraps the slightly-lower-level classes `puppetdb::server` and\n`puppetdb::database::*`, and it'll get you up and running with everything you\nneed (including database setup and management) on the server side. For maximum\nconfigurability, you may choose not to use this class. You may prefer to use the\n`puppetdb::server` class directly, or manage your puppetdb setup on your own.\n\nYou must declare the class to use it:\n\n    class { 'puppetdb': }\n\n### puppetdb::server\n\nThe `puppetdb::server` class manages the PuppetDB server independently of the\nunderlying database that it depends on. It will manage the PuppetDB package,\nservice, config files, etc., but will still allow you to manage the database\n(e.g. PostgreSQL) however you see fit.\n\n    class { 'puppetdb::server':\n      database_host =\u003e 'pg1.mydomain.com',\n    }\n\n### puppetdb::master::config\n\nThe `puppetdb::master::config` class directs your Puppet master to use PuppetDB,\nwhich means that this class should be used on your Puppet master node. It’ll\nverify that it can successfully communicate with your PuppetDB server, and then\nconfigure your master to use PuppetDB.\n\nUsing this class allows the module to manipulate the puppet configuration files\npuppet.conf and routes.yaml. The puppet.conf changes are supplemental and should\nnot affect any of your existing settings, but the routes.yaml file will be\noverwritten entirely. If you have an existing routes.yaml file, you will want to\ntake care to use the `manage_routes` parameter of this class to prevent the module\nfrom managing that file, and you’ll need to manage it yourself.\n\n    class { 'puppetdb::master::config':\n      puppetdb_server =\u003e 'my.host.name',\n      puppetdb_port   =\u003e 8081,\n    }\n\n### puppetdb::database::postgresql\n\nThe `puppetdb::database::postgresql` class manages a PostgreSQL server for use\nby PuppetDB. It can manage the PostgreSQL packages and service, as well as\ncreating and managing the PuppetDB database and database user accounts.\n\n    class { 'puppetdb::database::postgresql':\n      listen_addresses =\u003e 'my.postgres.host.name',\n    }\n\nImplementation\n---------------\n\n### Resource overview\n\nIn addition to the classes and variables mentioned above, PuppetDB includes:\n\n**puppetdb::master::routes**\n\nConfigures the Puppet master to use PuppetDB as the facts terminus. *WARNING*:\nthe current implementation simply overwrites your routes.yaml file; if you have\nan existing routes.yaml file that you are using for other purposes, you should\n*not* use this.\n\n    class { 'puppetdb::master::routes':\n      puppet_confdir =\u003e '/etc/puppet'\n    }\n\nThe optional parameter routes can be used to specify a custom route\nconfiguration. For example to configure routes for masterless puppet.\n\n    class { 'puppetdb::master::routes':\n      routes =\u003e {\n        'apply' =\u003e {\n          'facts' =\u003e {\n            'terminus' =\u003e 'facter',\n            'cache'    =\u003e 'puppetdb_apply',\n          }\n        }\n      }\n    }\n\n**puppetdb::master::storeconfigs**\n\nConfigures the Puppet master to enable storeconfigs and to use PuppetDB as the\nstoreconfigs backend.\n\n    class { 'puppetdb::master::storeconfigs':\n      puppet_conf =\u003e '/etc/puppet/puppet.conf'\n    }\n\n**puppetdb::server::validate_db**\n\nValidates that a successful database connection can be established between the\nnode on which this resource is run and the specified PuppetDB database instance\n(host/port/user/password/database name).\n\n    puppetdb::server::validate_db { 'validate my puppetdb database connection':\n      database_host     =\u003e 'my.postgres.host',\n      database_username =\u003e 'mydbuser',\n      database_password =\u003e 'mydbpassword',\n      database_name     =\u003e 'mydbname',\n    }\n\n### Custom Types\n\n**puppetdb_conn_validator**\n\nVerifies that a connection can be successfully established between a node and\nthe PuppetDB server. Its primary use is as a precondition to prevent\nconfiguration changes from being applied if the PuppetDB server cannot be\nreached, but it could potentially be used for other purposes such as monitoring.\n\nLimitations\n------------\n\nCurrently, PuppetDB is compatible with:\n\n    Puppet Version: 4.10+\n\nPlatforms:\n* EL 5, 6, 7\n* Debian 6, 7\n* Ubuntu 10.04, 12.04, 14.04\n\nCommunity Maintained Platforms:\n* Archlinux\n* OpenBSD 5.6-current and newer\n* SLES 11 SP1\n\nDevelopment\n------------\n\nPuppet Labs modules on the Puppet Forge are open projects, and community\ncontributions are essential for keeping them great. We can’t access the huge\nnumber of platforms and myriad of hardware, software, and deployment\nconfigurations that Puppet is intended to serve.\n\nWe want to keep it as easy as possible to contribute changes so that our modules\nwork in your environment. There are a few guidelines that we need contributors\nto follow so that we can have a chance of keeping on top of things.\n\nYou can read the complete [contribution guide](https://github.com/puppetlabs/.github/blob/master/CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-puppetdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-puppetdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs%2Fpuppetlabs-puppetdb/lists"}