Description

This cookbook provides custom resources and service recipes to install and configure
Sensu, a monitoring framework.

The custom resources provide building blocks for creating a monitoring
cookbook specific to your environment (wrapper). Without such a
wrapper, no Sensu configuration files will be created for your nodes.

An example wrapper cookbook can be found HERE.

How to Write Reusable Chef Cookbooks

Contributing

See CODE_OF_CONDUCT.md, CONTRIBUTING.md and TESTING.md documents.

Dependencies

Platforms

Ubuntu/Debian
RHEL and derivatives
Fedora
Windows
AIX

Chef

Chef 12+

Cookbooks

NOTE: This cookbook either constrains its dependencies optimistically (>=) or
not at all. You're strongly encouraged to more strictly manage these
dependencies in your wrapper cookbook.

Package versioning

This cookbook makes no attempt to manage the versions of its package
dependencies. If you desire or require management of these versions, you should
handle these via your wrapper cookbook.

Prerequisites

SSL configuration

Running Sensu with SSL is recommended; by default this cookbook attempts to load
SSL credentials from a data bag sensu, with an item ssl, containing the
required SSL certificates and keys. These data bag items may be encrypted via
native Chef encrypted data bags or via Chef Vault.

The data loaded from the data bag by default is expected to be formatted as
follows:

{
  "server": {
    "cert": "CERTIFICATE_DATA",
    "key": "PRIVATE_KEY_DATA",
    "cacert": "CA_CERTIFICATE_DATA"
  },
  "client": {
    "cert": "CERTIFICATE_DATA",
    "key": "PRIVATE_KEY_DATA"
  }
}

All of the above values are expected to be strings comprised of PEM-formatted
credentials with escaped line endings. See
test/integration/data_bags/sensu/ssl.json for a more literal example.

If the attempt to load SSL credentials from a data bag fails, the cookbook will
log a warning but proceed with the rest of the Chef run anyway, on the
assumption that credentials will be inserted into the Chef "run state" (i.e.
node.run_state['sensu']['ssl']) in the same format using the
Sensu::ChefRunState helper methods, set_sensu_run_state and
get_sensu_run_state.

Please see the documentation for the run state helper
methods for more information.

This cookbook comes with a tool to generate the certificates and data bag items.
If the integrity of the certificates is ever compromised, you must regenerate
and redeploy them.

cd examples/ssl
./ssl_certs.sh generate
knife data bag create sensu

Use the plain-text data bag item:

knife data bag from file sensu ssl.json

Or, encrypt it with your data bag secret. See Encrypt a Data Bag
for more information.

knife data bag --secret-file /path/to/your/secret from file sensu ssl.json

./ssl_certs.sh clean

Recipes

sensu::default

Installs Sensu and creates a base configuration file, intended to be
extended. This recipe must be included before any of the Sensu LWRP's
can be used. This recipe does not enable or start any services.

sensu::rabbitmq

Installs and configures RabbitMQ for Sensu, from configuring SSL to
creating a vhost and credentials. This recipe relies heavily on the
community RabbitMQ cookbook LWRP's.

sensu::redis

Installs and configures Redis for Sensu. This recipe uses the
RedisIO cookbook and installs Redis from source.

sensu::enterprise

Installs and configures Sensu Enterprise.

sensu::server_service

Enables and starts the Sensu server.

sensu::client_service

Enables and starts the Sensu client.

sensu::api_service

Enables and starts the Sensu API.

sensu::enterprise_service

Enables and starts Sensu Enterprise.

sensu::enterprise_dashboard

Installs and configures Sensu Enterprise Dashboard.

sensu::enterprise_dashboard_service

Enables and starts Sensu Enterprise Dashboard.

Attributes

Installation

node["sensu"]["version"] - Sensu build to install.

node["sensu"]["use_unstable_repo"] - If the build resides on the
"unstable" repository.

node["sensu"]["apt_repo_codename"] - Override LSB release codename
detected by ohai for purposes of configuring the apt repository definition.

node["sensu"]["yum_repo_releasever"] - Override $releasever string
used in yum repository definition.

node["sensu"]["directory"] - Sensu configuration directory.

node["sensu"]["log_directory"] - Sensu log directory.

node["sensu"]["log_level"] - Sensu log level (eg. "warn").

node["sensu"]["use_ssl"] - If Sensu and RabbitMQ are to use SSL.

node["sensu"]["user"] - The user who owns all sensu files and directories. Default
"sensu".

node["sensu"]["group"] - The group that owns all sensu files and directories.
Default "sensu".

node["sensu"]["use_embedded_ruby"] - If Sensu Ruby handlers and plugins
use the embedded Ruby in the Sensu package (default: true).

node["sensu"]["service_max_wait"] - How long service scripts should wait
for Sensu to start/stop.

node["sensu"]["loaded_tempfile_dir"] - Where Sensu stores temporary files. Set a persistent directory if you use hardened system that cleans temporary directory regularly.

Windows

Sensu requires Microsoft's .Net Framework to run on Windows. The following attributes influence the installation of .Net via this cookbook:

node["sensu"]["windows"]["install_dotnet"] - Toggles installation of .Net Framework using ms_dotnet cookbook. (default: true)

node["sensu"]["windows"]["dotnet_major_version"] - Major version of .Net Framework to install. (default: 4)

Adjusting the value of dotnet_major_version attribute will influence which
recipe from ms_dotnet cookbook will be included. See ms_dotnet cookbook
for additional details on using this cookbook.

Transport

node["sensu"]["transport"]["name"] - Name of transport to use for Sensu communications. Default "rabbitmq"

RabbitMQ

node["sensu"]["rabbitmq"]["hosts"] - Array of RabbitMQ hosts as strings, which will be combined with other RabbitMQ attributes to generate the Sensu RabbitMQ transport configuration as an array of hashes. Falls back to node["sensu"]["rabbitmq"]["host"] when empty. Defaults to an empty array.

node["sensu"]["rabbitmq"]["host"] - RabbitMQ host.

node["sensu"]["rabbitmq"]["port"] - RabbitMQ port, usually for SSL.

node["sensu"]["rabbitmq"]["ssl"] - RabbitMQ SSL configuration, DO NOT EDIT THIS.

node["sensu"]["rabbitmq"]["vhost"] - RabbitMQ vhost for Sensu.

node["sensu"]["rabbitmq"]["user"] - RabbitMQ user for Sensu.

node["sensu"]["rabbitmq"]["password"] - RabbitMQ password for Sensu.

Redis

node["sensu"]["redis"]["host"] - Redis host.

node["sensu"]["redis"]["port"] - Redis port.

Sensu API

node["sensu"]["api"]["host"] - Sensu API host, for other services to reach it.

node["sensu"]["api"]["bind"] - Sensu API bind address.

node["sensu"]["api"]["port"] - Sensu API port.

Sensu Enterprise

node["sensu"]["enterprise"]["repo_protocol"] - Sensu Enterprise repo protocol (e.g. http, https)

node["sensu"]["enterprise"]["repo_host"] - Sensu Enterprise repo host

node["sensu"]["enterprise"]["version"] - Desired Sensu Enterprise package version

node["sensu"]["enterprise"]["use_unstable_repo"] - Toggle use of Sensu Enterprise unstable repository

node["sensu"]["enterprise"]["log_level"] - Configure Sensu Enterprise log level

node["sensu"]["enterprise"]["heap_size"] - Configure Sensu Enterprise heap size

node["sensu"]["enterprise"]["heap_dump_path"] - Configure path where Sensu Enterprise will store heap dumps. Directory path will be managed by Chef. Honored by Enterprise version 2.0.0 and newer.

node["sensu"]["enterprise"]["java_opts"] - Specify additional Java options when running Sensu Enterprise

node["sensu"]["enterprise"]["max_open_files"] - Specify maxiumum number of file handles. Honored by Enterprise version 1.7.2 and newer.

Custom Resources (LWRPs)

Define a client

sensu_client node["name"] do
  address node["ipaddress"]
  subscriptions node["roles"] + ["all"]
  additional(:cluster => node["cluster"])
end

The sensu_client provider also supports the following optional attributes:

deregister
deregistration
keepalive
keepalives
redact
registration
safe_mode
socket

Define a handler

sensu_handler "pagerduty" do
  type "pipe"
  command "pagerduty.rb"
  severities ["ok", "critical"]
end

Define a check

sensu_check "redis_process" do
  command "check-procs.rb -p redis-server -C 1"
  handlers ["default"]
  subscribers ["redis"]
  interval 30
  additional(:notification => "Redis is not running", :occurrences => 5)
end

Define a filter

sensu_filter "environment" do
  attributes(:client => {:environment => "development"})
  days(
    :all => [{ :begin => "05:00 PM", :end => "09:00 AM" }}],
    :saturday => [{ :begin => "09:00 AM", :end => "05:00 PM" }],
    :sunday => [{ :begin => "09:00 AM", :end => "05:00 PM" }]
  )
  negate true
end

Define a mutator

sensu_mutator "opentsdb" do
  command "opentsdb.rb"
end

Define a custom configuration snippet

sensu_snippet "irc" do
  content(:uri => "irc://sensu:password@irc.freenode.net:6667#channel")
end

Install plugins

# define a hash of plugins (gems) WITH VERSIONS PINNED
default['MY_CUSTOM_NAMESPACE']['sensu']['plugins'] = {
  ## pretty much all checks rely on this
  'sensu-plugin' => '2.1.0',
  ## check consul
  'sensu-plugins-consul' => '1.4.1',
  ## check cpu
  'sensu-plugins-cpu-checks' => '1.1.2',
  ## check disks
  'sensu-plugins-disk-checks' => '2.4.0',
  ## check disks
  'sensu-plugins-http' => '2.6.0',
  ## check elasticsearch
  'sensu-plugins-elasticsearch' => '1.5.1',
  ## check load
  'sensu-plugins-load-checks' => '3.0.0',
  ## check memory
  'sensu-plugins-memory-checks' => '3.0.2',
  ## check network
  'sensu-plugins-network-checks' => '2.0.1',
  ## check processes
  'sensu-plugins-process-checks' => '2.4.0',
  ## check rabbitmq
  'sensu-plugins-rabbitmq' => '3.2.0',
  ## check redis
  'sensu-plugins-redis' => '2.0.0',
  ## check chef
  'sensu-plugins-chef' => '3.0.2',
  'hashie' => '3.5.6',
  ## check nginx
  'sensu-plugins-nginx' => '2.2.0'
}

# loop over each gem and install it into the sensu embedded ruby
node['MY_CUSTOM_NAMESPACE']['sensu']['plugins'].each do |plugin, version|
  sensu_gem plugin do
    version version
  end
end

Helper modules and methods

Run State Helpers

The Sensu::ChefRunState module provides helper methods which populate node.run_state['sensu'] with arbitrary key/value pairs. This provides a means for wrapper cookbooks to populate the node.run_state with data required by the cookbook, e.g. SSL credentials, without cookbook itself enforcing source for that data.

NOTE: The node.run_state is not persisted locally nor on a Chef server. Data stored here exists only for the duration of the Chef run.

`set_sensu_state`

This method sets values inside the node.run_state['sensu'] Mash, and expects arguments in the following order:

the Chef node object
one or more keys, providing the path to walk
the value to set at that path

Example:

set_sensu_state(node, 'food', 'nachos', true)

The above sets the value of node.run_state['sensu']['food']['nachos'] to true.

`get_sensu_state`

This method retrieves the value of a key inside the node.run_state['sensu'] Mash and expects arguments in the following order:

the Chef node object
one or more keys, providing the path to walk

Examples:

get_sensu_state(node, 'food', 'nachos') would return true

When no value is set for a requested path, this method returns nil:

get_sensu_state(node, 'this', 'path', 'is', 'invalid') returns nil

Support

Please visit sensuapp.org/support for details on community and commercial
support resources, including the official IRC channel.

Dependent cookbooks

Contingent cookbooks

Sensu cookbook changelog

This file is used to track changes made in recent versions of the Sensu
cookbook. Please see HISTORY.md for changes from older versions of this project.

Unreleased

4.0.6 - 2017-09-12

Fixed

on systems with restrictive umasks the permissions for rabbitmq ssl directories ended up with permissions that made it non functional. This sets them to the required permissions to make things work (@jessebolson)

4.0.5 - 2017-09-12

Fixed

client.json should now be used by node['sensu']['user'] rather than node['sensu']['admin_user']

4.0.4 - 2017-09-12

Features

added example in README.md how to easily install a bunch of sensu plugins into the emebedded ruby context (@majormoses)

4.0.3 - 2017-09-12

Features

added support for suse linux (@runningman84)

4.0.2 - 2017-07-06

Changes

Tests now run via ChefDK

Fixed

Updated node attribute syntax for Chef 13 compatibility
Updated recipes to allow for "amazon" platform family under Chef 13

Features

When given a value, node["sensu"]["yum_repo_releasever"] attribute will be
used in lieu of $releasever yum variable, restoring support for RHEL
derivatives, e.g. Amazon Linux.
When given a value, node["sensu"]["apt_repo_codename"] attribute will be
used in lieu of the LSB codename detected by ohai on Debian and Ubuntu.

4.0.0 - 2017-03-14

Important

Due to sysv init scripts being replaced with systemd unit files on select platforms, upgrading Sensu package from version < 0.27 to >= 0.27 may leave Sensu services in an unexpected state. This cookbook does not attempt to address this condition. See the Sensu 0.27 changelog for further details.

As required to support Sensu 0.27 and later:

Configuration of yum and apt package repositories have changed to target
per-platform version packages, using $releasever or release codename,
respectively.
The init_style attribute has been removed from sensu_service resource.
The sensu_service resource will now use Chef's default service
provider on each platform.

Changes

The default version of Sensu is now 0.28.4

The default version of Sensu Enterprise is now 2.5.1

The default version of Sensu Enterprise Dashboard is now 2.3.0

Fixed

sensu_check resources can now be deleted without requiring
standalone or subscriptions attributes
The built-in Administrator group should now be usable for the value
of node["sensu"]["group"] on Windows platforms.

3.2.0 - 2017-01-10

Important

The runit init_style is now deprecated and will be removed in the next
major version of this cookbook.

Features

Added days parameter to sensu_filter resources. This parameter accepts
a hash of time windows passed as the value of a filter's when
attribute. See the filter reference
doc
for more detail on time windows.

Added new attributes added for configuring Sensu Enterprise max open files
and heap dump path parameters.

Changes

The default version of Sensu is now 0.26.5

The default version of Sensu Enterprise is now 1.14.10

The default version of Sensu Enterprise Dashboard is now 1.12.0

The account created for Sensu on Windows now uses the
node["sensu"]["user"] attribute instead of a hard-coded value.

Project changes

For purposes of releasing this cookbook, emeril has been replaced with stove.

3.1.2 - 2016-09-29

Changes

The _enterprise_repo recipe now configures yum repos for both noarch
and $basearch so that sensu-enterprise-dashboard package can be installed.

Due to upstream repository changes, the default value of
node['sensu']['enterprise-dashboard]['version'] has changed from
1:1.4.0-1 to 1.4.0-1.

3.1.0 - 2016-09-23

Changes

The default version of Sensu installed by this cookbook is now 0.26.3-1.

Eliminated resource cloning warnings when calling rabbitmq_credentials definition.

Replaced librarian-chef with Berkshelf.

Updated test-kitchen configuration for windows platforms.

Updated metadata to depend on Chef >= 12.

Updated dependencies for yum, apt and windows cookbooks to make sense for Chef >= 12.

Features

Added support for AIX platform

Added support for configuring SENSU_LOADED_TEMPFILE_DIR via node["sensu"]["loaded_tempfile_dir"]

Added logic for detecting gem binary path on Windows platform

Fixes

Using baseurl attribute for yum_repository instead of url property

Fixed broken tests for availability of sensitive attribute

3.0.0 - 2016-08-09

Important

This cookbook now supports Chef version 12+. Earlier versions may work but
are not supported.

The default version of Sensu installed by this cookbook is now 0.25.6-1.

The default value of node["sensu"]["use_embedded_ruby"] is now true.

The rabbitmq recipe now installs Erlang via the Erlang Solutions repository on all platforms.

Behavior changes

Installation of the .NET Framework is now handled by the ms_dotnet cookbook.

Features

Sensu Enterprise repository URL is now configurable via attributes.

Sensu Enterprise JVM options are now configurable via attributes.

Sensu transport name is now configurable via attributes.

The sensu_base_config provider now honors node["rabbitmq"]["hosts"] attribute,
providing an array of hosts to use for configuring rabbitmq transport with multiple brokers.
When hosts attribute has no value, we fall back to value of node["sensu"]["rabbitmq"]["host"]
attribute.

The sensu_client provider now honors the following additional client
attributes, as defined in the Sensu Client Reference Documentation:

deregister
deregistration
keepalives
redact
registration
safe_mode
socket

Check definition LWRP has been updated to support named aggregates (added
in Sensu 0.25) and multiple named aggregates (coming in Sensu 0.26).

Integration tests for Windows now use the new Chef Zero Scheduled
Task provider which makes testing this platform much easier.

Expanded unit tests in many areas, including sensu_base_config,
sensu_client, sensu_json_file and other LWRPs.

Fixes

Directories created by the sensu_json_file provider now assume the mode
defined by the value of node["sensu"]["directory_mode"] attribute.

The method used to look up sensu_service_trigger ruby block in the
resource collection has been updated to eliminate conditions where Sensu
services may not be notified to restart.

Resources are now created by the sensu_json_file provider
unconditinally, unblocking the use of library cookbooks like zap to
clean up unmanaged files on disk.

2.12.0 - 2016-03-14

Project changes

The Sensu cookbook project has adopted a new contribution workflow and a
new code of conduct policy. Please see the relevant documents in
repo for details.

Behavior changes

Values for owner and group properties on sensu_json_file resources
now default to lazy evaluation of node attributes sensu.admin_user and
sensu.group respectively. (#426)

Data bags remain default source of SSL certificates, but are now optional:

With the addition of Sensu state helpers in #410 recipes which
access credentials via data bags (i.e. `default`, `rabbitmq` and
`enterprise` recipes) have been updated to make these data bag
items optional.

Please see the readme and integration test suite for examples of
using these helpers.

Testing notes have been added in TESTING.md to describe some of the
platform/suite combinations which are disabled or otherwise
require special configuration.

Features

Added ChefSpec test coverage for the following:

default and client_service recipes
sensu_gem LWRP
Sensu::Helpers library #select_attributes and #gem_binary methods

Added source attribute to sensu_gem resource
Added upgrade action to sensu_gem resource
Added helpers for storing key/value pairs which persist for duration of the Chef run

Fixes

Allow "standard" as a value of type attribute on sensu_check resources, as described in Sensu documentation.

Collaborator Number Metric

4.0.6 passed this metric

Contributing File Metric

4.0.6 passed this metric

Foodcritic Metric

4.0.6 failed this metric

FC059: LWRP provider does not declare use_inline_resources: sensu/providers/api_stash.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/asset.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/base_config.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/check.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/client.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/dashboard_config.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/filter.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/gem.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/handler.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/json_file.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/mutator.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/plugin.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/service.rb:1
FC059: LWRP provider does not declare use_inline_resources: sensu/providers/snippet.rb:1
FC104: Use the :run action in ruby_block instead of :create: sensu/providers/json_file.rb:14
FC104: Use the :run action in ruby_block instead of :create: sensu/providers/json_file.rb:30
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_aix.rb:30
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_linux.rb:42
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_linux.rb:59
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_linux.rb:81
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_linux.rb:94
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_windows.rb:37
FC104: Use the :run action in ruby_block instead of :create: sensu/recipes/_windows.rb:44
Run with Foodcritic Version 12.2.1 with tags metadata,correctness ~FC031 ~FC045 and failure tags any

License Metric

4.0.6 passed this metric

No Binaries Metric

4.0.6 passed this metric

Testing File Metric

4.0.6 passed this metric

Version Tag Metric

4.0.6 passed this metric

Adoptable Cookbooks List

Supermarket Belongs to the Community

View our collection of guides, documentation, and articles

Select Badges

Select Supported Platforms

Select Status

Description

Contributing

Dependencies

Platforms

Chef

Cookbooks

Package versioning

Prerequisites

SSL configuration

Recipes

sensu::default

sensu::rabbitmq

sensu::redis

sensu::enterprise

sensu::server_service

sensu::client_service

sensu::api_service

sensu::enterprise_service

sensu::enterprise_dashboard

sensu::enterprise_dashboard_service

Attributes

Installation

Windows

Transport

RabbitMQ

Redis

Sensu API

Sensu Enterprise

Custom Resources (LWRPs)

Define a client

Define a handler

Define a check

Define a filter

Define a mutator

Define a custom configuration snippet

Install plugins

Helper modules and methods

Run State Helpers

set_sensu_state

get_sensu_state

Support

Dependent cookbooks

Contingent cookbooks

Sensu cookbook changelog

Unreleased

4.0.6 - 2017-09-12

Fixed

4.0.5 - 2017-09-12

Fixed

4.0.4 - 2017-09-12

Features

4.0.3 - 2017-09-12

Features

4.0.2 - 2017-07-06

Changes

Fixed

Features

4.0.0 - 2017-03-14

Important

Changes

Fixed

3.2.0 - 2017-01-10

Important

Features

Changes

Project changes

3.1.2 - 2016-09-29

Changes

3.1.0 - 2016-09-23

Changes

Features

Fixes

3.0.0 - 2016-08-09

Important

`set_sensu_state`

`get_sensu_state`

Collaborator Number Metric

4.0.6 passed this metric

Contributing File Metric

4.0.6 passed this metric

License Metric

4.0.6 passed this metric

No Binaries Metric

4.0.6 passed this metric

Testing File Metric

4.0.6 passed this metric

Version Tag Metric

4.0.6 passed this metric