DOCSEARCHbyAlgolia
Submit Docs

Puppetboard

repository·master·Indexed 20 days ago

https://github.com/voxpupuli/puppetboard

A web-based reporting interface for PuppetDB that provides an open-source alternative to the Puppet Enterprise console for visualizing Puppet data. Version 7.0.2 supports Python 3.9-3.13 and PuppetDB 5.2-8.* (excluding 8.1.0). It can be deployed via Docker, OpenShift S2I templates, or manual installation from PyPI.

Tokens
15.2K
Snippets
53
Records
66
Agent score
72%

What's inside puppetboard

  2. Run Puppetboard locally for development

    master

    To run Puppetboard in a development environment, you must first set up a virtual environment and install the dependencies. You can then use the flask run command to start the application.

    Puppetboard uses the PUPPETBOARD_SETTINGS environment variable to locate your configuration file. If this variable is not set, the application looks for a settings.py file in the base directory of the git repository.

    # 1. Setup virtualenv
python -m venv venv
. venv/bin/activate

# 2. Install dependencies
pip install --upgrade wheel setuptools
pip install -e .
pip install --upgrade -r requirements-test.txt

# 3. Run the app
export PUPPETBOARD_SETTINGS=$PWD/settings.py
flask run

  3. Run tests for Puppetboard

    master

    To ensure code quality, you can run the test suite using pytest with coverage and mypy for type checking, or use pylint to check for errors.

    # Run tests with coverage and mypy
pytest --cov=. --cov-report=xml --strict-markers --mypy puppetboard test

# Run linting for errors
pylint --errors-only puppetboard test

  4. Enable the Query Presets feature

    master

    To enable the Query Presets feature, you must specify the path to a YAML configuration file in your Puppetboard settings (e.g., local_settings.py or docker_settings.py).

    Set the QUERY_PRESETS_FILE variable to the absolute path of your YAML file. To disable the feature, set it to None.

    # Enable presets
QUERY_PRESETS_FILE = '/etc/puppetboard/query_presets.yaml'

# Disable presets
QUERY_PRESETS_FILE = None

  5. Deploy Puppetboard with Apache and mod_passenger

    master

    To run Puppetboard through Passenger (experimental/core feature in Passenger 4):

    1. Create directories: Create /var/www/puppetboard/ with tmp and public subdirectories.
    2. Configure settings: Copy default_settings.py to /var/www/puppetboard/settings.py and customize it.
    3. Create passenger_wsgi.py: Create this file in your application directory. You must configure logging inside this file because Passenger's startup issues won't be logged otherwise. Set the PUPPETBOARD_SETTINGS environment variable here.
    4. Configure Apache: Set the DocumentRoot to your public directory and use RackAutoDetect On with an Alias for the /static directory.
    from __future__ import absolute_import
import os
import logging

logging.basicConfig(filename='/path/to/file/for/logging', level=logging.INFO)

# Needed if a settings.py file exists
os.environ['PUPPETBOARD_SETTINGS'] = '/var/www/puppetboard/settings.py'

try:
    from puppetboard.app import app as application
except Exception, inst:
    logging.exception("Error: %s", str(type(inst)))

  6. Configure PuppetDB connection and SSL

    master

    Puppetboard requires a Puppet Server configured to store reports in PuppetDB. If Puppetboard and PuppetDB are on different hosts, you must configure the PuppetDB certificate allow-list.

    When connecting to a remote PuppetDB, you typically need to provide SSL settings. If using the Puppetboard Docker image, you can pass certificate contents via environment variables as either a multiline string or a pre-base64 encoded string.

    # Example: Providing certificate as a multiline string
PUPPETDB_CERT="-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----"

# Example: Providing certificate as a base64 encoded string
PUPPETDB_CERT=LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQouLi4KLS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==

  7. Configure Puppet agents to show compilation failures

    master

    By default, Puppet agents use usecacheonfailure = true, which causes Puppet to use a cached catalog and report a successful run even if there is a compilation error (e.g., a syntax error). This prevents Puppetboard from identifying nodes with failed catalog compilations.

    To ensure Puppetboard correctly shows nodes with failed catalog compilations, set usecacheonfailure = false in your nodes' puppet.conf.

  8. Install Puppetboard using Docker

    master

    You can run Puppetboard using official Docker images from the GitHub Container Registry or Dockerhub.

    To run the application on your PuppetDB host, use the following command. You must provide a SECRET_KEY. You can generate a secure key using: ruby -e "require 'securerandom'; puts SecureRandom.hex(32)".

    Optionally, set the PUPPETBOARD_URL_PREFIX environment variable (e.g., /puppetboard) to run the application under a specific URL path.

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

  9. Puppetboard Requirements

    master

    Before installing Puppetboard, ensure your environment meets the following requirements:

    • PuppetDB: version 5.2-8.*.
      • Note: PuppetDB 8.1.0 is not supported due to a known bug. Please use 8.1.1 or later.
    • Runtime: Python 3.9-3.13 or Docker.

  10. Install Puppetboard on Debian Jessie

    master

    To install Puppetboard on Debian Jessie, install the necessary system dependencies, clone the repository to /opt/voxpupuli-puppetboard/, and use pip to install the package.

    1. Install python-pip and git via apt-get.
    2. Create the installation directory /opt/voxpupuli-puppetboard/.
    3. Clone the Puppetboard repository into that directory.
    4. Install the puppetboard package using pip from within the cloned directory.
    $ apt-get install python-pip git

$ mkdir /opt/voxpupuli-puppetboard/
$ cd /opt/voxpupuli-puppetboard/
$ git clone https://github.com/voxpupuli/puppetboard
$ cd /opt/voxpupuli-puppetboard/puppetboard
$ pip install puppetboard

  11. Install Puppetboard manually via PyPI

    master

    For manual installations, you can install Puppetboard from PyPI and serve it using a WSGI-capable application server. It is recommended to use virtualenv to isolate the environment.

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

  12. Configure Puppetboard host and port

    master

    You can specify the listening host and port for the Flask development server using either environment variables or command line options when executing flask run.

    # Using environment variables
export FLASK_RUN_HOST=0.0.0.0
export FLASK_RUN_PORT=8000
flask run

# Using command line options
flask run --host '0.0.0.0' --port '8000'