puppet-graphite

Wirbelsturm-compatible Puppet module to deploy Graphite.

Note: This module is a work in progress. The code still needs some cleaning and better style.

Table of Contents

Installation
Usage and configuration
Requirements
Assumptions
FAQ
Credits

Installation

It is recommended to use librarian-puppet to add this module to your Puppet setup.

Add the following lines to your Puppetfile:

# Add the dependencies as hosted on public Puppet Forge.
#
# We intentionally do not include e.g. the stdlib dependency in our Modulefile to make it easier for users who decided
# to use internal copies of stdlib so that their deployments are not coupled to the availability of PuppetForge.  While
# there are tools such as puppet-library for hosting internal forges or for proxying to the public forge, not everyone
# is actually using those tools.
mod 'puppetlabs/stdlib'
mod 'ispavailability/file_concat', '0.1.0'

# Add the puppet-graphite module
mod 'graphite',
  :git => 'https://github.com/miguno/puppet-graphite.git'

Then use librarian-puppet to install (or update) the Puppet modules.

Usage and configuration

General configuration

Installation, make sure service is running and will be started at boot time:

 class { 'graphite': }

Removal/decommissioning:

 class { 'graphite':
   ensure => 'absent',
 }

Install everything but disable service(s) afterwards:

 class { 'graphite':
   status => 'disabled',
 }

Configuring carbon

Carbon is 1 of the applications for graphite. You can activate the 3 separate services individually depending on requirments.

Common config variables:

 # Template
 carbon_config_file => "${module_name}/etc/carbon/carbon.conf.erb"

cache

 carbon_cache_enable => true

Once carbon-cache is running you can send metrics to it via e.g. port 2003/tcp (default for the line receiver port of carbon-cache).

Command line example:

# Format is "<metric> <value> <timestamp>"
$ echo "local.random.diceroll 4 `date +%s`" | nc localhost 2003

See Feeding Carbon for more information.

relay

 carbon_relay_enable => true

aggregator

 carbon_aggregator_enable => true

storage definitions

For defining the storage methods a define is in place:

 graphite::carbon::cache::storage { 'default_1min_for_1day':
   pattern    => '.*'
   retentions => '60s:1d'
 }

An other of sequence can be given with the order => directive.

Configuring max number of open files (limits.conf)

You can optionally configure the maximum number of open files for the user running carbon daemons. Doing so will create an entry in /etc/security/limits.conf (note: this is an implementation detail and should not be relied upon) for the user running the carbon daemons. By default, such an entry will not be created.

Example configuration:

# Optional: Manage /etc/security/limits.conf to tune the maximum number
# of open files, which is a typical setting you may need to change for
# production environments.  Default: false (do not manage)
graphite::carbon::limits_manage: true
graphite::carbon::limits_nofile: 32768

Configuring graphite-web

For the graphite-web there are 2 variables:

# Templates
$graphite::web::dashboard_config_template => "${module_name}/etc/graphite-web/dashboard.conf.erb"
$graphite::web::local_settings_template   => "${module_name}/etc/graphite-web/local_settings.py.erb"

The default superuser of the graphite-web application is user admin with password wirbelsturm and email address admin@example.com.

Create your own hashed password for the admin user of graphite-web

You can define a custom superuser for graphite-web via the parameters:

$graphite::web::admin_user
$graphite::web::admin_password
$graphite::web::admin_email

The password must be in an encrypted, hashed format. You can use Python to create your own custom password as follows (you must have a recent version of Django installed locally). The following example hashes (encrypts) the password wirbelsturm with a salt of yhmSGMwIMU0t.

First we will install Django in a local sandbox because we only need it to create hashed passwords:

$ sudo pip install virtualenv
$ virtualenv /tmp/django-sandbox
$ cd /tmp/django-sandbox
$ source bin/activate
(django-sandbox) $ pip install django

Now you can use Python to encrypt your password:

(django-sandbox) $ python
>>> from django.utils.crypto import pbkdf2
>>> import base64, hashlib
>>> algorithm = 'pbkdf2_sha256'
>>> iterations = 10000
>>> salt = 'yhmSGMwIMU0t'               # <<<< Pick your own random string instead of this one.
>>> plaintext_password = 'wirbelsturm'  # <<<< Use your own unencrypted password here.
>>> hash = pbkdf2(plaintext_password, salt, iterations, 32, hashlib.sha256).encode('base64').strip()
>>> hashed_password = '{algorithm}${iterations}${salt}${hash}'.format(algorithm=algorithm,iterations=iterations,salt=salt,hash=hash)
>>> print hashed_password
pbkdf2_sha256$10000$yhmSGMwIMU0t$HDegvfcy2i14qhQgWhDP7fL5Pf658Cfu065iv0e8YlE=

You would then use pbkdf2_sha256$10000$yhmSGMwIMU0t$HDegvfcy2i14qhQgWhDP7fL5Pf658Cfu065iv0e8YlE= as the value for graphite::web::admin_password.

Lastly we destroy our local Django sandbox as we do not need it anymore:

>>> exit()
(django-sandbox) $ deactivate
$ rm -rf /tmp/django-sandbox

See Password management in Django.

Configuring max number of open files (limits.conf)

You can optionally configure the maximum number of open files for the user running graphite-web. Doing so will create an entry in /etc/security/limits.conf (note: this is an implementation detail and should not be relied upon) for the user running graphite-web. By default, such an entry will not be created.

Example configuration:

# Optional: Manage /etc/security/limits.conf to tune the maximum number
# of open files, which is a typical setting you may need to change for
# production environments.  Default: false (do not manage)
graphite::web::limits_manage: true
graphite::web::limits_nofile: 32768

Example configuration with Nginx (using Hiera)

This example was tested on RHEL 6. It runs gunicorn on port 8081/tcp for serving graphite-web, and nginx on port 8080/tcp is acting as the main frontend that relays requests to gunicorn. Note that the various www_root parameters are specific to the RedHat OS family.

This example requires the Puppet module puppet-nginx for managing nginx.

---
classes:
  - graphite
  - nginx

## Graphite
#
# Note: If clients connecting to carbon-cache are experiencing errors such as connection refused by the daemon, a common
# reason is a shortage of file descriptors (ulimit -n).  A value of 8192 or more may be necessary depending on how many
# clients are simultaneously connecting to the carbon-cache daemon.
graphite::carbon_cache_enable: true
graphite::web::admin_email: 'your.email@example.com'
graphite::web::django_secret_key: 'kja0x0w3qdjf;kjtg098yh#%&ISZFGH'

## Nginx
nginx::nginx_upstreams:
  'gunicorn_app_server':
    ensure: 'present'
    members:
      - 'localhost:8081 fail_timeout=0'
nginx::nginx_vhosts:
  '_':
    www_root: '/usr/share/graphite/webapp/content'
    ipv6_enable: false
    listen_port: 8080
    access_log: '/var/log/nginx/monitor1.access.log'
    error_log:  '/var/log/nginx/monitor1.error.log'
    vhost_cfg_append:
      client_max_body_size: '64M'
      keepalive_timeout: 5
    location_cfg_append:
      proxy_pass_header: 'Server'
      proxy_redirect: 'off'
      'proxy_set_header X-Real-IP': '$remote_addr'
      'proxy_set_header Host': '$http_host'
      'proxy_set_header X-Scheme': '$scheme'
      proxy_connect_timeout: 10
      proxy_read_timeout: 10
      proxy_pass: 'http://gunicorn_app_server'
nginx::nginx_locations:
  'media':
    vhost: '_'
    location: '/media/'
    www_root: '/usr/lib/python2.6/site-packages/django/contrib/admin'

Configuring whisper

Whisper is the storage for all the data. This one has no special configuration.

Requirements

Tested with RHEL/CentOS 6
Puppet 3.x
Ruby 1.9 (preferred) or 1.8

Assumptions

Certain assumptions have been made with this module:

Carbon, graphite-web & whisper are available through a package repository.
When no config files are specified, the default ones are used.
All three applications are standard installed.
For the three processes from carbon; unless activated they are not running.
If you want to run graphite-web, then supervisord 3.x must be available through a package repository and you have loaded the puppet-supervisor module (e.g. through librarian-puppet) as forked by miguno.
If you want to configure the maximum number of open files (nofile in /etc/security/limits.conf) through this Puppet module, then you must have loaded the puppet-limits module (e.g. through librarian-puppet) as forked by miguno.

FAQ

Configure additional users and groups for Graphite web UI?

Once graphite-web is up and running you can access its user management component (driven by Django) at:

http://<graphite-root-url>/admin/

You must login with a user account that has superuser rights or the relevant permissions in order to be able to add, modify and remove users and groups (the initial admin user has such permissions).

Manually create a graphite-web admin / superuser account?

Graphite-web is based on Django, so you can follow the standard Django procedures.

$ sudo python /path/to/manage.py createsuperuser

It is recommended to use the name admin for the admin/superuser account.

Reset admin password for graphite-web?

Graphite-web is based on Django, so you can follow the standard Django procedures.

$ sudo python /path/to/manage.py changepassword admin

Alternatively you can also use the Django shell:

$ sudo python /path/to/manage.py shell
Python 2.6.6 (r266:84292, Oct 12 2012, 14:23:48)
>>> from django.contrib.auth.models import User
>>> user = User.objects.get(username='normaluser')
>>> user.set_password('plain password')  # Don't enter the salted/hashed version here!
>>> user.save()

Other helpful User methods are:

>>> admins = User.objects.filter(is_superuser=True)

See How to reset django admin password for more information.

Note: In case you need to manually create the admin user run the following command:

$ sudo python /path/to/manage.py createsuperuser
Username (Leave blank to use 'root'): admin
E-mail address: foo@example.com
Password:
Password (again):
Superuser created successfully.

Get a dump of the Graphite web UI database?

Note: This is about the database Graphite uses to store user accounts and dashboards. It is NOT about the actual metrics, which are stored in Whisper files.

$ sudo python /path/to/manage.py dumpdata > /tmp/django-dump.json

See Bootstrap the Django DB for more information.

Credits

This module is based on -- and a fork of -- the great work done by electrical.

miguno / puppet-graphite

puppet-graphite

Installation

Usage and configuration

General configuration

Configuring carbon

cache

relay

aggregator

storage definitions

Configuring max number of open files (limits.conf)

Configuring graphite-web

Create your own hashed password for the admin user of graphite-web

Configuring max number of open files (limits.conf)

Example configuration with Nginx (using Hiera)

Configuring whisper

Requirements

Assumptions

FAQ

Configure additional users and groups for Graphite web UI?

Manually create a graphite-web admin / superuser account?

Reset admin password for graphite-web?

Get a dump of the Graphite web UI database?

Credits

About

Languages