The Dashboard is a Ruby on Rails application and is quite new, so it hasn’t yet been added to many distributions as a package, but it is available from Puppet Labs as an RPM or a DEB package. We culd also install from source.
As prerequisites, the Dashboard needs Puppet to be installed and running using stored configurations (click here to see how to set up stored Puppet configurations). The Dashboard will work on most recent versions of Puppet from release 0.24.8 and later. It also requires Ruby, the Rake tool and a MySQL database (more database support will be available in later releases).
Adding Yum or Apt repositories
First, we need to add either the Puppet Labs Yum or Apt repositories. For Yum, we need to create a Yum repo entry for Puppet Labs:
$ vi /etc/yum.repos.d/puppetlabs.repo
Add the following to the entry:
$ sudo yum install puppet-dashboard
You will be prompted to install the Puppet Labs release key as part of the installation process.
For Apt, we need to add entries to the /etc/apt/sources.list file:
$ gpg --recv-key 4BD6EC30
$ gpg -a --export 4BD6EC30 | sudo apt-key add -
Next, we run an update:
$ sudo apt-get update
And then install the package:
$ sudo apt-get install puppet-dashboard
On both Red Hat and Ubuntu hosts, the Puppet Dashboard will be installed into the /usr/share/puppet-dashboard directory.
Configuring the Rails application
Next, we need to configure the Rails application, starting with a database. Currently the Dashboard only supports MySQL databases, so create one:
$ mysql --u root p
mysql> CREATE DATABASE dashboard CHARACTER SET utf8;
mysql> CREATE USER 'dashboard'@'localhost' IDENTIFIED BY 'password';
mysql> GRANT ALL PRIVILEGES ON dashboard.* TO 'dashboard'@'localhost';
Here we’ve created a database called dashboard, added a user called dashboard and granted that user appropriate privileges to the database. You should replace “password” with an appropriate password.
Next, we need to tell Dashboard about the database. To do this, we configure a database.yml file in the /usr/share/puppet-dashboard/config directory.
The package contains an example file called database.yml.example that we can copy and edit:
$ cp database.yml.example database.yml
$ vi database.yml
Update the production stanza in the file like so (replacing password with the password you chose above):
This stanza needs to be valid YAML, so ensure you keep the existing indentation.
Lastly, we need to populate our new database with tables and base data. To do this we use a Rake task. From the /usr/share/puppet-dashboard directory, run:
$ rake RAILS_ENV=production db:migrate
Now Dashboard is fully configured and we can run the Rails application. There are a lot of ways to run Rails applications. One way is to use the internal Webrick server (this isn’t really great for production, as it doesn’t scale very well).
From the /usr/share/puppet-dashboard directory, run:
$ sudo ./script/server -e production
This will run the Dashboard on port 3000 and you can access it via a Web browser:
You can also configure Apache or Nginx with Passenger to run the Dashboard, which is a more stable and scalable production option. Here, you can find a sample Apache Passenger configuration file.
Getting Puppet reports to the Puppet Dashboard
Now the Dashboard is running and we need to ensure it gets our Puppet reports. There are a few ways we can do this, starting with importing old reports using a Rake task. From the /usr/share/puppet-dashboard directory, run:
$ rake RAILS_ENV=production reports:import
This assumes your Puppet master is on the local host and will import any report files located in the Puppet vardir (usually /var/lib/puppet/reports, but you can specify an alternative with the REPORT_DIR option). You can run this multiple times or schedule it with a cron job -- it recognizes reports it has previously imported and will only add new reports.
You can also configure Puppet to automatically report to the Dashboard using two methods, the first for Puppet versions 0.25.x and earlier, and the second for Puppet versions 2.6.x and later. For Puppet 0.25.x and earlier, ensure you have reports enabled on your clients by adding report = true to the [puppetd] stanza of your puppet.conf configuration file on every client you wish to have reporting. Then on the Puppet master, add /usr/share/puppet-dashboard/lib/puppet to Puppet’s libdir in the puppet.conf file like so:
libdir = /usr/share//puppet-dashboard/lib/puppet:/var/puppet/lib
And enable the Puppet Dashboard report:
reports = puppet_dashboard, any-other-reports
This report assumes your Puppet Dashboard is running on the local host at port 3000. You can adjust this location by editing the file /usr/share/puppet-dashboard/lib/puppet/puppet_dashboard.rb file and updating the HOST and PORT options at the top of the file.
On Puppet 2.6.x and later, you need to enable reports on your clients:
report = true
And then specify the http report type and use the new reporturl option to specify the target host and URL like so:
Update the host and port to match your environment (you should leave the reports suffix on the URL).
Now the Puppet Dashboard should be receiving your Puppet reports and you’re done! When you navigate to the page, you should see the Puppet Dashboard’s home screen.
Click here for a larger image
From this screen you can see all your current Puppet nodes that have been reported in and the successes or failures of their Puppet runs (and you can drill down into the results to see which resources failed and the errors that were generated). It provides a powerful central interface to your Puppet environment and provides status at a glance for your environment.
It’s also a relatively new product too, so new features (and potentially bugs!) are being added every day. If you have problems, issues and especially ideas and feedback, log tickets at Puppet Labs and get help from the #puppet IRC channel on Freenode or via the Puppet mailing list. Enjoy, and let us know about your experiences!
This was first published in August 2010