Forge Home

Modules

Resources

PuppetEcosystemPuppet CommunityUpdates

sensu

A module to install the Sensu monitoring framework
Project URLRSS FeedReport issues

3,270,865 downloads

5,097 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 5.11.1 (latest)
  • 5.11.0
  • 5.10.1
  • 5.10.0
  • 5.9.0
  • 5.8.0
  • 5.7.0
  • 5.6.0
  • 5.5.1
  • 5.5.0
  • 5.4.0
  • 5.3.1
  • 5.3.0
  • 5.2.1
  • 5.2.0
  • 5.1.0
  • 5.0.0
  • 4.13.1
  • 4.13.0
  • 4.12.0
  • 4.11.0
  • 4.10.0
  • 4.8.0
  • 4.7.1
  • 4.7.0
  • 4.6.0
  • 4.5.1
  • 4.5.0
  • 4.4.1
  • 4.4.0
  • 4.3.0
  • 4.2.1
  • 4.2.0
  • 4.1.0
  • 4.0.0
  • 3.14.0
  • 3.13.0
  • 3.12.0
  • 3.11.0
  • 3.10.0
  • 3.9.0
  • 3.8.0
  • 3.7.0
  • 3.6.0
  • 3.5.0
  • 3.4.1
  • 3.4.0
  • 3.3.0
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.63.0
  • 2.62.3
  • 2.62.2
  • 2.62.1
  • 2.62.0
  • 2.61.0
  • 2.60.0
  • 2.59.0
  • 2.58.0
  • 2.57.0
  • 2.56.0
  • 2.55.1
  • 2.55.0
  • 2.54.0
  • 2.53.0
  • 2.52.0
  • 2.51.0
  • 2.50.1
  • 2.50.0
  • 2.49.0
  • 2.48.0
  • 2.47.0
  • 2.46.0
  • 2.45.0
  • 2.44.0
  • 2.43.0
  • 2.42.0
  • 2.41.0
  • 2.40.1
  • 2.40.0
  • 2.39.0
  • 2.38.1
  • 2.38.0
  • 2.37.0
  • 2.36.0
  • 2.35.0
  • 2.34.0
  • 2.33.1
  • 2.33.0
  • 2.32.0
  • 2.31.0
  • 2.30.1
  • 2.30.0
  • 2.29.0
  • 2.28.0
  • 2.27.0
  • 2.26.0
  • 2.25.0
  • 2.24.0
  • 2.23.0
  • 2.22.0
  • 2.21.0
  • 2.20.1
  • 2.20.0
  • 2.19.2
  • 2.19.1
  • 2.19.0
  • 2.18.0
  • 2.17.0
  • 2.16.0
  • 2.15.0
  • 2.14.0
  • 2.13.0
  • 2.12.0
  • 2.11.0
  • 2.10.0
  • 2.9.0
  • 2.8.0
  • 2.7.0
  • 2.6.0
  • 2.5.0
  • 2.4.0
  • 2.3.1
  • 2.3.0
  • 2.2.1
  • 2.2.0
  • 2.1.0
  • 2.0.0
  • 1.5.5
  • 1.5.0
  • 1.4.0
  • 1.3.1
  • 1.3.0
  • 1.2.1
  • 1.2.0
  • 1.1.0
  • 1.0.0
  • 0.7.7
  • 0.7.6
  • 0.7.5 (deleted)
  • 0.5.0 (deleted)
  • 0.0.1 (deleted)
released May 18th 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x
  • Puppet >= 5.0.0 < 7.0.0
  • , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'sensu-sensu', '3.3.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add sensu-sensu
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install sensu-sensu --version 3.3.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: monitoring, sensu

Documentation

sensu/sensu — version 3.3.0 May 18th 2019

Sensu-Puppet

Table of Contents

  1. Module Description
  2. Setup - The basics of getting started with sensu
  3. Usage - Configuration options and additional functionality
  4. Reference
  5. Limitations - OS compatibility, etc.
  6. Development - Guide for contributing to the module
  7. License

Module description

Installs and manages Sensu, the open source monitoring framework.

Please note, that this is a Partner Supported module, which means that technical customer support for this module is solely provided by Sensu. Puppet does not provide support for any Partner Supported modules. Technical support for this module is provided by Sensu at https://sensuapp.org/support.

Documented with Puppet Strings

Puppet Strings documentation

Compatibility - supported sensu versions

If not explicitly stated it should always support the latest Sensu release. Please log an issue if you identify any incompatibilities.

Sensu Go Version Recommended Puppet Module Version
5.x latest v3

Upgrade note

Sensu Go 5.x is a rewrite of Sensu and no longer depends on redis and rabbitmq. Version 3 of this module supports Sensu Go 5.x.

Users wishing to use the old v2 Puppet module to support previous Ruby based Sensu should use sensu/sensuclassic.

Setup

What sensu effects

This module will install packages, create configuration and start services necessary to manage Sensu agents and backend.

Setup requirements

Plugin sync is required if the custom sensu types and providers are used.

This module has a soft dependency on the puppetlabs/apt module (>= 5.0.1 < 7.0.0) for systems using apt.

If using Puppet >= 6.0.0 there is a soft dependency on the puppetlabs/yumrepo_core module (>= 1.0.1 < 2.0.0) for systems using yum.

If managing Windows there is a soft dependency on the puppet/archive module (>= 3.0.0 < 4.0.0).

Beginning with sensu

This module provides Vagrant definitions that can be used to get started with Sensu.

vagrant up sensu-backend
vagrant ssh sensu-backend

Beginning with a Sensu cluster

Multiple Vagrant boxes are available for testing a sensu-backend cluster.

vagrant up sensu-backend-peer1 sensu-backend-peer2
vagrant provision sensu-backend-peer1 sensu-backend-peer2

Usage

Basic Sensu backend

The following example will configure sensu-backend, sensu-agent on backend and add a check. By default this module will configure the backend to use Puppet's SSL certificate and CA. It's advisable to not rely on the default password. Changing the password requires providing the previous password via old_password.

  class { 'sensu::backend':
    password     => 'supersecret',
    old_password => 'P@ssw0rd!',
  }
  include sensu::agent
  sensu_check { 'check-cpu':
    ensure        => 'present',
    command       => 'check-cpu.sh -w 75 -c 90',
    interval      => 60,
    subscriptions => ['linux'],
  }

Basic Sensu agent

The following example will manage resources necessary to configure a sensu-agent to communicate with a sensu-backend and associated to linux and apache-servers subscriptions.

  class { 'sensu::agent':
    backends    => ['sensu-backend.example.com:8081'],
    config_hash => {
      'subscriptions' => ['linux', 'apache-servers'],
    },
  }

Manage Windows Agent

This module supports Windows Sensu Go agent starting with version 5.7.0.

The Windows package source must be specified as either a URL, a Puppet source or a filesystem path.

Install sensu-go-agent on Windows from URL:

class { 'sensu::agent':
  package_source => 'https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.7.0/sensu-go-agent_5.7.0.2380_en-US.x64.msi',
}

Install sensu-go-agent on Windows from Puppet source:

class { 'sensu::agent':
  package_source => 'puppet:///modules/profile/sensu/sensu-go-agent.msi',
}

If a system already has the necessary MSI present it can be installed without downloading from an URL:

class { 'sensu::agent':
  package_source => 'C:\Temp\sensu-go-agent.msi',
}

Advanced agent

If you wish to change the agent password you must provide the new and old password. It's advisable to set show_diff to false to avoid exposing the agent password.

class { 'sensu::backend':
  agent_password     => 'supersecret',
  agent_old_password => 'P@ssw0rd!',
}
class { 'sensu::agent':
  config_hash => {
    'password' => 'supersecret',
  },
  show_diff   => false,
}

Advanced SSL

By default this module uses Puppet's SSL certificates and CA. If you would prefer to use different certificates override the ssl_ca_source, ssl_cert_source and ssl_key_source parameters. The value for url_host must be valid for the provided certificate and the value used for agent's backends must also match the certificate used by the specified backend. If the certificates and keys are already installed then define the source parameters as filesystem paths.

class { 'sensu':
  ssl_ca_source => 'puppet:///modules/profile/sensu/ca.pem',
}
class { 'sensu::backend':
  url_host        => 'sensu-backend.example.com',
  ssl_cert_source => 'puppet:///modules/profile/sensu/cert.pem',
  ssl_key_source  => 'puppet:///modules/profile/sensu/key.pem',
}

class { 'sensu':
  ssl_ca_source => 'puppet:///modules/profile/sensu/ca.pem',
}
class { 'sensu::agent':
  backends    => ['sensu-backend.example.com:8081'],
  config_hash => {
    'subscriptions' => ['linux', 'apache-servers'],
  },
}

To disable SSL support:

class { 'sensu':
  use_ssl => false,
}

Enterprise Support

In order to activate enterprise support the license file needs to be added:

class { 'sensu::backend':
  license_source => 'puppet:///modules/profile/sensu/license.json',
}

The type sensu_ldap_auth requires a valid enterprise license.

Installing Plugins

Plugin management is handled by the sensu::plugins class.

Example installing plugins on agent:

  class { 'sensu::agent':
    backends    => ['sensu-backend.example.com:8081'],
    config_hash => {
      'subscriptions' => ['linux', 'apache-servers'],
    },
  }
  class { 'sensu::plugins':
    plugins => ['disk-checks'],
  }

The plugins parameter can also be a Hash that sets the version:

  class { 'sensu::agent':
    backends    => ['sensu-backend.example.com:8081'],
    config_hash => {
      'subscriptions' => ['linux', 'apache-servers'],
    },
  }
  class { 'sensu::plugins':
    plugins => {
      'disk-checks' => { 'version' => 'latest' },
    },
  }

Set dependencies to an empty Array to disable the sensu::plugins dependency management.

  class { 'sensu::plugins':
    dependencies => [],
  }

You can uninstall plugins by passing ensure as absent.

  class { 'sensu::agent':
    backends    => ['sensu-backend.example.com:8081'],
    config_hash => {
      'subscriptions' => ['linux', 'apache-servers'],
    },
  }
  class { 'sensu::plugins':
    plugins => {
      'disk-checks' => { 'ensure' => 'absent' },
    },
  }

Installing Extensions

Extension management is handled by the sensu::plugins class.

Example installing extension on backend:

  class { 'sensu::backend':
    password     => 'supersecret',
    old_password => 'P@ssw0rd!',
  }
  class { 'sensu::plugins':
    extensions => ['graphite'],
  }

The extensions parameter can also be a Hash that sets the version:

  class { 'sensu::backend':
    password     => 'supersecret',
    old_password => 'P@ssw0rd!',
  }
  class { 'sensu::plugins':
    extensions => {
      'graphite' => { 'version' => 'latest' },
    },
  }

You can uninstall extensions by passing ensure as absent.

  class { 'sensu::backend':
    password     => 'supersecret',
    old_password => 'P@ssw0rd!',
  }
  class { 'sensu::plugins':
    extensions => {
      'graphite' => { 'ensure' => 'absent' },
    },
  }

Exported resources

One possible approach to defining checks is having agents export their checks to the sensu-backend using Exported Resources.

The following example would be defined for agents:

  @@sensu_check { 'check-cpu':
    ensure        => 'present',
    command       => 'check-cpu.sh -w 75 -c 90',
    interval      => 60,
    subscriptions => ['linux'],
  }

The backend system would collect all sensu_check resources.

  Sensu_check <<||>>

Hiera resources

All the types provided by this module can have their resources defined via Hiera. A type such as sensu_check would be defined via sensu::backend::checks.

The following example adds an asset, filter, handler and checks via Hiera:

sensu::backend::assets:
  sensu-email-handler:
    ensure: present
    url: 'https://github.com/sensu/sensu-email-handler/releases/download/0.1.0/sensu-email-handler_0.1.0_linux_amd64.tar.gz'
    sha512: '755c7a673d94997ab9613ec5969666e808f8b4a8eec1ba998ee7071606c96946ca2947de5189b24ac34a962713d156619453ff7ea43c95dae62bf0fcbe766f2e'
    filters:
      - "entity.system.os == 'linux'"
      - "entity.system.arch == 'amd64'"
sensu::backend::filters:
  hourly:
    ensure: present
    action: allow
    expressions:
      - 'event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0'
sensu::backend::handlers:
  email:
    ensure: present
    type: pipe
    command: "sensu-email-handler -f root@localhost -t user@example.com -s localhost -i"
    timeout: 10
    runtime_assets:
      - sensu-email-handler
    filters:
      - is_incident
      - not_silenced
      - hourly
sensu::backend::checks:
  check-cpu:
    ensure: present
    command: check-cpu.sh -w 75 -c 90
    interval: 60
    subscriptions:
      - linux
    handlers:
      - email
    publish: true
  check-disks:
    ensure: present
    command: "/opt/sensu-plugins-ruby/embedded/bin/check-disk-usage.rb -t '(xfs|ext4)'"
    subscriptions:
      - linux
    handlers:
      - email
    interval: 1800
    publish: true

Resource purging

All the types provided by this module support purging except sensu_config. At this time sensu_asset can not be purged, see Limitations. This example will remove all unmanaged Sensu checks:

resources { 'sensu_check':
  purge => true,
}

Sensu backend cluster

A sensu-backend cluster can be defined for fresh installs by defining the necessary config_hash values. The following examples are using Hiera and assume the sensu::backend class is included.

# data/fqdn/sensu-backend1.example.com.yaml
---
sensu::backend::config_hash:
  etcd-advertise-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-peer-urls: 'http://0.0.0.0:2380'
  etcd-initial-cluster: 'backend1=http://192.168.0.1:2380,backend2=http://192.168.0.2:2380'
  etcd-initial-advertise-peer-urls: "http://%{facts.ipaddress}:2380"
  etcd-initial-cluster-state: 'new'
  etcd-initial-cluster-token: ''
  etcd-name: 'backend1'

# data/fqdn/sensu-backend2.example.com.yaml
---
sensu::backend::config_hash:
  etcd-advertise-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-peer-urls: 'http://0.0.0.0:2380'
  etcd-initial-cluster: 'backend1=http://192.168.0.1:2380,backend2=http://192.168.0.2:2380'
  etcd-initial-advertise-peer-urls: "http://%{facts.ipaddress}:2380"
  etcd-initial-cluster-state: 'new'
  etcd-initial-cluster-token: ''
  etcd-name: 'backend2'

Adding backend members to an existing cluster

Adding new members to an existing cluster requires two steps.

First, add the member to the catalog on one of the existing cluster backends with the sensu_cluster_member type.

sensu_cluster_member { 'backend3':
  peer_urls => ['http://192.168.0.3:2380'],
}

Second, configure and start sensu-backend to interact with the existing cluster. The output from Puppet when a new sensu_cluster_member is applied will print some of the values needed.

# data/fqdn/sensu-backend3.example.com.yaml
---
sensu::backend::config_hash:
  etcd-advertise-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-client-urls: "http://%{facts.ipaddress}:2379"
  etcd-listen-peer-urls: 'http://0.0.0.0:2380'
  etcd-initial-cluster: 'backend1=http://192.168.0.1:2380,backend2=http://192.168.0.2:2380,backend3=http://192.168.0.3:2380'
  etcd-initial-advertise-peer-urls: "http://%{facts.ipaddress}:2380"
  etcd-initial-cluster-state: 'existing'
  etcd-initial-cluster-token: ''
  etcd-name: 'backend3'

The first step will not fully add the node to the cluster until the second step is performed.

Reference

Facts

sensu_agent

The sensu_agent fact returns the Sensu agent version information by the sensu-agent binary.

facter -p sensu_agent
{
  version => "5.1.0",
  build => "b2ea9fcdb21e236e6e9a7de12225a6d90c786c57",
  built => "2018-12-18T21:31:11+0000"
}

sensu_backend

The sensu_backend fact returns the Sensu backend version information by the sensu-backend binary.

facter -p sensu_backend
{
  version => "5.1.0",
  build => "b2ea9fcdb21e236e6e9a7de12225a6d90c786c57",
  built => "2018-12-18T21:31:11+0000"
}

sensuctl

The sensuctl fact returns the sensuctl version information by the sensuctl binary.

facter -p sensuctl
{
  version => "5.1.0",
  build => "b2ea9fcdb21e236e6e9a7de12225a6d90c786c57",
  built => "2018-12-18T21:31:11+0000"
}

Limitations

The Sensu v2 support is designed so that all resources managed by sensuctl are defined on the sensu-backend host. This module does not support adding sensuctl resources on a host other than the sensu-backend host.

The type sensu_asset does not at this time support ensure => absent due to a limitation with sensuctl, see sensu-go#988.

The type sensu_user does not at this time support ensure => absent due to a limitation with sensuctl, see sensu-go#2540.

Notes regarding support

This module is built for use with Puppet versions 5 and 6 and the ruby versions associated with those releases. See .travis.yml for an exact matrix of Puppet releases and ruby versions.

This module targets the latest release of the current major Puppet version and the previous major version. Platform support will be removed when a platform is no longer supported by Puppet, Sensu or the platform maintainer has signaled that it is end of life (EOL).

Though Amazon does not announce end of life (EOL) for its releases, it does encourage you to use the latest releases. This module will support the current release and the previous release. Since AWS does not release Vagrant boxes and the intent of those platforms is to run in AWS, we will not maintain Vagrant systems for local development for Amazon Linux.

Supported Platforms

  • EL 6
  • EL 7
  • Debian 8
  • Debian 9
  • Ubuntu 16.04 LTS
  • Ubuntu 18.04 LTS
  • Amazon 2018.03
  • Amazon 2

Development

See CONTRIBUTING.md

License

See LICENSE file.