Ruby HTML
Latest commit d97f406 Mar 15, 2017 @gcymbalski gcymbalski committed on GitHub Merge pull request #550 from cwjohnston/changelog/027-upgrade-notes
augment changelog for 4.0.0 to describe sysv/systemd upgrade issue
Permalink
Failed to load latest commit information.
.github Add pull request and issue templates (#439) Apr 22, 2016
attributes update default versions of Sensu Core, Enterprise and Enterprise Dash… Mar 14, 2017
definitions [rabbitmq_credentials] remove unnecessary reference to undefined vari… Sep 20, 2016
examples/ssl remove outdated Vagrantfile and supporting material in examples dir Mar 3, 2016
libraries [linux] add helper method for redhat/centos version strings Feb 9, 2017
providers [sensu_service] remove support for init_style property Feb 6, 2017
recipes [windows] set append to true on group resource Feb 15, 2017
resources [sensu_check] fix conditional validation of subscribers/standalone (#547 Mar 14, 2017
templates/default update template for sensu-enterprise defaults, manage heap dump direc… Nov 23, 2016
test [sensu_check] validate subscribers/standalone on create action only Feb 15, 2017
.foodcritic Disable foodcritic rules for now Mar 7, 2017
.gitignore replace librarian-chef with berkshelf Sep 22, 2016
.kitchen.yml Test on the latest CentOS in Test Kitchen Mar 7, 2017
.rspec add unit tests Nov 24, 2015
.rubocop.yml Add guard, rubocop and foodcritic to bundle (#456) Jul 30, 2016
.travis.yml Add guard, rubocop and foodcritic to bundle (#456) Jul 30, 2016
Berksfile replace librarian-chef with berkshelf Sep 22, 2016
CHANGELOG.md augment changelog for 4.0.0 to describe sysv/systemd upgrade issue Mar 15, 2017
CODE_OF_CONDUCT.md specify contact email address in code of conduct Feb 3, 2016
CONTRIBUTING.md add more specific notes on testing Mar 3, 2016
Gemfile replace emeril with stove Nov 2, 2016
Guardfile Add guard, rubocop and foodcritic to bundle (#456) Jul 30, 2016
HISTORY.md [changlog] add missing history.md Aug 8, 2016
LICENSE add license document Feb 3, 2016
README.md [sensu_service] remove support for init_style property Feb 6, 2017
Rakefile replace emeril with stove Nov 2, 2016
TESTING.md [rabbitmq] use erlang solutions repo on all platforms Aug 2, 2016
chefignore Update chefignore file Sep 21, 2016
metadata.rb bump version to 4.0.1 for development Mar 14, 2017

README.md

sensu

Build Status Cookbook VersionBuild Status

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"]["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

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:

  1. the Chef node object
  2. one or more keys, providing the path to walk
  3. 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:

  1. the Chef node object
  2. 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.