Puppet Integration

Puppet is IT automation software that enables system administrators to manage provisioning and configuration of their infrastructure.  LogicMonitor’s Puppet module allows your Puppet infrastructure code to manage your LogicMonitor account as well.

Notes:

• This module is only compatible with linux servers. Windows compatibility may be added in future releases.

Module Overview

LogicMonitor’s Puppet module defines 5 classes and 4 custom resource types:

Classes

• logicmonitor: Handles setting the credentials needed to interact with the LogicMonitor API
• logicmonitor::config: Provides the default credentials to the logicmonitor class
• logicmonitor::master: Collects the exported lm_host resources and lm_hostgroup resources. Communicates with the LogicMonitor API
• logicmonitor::collector: Handles LogicMonitor collector management for the device. Declares an instances of lm_collector and lm_installer resources
• logicmonitor:host: Declares an exported lm_host resource

Resource Types

• lm_hostgroup: Defines the behavior of the handling of LogicMonitor device groups. We recommend using exported resources
• lm_host: Defines the handling behavior of LogicMonitor devices. Used only within the logicmonitor::host class
• lm_collector: Defines the handling behavior of LogicMonitor collectors. Used only with the logicmonitor::collector class
• lm_installer: Defines the handling behavior of LogicMonitor collector binary installers. Used only within the logicmonitor::collector class

Requirements

In order to use LogicMonitor’s Puppet Module, you’ll need to make sure you have the following:

1. Ruby 1.8.7 or 1.9.3
2. Puppet 3.X
3. JSON Ruby gem (included by default in Ruby 1.9.3)
4. Store Configs in Puppet

Store configs are required for the exported resources used by this module. To enable store configs, add storeconfigs = true to the [master] section of your puppet.conf file, like so:

# /etc/puppet/puppet.conf
[master]
storeconfigs = true

Once enabled, Puppet will need a database to store the config info. Puppet recommends PuppetDB, although other database solutions are available.

Device Configuration

As with your other LogicMonitor devices, the collector will need to communicate with the device in order to gather data.  Make sure the correct properties and authentication protocols are configured as part of the Puppet installation.

Installing the LogicMonitor Puppet Module

You can install LogicMonitor’s original Puppet Module via GitHub:

$ cd /etc/puppet/modules
$ git clone git: //github.com/logicmonitor/logicmonitor-puppet.git
$ mv logicmonitor-puppet logicmonitor

Getting Started

Once you’ve installed LogicMonitor’s Puppet Module, you can get started using the following sections:

Create a new user for Puppet

We recommend you create a new user with administrator privileges in your Logic Monitor account that you will use exclusively within your Puppet nodes to track changes made by Puppet in the audit log.

Configuration

• Class: logicmonitor (modules/logicmonitor/manifests/init.pp)

This is the top level class for the LogicMonitor module. It’s purpose is to set the LogicMonitor credentials to be used by all the child classes. Explicit declaration of this class will override the default credentials set in the logicmonitor::config class. This class does not need to be explicitly declared.

Parameter	Description	Inputs
account	Your LogicMonitor account name For example, if you log in to https://mycompany.logicmonitor.com, your account should be “mycompany”	String Default to $account logicmonitor::config
user	The username of a LogicMonitor user with access to manage hosts, groups, and collectors. Actions taken by Puppet show up in the audit log as this user. We recommend creating a dedicated user for your Puppet account.	String. Default to $user in logicmonitor::config
password	The password associated with the LogicMonitor user Puppet will be making changes on behalf of.	String Default to $password in logicmonitor::config

• Class: logicmonitor::config (modules/logicmonitor/manifests/config.pp)

This class is used to set the default LogicMonitor account credentials for your Puppet environment. This class does not need to be explicitly declared.

Parameters: None

• Class: logicmonitor::master (modules/logicmonitor/manifests/master.pp)

The master class enables communication between the LogicMonitor module and your LogicMonitor account for group and device management. This class acts as the collector for the lm_host and lm_hostgroup exported resources. This prevents conflicts and provides a single point of contact for communicating with the LogicMonitor API. This class must be explicitly declared on a single device. NOTE: All devices with the logicmonitor::collector and logicmonitor::master classes will need to be able to make outgoing http(s) requests.

Parameters: none

• Class: logicmonitor::collector (modules/logicmonitor/manifests/collector.pp)

This class manages the creation, download and installation of a LogicMonitor collector on the specified node.

• The only absolute requirement for a collector node is that is is Linux and can make an outgoing SSL connection over port 443
• We suggest the collector system have at least 1G of RAM
• If the collector will be collecting data for more than 100 hosts, it is a good idea to dedicate a machine to it

Parameter	Description	Inputs
install_dir	The path to install the LogicMonitor collector.	A valid directory path. Default to “/usr/local/logicmonitor”

Examples

To add collector to a node:

include logicmonitor::collector

If you want to specify a specific location where you’d like to install a collector:

class{"logicmonitor::collector":
install_dir => $install_dir,
}

Class: logicmonitor::host (modules/logicmonitor/manifests/host.pp)

This class is used to add devices to your LogicMonitor account. Devices which are managed through Puppet will have any properties not specified in the device definition removed.

Parameter	Description	Inputs
collector	The fully qualified domain name of the collector machine. You can find this by running hostname -f on the collector machine.	String. No Default (required)
hostname	The IP address or fully qualified domain name of the node. This is the way that the collector reaches this device.	String. Default to $fqdn
displayname	The human readable name to display in your LogicMonitor account. e.g. “dev2.den1”	String. Default to $fqdn
description	The long text description of the host. This is seen when hovering over the device in your LogicMonitor account.	String. No Default (Optional)
alertenable	Turn on or off alerting for the device. If a parent group is set to alertenable=false alerts for child hosts will be turned off as well.	Boolean, Default to True.
groups	A list of groups that the device should be a member of. Each group is a String representing its full path. E.g. “/linux/production”	List. No Default (Optional)
properties	A hash of properties to be set on the host. Each entry should be “propertyName” => “propertyValue”. E.g. {“mysql.port” => 6789, “mysql.user” => “dba1”}	Hash. No Default (Optional)

Examples

class {'logicmonitor::host':
        collector => "qa1.domain.com",
        hostname => "10.171.117.9",
        groups => ["/Puppetlabs", "/Puppetlabs/Puppetdb"],
        properties => {"snmp.community" => "Puppetlabs"},
        description => "This device hosts the PuppetDB instance for this deployment",
      }

class {'logicmonitor::host':
        collector => $fqdn,
        displayname => "MySQL Production Host 1",
        groups => ["/Puppet", "/production", "/mysql"],
        properties => {"mysql.port" => 1234},
      }

Adding a Device Group:

Type: Lm_hostgroup Device groups should be added using an exported resource to prevent conflits. It is recommend device groups are added from the same node where the logicmonitor::master class is included. Devices can be included in zero, one, or many device groups.  Device groups are used to organize how your LogicMonitor Devices are displayed and managed and do not require a collector . Properties set at the device group level will be inherited by any devices added to the group.

Parameter	Description	Inputs
namevar	The puppet namevar is used to uniquely identify the resource. If the fullpath parameter is empty, the namevar is used as the fullpath.	String. No default (required)
fullpath	The full path of the host group. E.g. a host group “bar” with parent group “foo” would have the fullpath of “/foo/bar”	String. Default to $namevar. (required)
ensure	Puppet ensure parameter.	present/absent. No Default (required)
alertenable	Turn on/off alerting for the group. If alertenable is false, all child groups and hosts will have alerting disabled	Boolean. Default to True.
properties	A hash of properties to be set on the host. Each entry should be “propertyName” => “propertyValue”. E.g. {“mysql.port” => 6789, “mysql.user” => “dba1”}. The properties will be inherited by all child groups and hosts	Hash, No Default (optional)
description	The long text description of the host. This is seen when hovering over the group in your LogicMonitor account.	String. No Default (optional)

To add and edit properties of device groups use lm_hostgroup, example below.

@@lm_hostgroup{"/parent/child/grandchild/greatgrandchild":
  ensure => present,
  alertenable => true,
  properties => {"snmp.community" => "n3wc0mm", "mysql.port" => 9999,"fake.pass" => "12345"},
  description => "This is the description that shows up in the yellow box from hover in your LM account",
}

For more examples of the module in action, check out logicmonitor-puppet/README.md.