[opensourcedex]

puppetboard is a free, open source business intelligence & reporting project written in Python and released under Apache-2.0. It has 736 GitHub stars, 240 forks and 77 open issues, and was last pushed 12 hours ago. On this registry it ranks #31 of 34 tracked projects in Business Intelligence & Reporting, with 5 head-to-head comparisons available.

What is puppetboard?

What it is

Puppetboard is a web frontend for PuppetDB, the database component of the Puppet ecosystem. It is a Python project licensed under Apache-2.0, and it is intended to provide dashboard and reporting access to PuppetDB data for open-source Puppet users.

The problem it addresses is that PuppetDB is not itself a human-facing reporting console. Puppetboard gives operators a web interface for viewing PuppetDB information, and it can be deployed next to an existing PuppetDB installation as a package, a Puppet-managed service, or a container.

Key capabilities

  • Puppetboard presents PuppetDB through a web interface and is intended to replace Puppet Enterprise console reporting in open-source Puppet environments.
  • It supports PuppetDB versions 5.2 through 8.x, excluding 8.1.0 because of an upstream bug, with 8.1.1 and later noted as supported.
  • It can be installed from PyPI, managed with a Puppet module, or run from official Docker images in GitHub Container Registry and Docker Hub.
  • It connects to PuppetDB through environment variables such as PUPPETDB_HOST and PUPPETDB_PORT, and it requires a SECRET_KEY value.
  • It can run under a URL prefix by setting PUPPETBOARD_URL_PREFIX, which supports deployment behind an existing web path.
  • It can enable catalog features by using SSL to PuppetDB with ENABLE_CATALOG, PUPPETDB_KEY, PUPPETDB_CERT, and PUPPETDB_SSL_VERIFY.
  • It supports air-gapped operation through OFFLINE_MODE, allowing the service to load content from the local deployment.

Who uses it and how

  • Puppet operators run Puppetboard on the PuppetDB host, using host networking and localhost connection settings.
  • Infrastructure teams manage it with the Puppet module or with Puppet types such as docker::image and docker::run.
  • Users who need full features mount certificate and key files and configure Puppetboard to talk to PuppetDB over SSL.
  • Administrators expose the dashboard under a prefix such as /puppetboard when it must share a web path.
  • Operators in isolated environments set OFFLINE_MODE so the service does not depend on external content sources.

Getting started

The usual methods are installing puppetboard from PyPI for Python 3.9 through 3.13, applying the Puppet module, or running the ghcr.io/voxpupuli/puppetboard or voxpupuli/puppetboard Docker image. A basic Docker run sets PUPPETDB_HOST, PUPPETDB_PORT, and SECRET_KEY, often with host networking on the PuppetDB host.

When to use it — and when not to

Puppetboard fits open-source Puppet deployments that already run PuppetDB and want a self-hosted reporting dashboard instead of Puppet Enterprise console reporting. Self-hosting requires operating the Python or Docker runtime, providing a secret key, and managing SSL certificate material when full features are needed. It is less suitable for PuppetDB 8.1.0, which is explicitly unsupported, or for environments that cannot supply the required PuppetDB connection and certificate configuration.

project readme (upstream, from github) — read inline

Puppetboard

PyPI Version PyPI Downloads Tests Status codecov By Voxpupuli

Puppetboard is a web interface to PuppetDB aiming to replace the reporting functionality of Puppet Enterprise console (previously: Puppet Dashboard) for the open source Puppet.

Overview

See more screenshots here.

Table of Contents

Requirements

  • PuppetDB v. 5.2-8.*
    • (Note: PuppetDB 8.1.0 is not supported because of this bug. Please update to 8.1.1+.)
  • Python 3.9-3.13 or Docker

Installation

Puppetboard is packaged and available on PyPI.

With Puppet module

There is a Puppet module originally written by Spencer Krum and currently maintained by Voxpupuli that takes care of installing the Puppetboard for you.

To see how to get it working with RedHat/Centos 7 check out these docs.

Using Docker

We provide an official Docker image in:

You can run the app on your PuppetDB host with this command:

docker run -it \
  -e PUPPETDB_HOST=localhost \
  -e PUPPETDB_PORT=8080 \
  -e SECRET_KEY=XXXXXXXX \
  --net=host \
  ghcr.io/voxpupuli/puppetboard

Note: you must provide a secret key! Generate one for example by running ruby -e "require 'securerandom'; puts SecureRandom.hex(32)".

Optionally you can set PUPPETBOARD_URL_PREFIX env variable to a value like /puppetboard to run the app under a URL prefix.

You can use the following Puppet Code to have Puppetboard managed by Puppet:

include docker

docker::image { 'ghcr.io/voxpupuli/puppetboard': }

docker::run { 'puppetboard':
  image => 'ghcr.io/voxpupuli/puppetboard',
  env   => [
    'PUPPETDB_HOST=127.0.0.1',
    'PUPPETDB_PORT=8080',
    'PUPPETBOARD_PORT=8088',
    'SECRET_KEY=XXXXXXXX',
  ],
  net   => 'host',
}

If you want to have all features enabled, you must use SSL talking to PuppetDB:

file { '/etc/puppetboard':
  ensure => directory,
}
file { '/etc/puppetboard/key.pem':
  ensure => file,
  mode   => '0644',
  source => "/etc/puppetlabs/puppet/ssl/private_keys/${facts['networking']['fqdn']}.pem",
}
file { '/etc/puppetboard/cert.pem':
  ensure => file,
  mode   => '0644',
  source => "/etc/puppetlabs/puppet/ssl/certs/${facts['networking']['fqdn']}.pem",
}

include docker

docker::image { 'ghcr.io/voxpupuli/puppetboard': }

docker::run { 'puppetboard':
  image   => 'ghcr.io/voxpupuli/puppetboard',
  volumes => ['/etc/puppetboard:/etc/puppetboard:ro'],
  env     => [
    'PUPPETDB_HOST=puppet', # this must be the certname or DNS_ALT_NAME of the PuppetDB host
    'PUPPETDB_PORT=8081',
    'PUPPETBOARD_PORT=8080',
    'ENABLE_CATALOG=true',
    'PUPPETDB_SSL_VERIFY=false',
    'PUPPETDB_KEY=/etc/puppetboard/key.pem',
    'PUPPETDB_CERT=/etc/puppetboard/cert.pem',
    'SECRET_KEY=XXXXXXXX',
    'DEFAULT_ENVIRONMENT=*',
  ],
  net     => 'host',
}

Within an air gapped environment you want to load all content from your local puppetboard web service. Add: 'OFFLINE_MODE=true', to the env parameter list of the docker::run Puppet type.

We also provide the Dockerfile, so you can build the image yourself:

docker build -t puppetboard .

Using Red Hat OpenShift

The included OpenShift template file helps in the creation of the Puppetboard web interface by adopting a source-to-image methodology.

You can run the app on your OpenShift environment with these commands:

# Import the template into OpenShift
oc create -f puppetboard-s2i-template.yaml 

# Create the Puppetboard application and supporting Pods.
oc new-app -p PUPPETDB_HOST=puppetdb.fqdn.com \
           --template=puppetboard-template

This will build a puppetboard application that queries a PuppetDB database at puppetdb.fqdn.com.

Optionally you can set other environment variables to fit your needs:

oc new-app -p PUPPETDB_HOST=puppetdb.fqdn.com \
           -p PUPPETDB_PORT=3456 \
           -p PUPPETBOARD_SOURCE_REPOSITORY_REF="v5.4.0" \
           -p PUPPETBOARD_SERVICE_NAME=prod_puppetboard \
           --template=puppetboard-template

This will build Puppetboard version v5.4.0 that queries the PuppetDB server on TCP/3456.

The following is a list of OpenShift parameters that you can pass to the oc command to customize the application:

  • PUPPETBOARD_SERVICE_NAME: This is the name that will be used for application. Deployment Configs, Build Configs Services, Routes and Pods will use this value for their names as well. You can instantiate multiple applications by using different names in oc new-app. Defaults to 'puppetboard'.
  • PUPPETDB_HOST: This is the name of the PuppetDB host that Puppetboard will query for its reports. Defaults to 'puppetdb'.
  • PUPPETDB_PORT: This is tcp port on the PUPPETDB_HOST for queries. Defaults to '8080'.
  • PUPPETBOARD_SECRET_KEY: Identical to SECRET_KEY (below). Defaults to 'Secr3t_K3y'.
  • PUPPETBOARD_PORT: The TCP port on which the Puppetboard docker image presents the web interface. This is not the user-facing web interface. Rather, it's the port that the OpenShift route forwards to.
  • SERVICE_PORT: The TCP port on which the Puppetboard service offers its user-facing web interface on OpenShift. Defaults to '80'.
  • PUPPETBOARD_SOURCE_REPOSITORY_URL: The URL to the Puppetboard repository. Defaults to 'https://github.com/voxpupuli/puppetboard.git'.
  • PUPPETBOARD_SOURCE_REPOSITORY_REF: The branch/tag/ref for Puppetboard. Defaults to 'master'.

From a package

Actively maintained packages:

Manually

You can also install the package from PyPI and configure a WSGI-capable application server to serve it.

We recommend using virtualenv to provide a separate environment for the app.

virtualenv -p python3 venv
. venv/bin/activate
pip install puppetboard

Please see an article about more deployment setups here.

Configuration

Puppet agents

The default value of usecacheonfailure = true configuration setting for Puppet agents causes Puppet runs to always succeed, event if there are catalog compilation failures f.e. because of a syntax error in your code. This is because in such cases with this setting Puppet will just use a cached working catalog and report the run to PuppetDB as successful. (Although with an error visible in the Puppet run log.)

Therefore, to show the nodes with a catalog compilation as failed in Puppetboard you need to set usecacheonfailure = false in your nodes' puppet.conf.

PuppetDB

Of course you need to configure your Puppet Server to store the Puppet run reports in PuppetDB. If you haven't done that already please follow the PuppetDB documentation about this.

If you run Puppetboard on a different host than PuppetDB then you may want to configure the certificate allow-list for which certificates are allowed to access data from PuppetDB. Please read more about this feature in the PuppetDB documentation here.

App settings

Puppetboard will look for a file pointed at by the PUPPETBOARD_SETTINGS environment variable. The file has to be identical to [default_settings.py](https://github.com/voxpupuli/puppetboard/blob/master/puppetboard/default_s

readme truncated — read the full docs on github

Frequently asked questions

Is puppetboard free to use?

puppetboard is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does puppetboard do?

Web frontend for PuppetDB

What is puppetboard written in?

puppetboard is primarily written in Python. Its source is publicly available at https://github.com/voxpupuli/puppetboard, and it has 736 GitHub stars.