[Under Construction] Chef Library Cookbook for The Sensu 2.0 project
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github
libraries
recipes
resources
spec
test
.editorconfig
.gitignore
.kitchen.dokken.yml
.kitchen.yml
.rspec
.rubocop.yml
.travis.yml
Berksfile
CHANGELOG.md
CONTRIBUTING.md
Gemfile
Guardfile
LICENSE
README.md
Rakefile
TESTING.md
chefignore
metadata.rb

README.md

sensu-go

Build Status Cookbook Version Community Slack

[Under Construction] Chef Cookbook for The Sensu Go project

Community

Sensu is discussed in many places but typically the best place to get adhoc general help is through or community slack in #chef channel.

Scope

This Chef Cookbook is for installing & configuring Sensu 2.x See the sensu cookbook if you wish to manage Sensu 1.x via Chef.

Requirements

  • Chef 12.5 or higher.
  • Network accessible package repositories.

Platform Support

The following platforms have been tested with Test Kitchen. It will most likely work on other platforms as well.

Platform Supported Version
0.0.1
centos-6 X
centos-7 X
debian-8 X
debian-9 X
fedora X
ubuntu-14.04 X
ubuntu-16.04 X

Cookbook Dependencies

Usage

This is a library style cookbook that provides a set of resources to install and configure the Sensu 2.x environment in a composable way. It is intended to be used in your own wrapper cookbook suited to your specific needs. You can see a very simple example usage in the default recipe of the sensu_test cookbook that is included in this repo. This recipe is used as part of integration testing.

  • add depends 'sensu-go' to the metadata.rb for your cookbook.
  • use the provided resources in your cookbook
sensu_backend 'default'

sensu_agent 'default'

sensu_ctl 'default' do
  action [:install, :configure]
end

sensu_check 'cron' do
  command '/bin/true'
  cron '@hourly'
  subscriptions %w(dad_jokes production)
  handlers %w(pagerduty email)
  extended_attributes(runbook: 'https://www.xkcd.com/378/')
  publish false
  ttl 100
  high_flap_threshold 60
  low_flap_threshold 20
  subdue(days: { all: [{ begin: '12:00 AM', end: '11:59 PM' },
                       { begin: '11:00 PM', end: '1:00 AM' }] })
  action :create
end

# data bag contains url, checksum for asssets
assets = data_bag_item('sensu', 'assets')
assets.each do |name, property|
  next if name == 'id'
  sensu_asset name do
    url property['url']
    sha512 property['checksum']
  end
end

sensu_handler 'slack' do
  type 'pipe'
  command 'handler-slack --webhook-url https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX --channel monitoring'
end

sensu_filter 'production_filter' do
  filter_action 'allow'
  statements [
    "event.Entity.Environment == 'production'",
  ]
end

sensu_mutator 'example-mutator' do
  command 'example_mutator.rb'
  timeout 60
end

Testing

For more details look at the TESTING.md.

Resource Overview

These resources primarily work by writing the Sensu 2.x object definitions to a local path and then using the sensuctl command line to reconfigure the definitions known to the sensu backend.

  • sensu_backend install and configure the sensu backend
  • sensu_agent install and configure the sensu agent
  • sensu_ctl install and configure the sensuctl
  • sensu_check configure sensu checks
  • sensu_handler configure check handlers
  • sensu_filter configure sensu filters
  • sensu_mutator configure sensu mutators
  • sensu_asset configure sensu assets for use with checks

Resource Details

sensu_backend

The sensu backend resource can configure the core sensu backend service.

Properties

  • version which version to install, default: latest
  • repo which repo to pull package from, default: sensu/nightly
  • config_home where to store the generated object definitions, default: /etc/sensu
  • config a hash of configuration, default: { 'state-dir': '/var/lib/sensu'}

Examples

sensu_backend 'default'

Optionally pass configuration values for the backend:

(insecure example, don't really do this)

sensu_backend 'default' do
  repo 'sensu/beta'
  config({'state-dir' => '/var/lib/sensu',
          'trusted-ca-file' => "/some/local/path.pem",
          'insecure-skip-tls-verify' => true})
end

sensu_agent

The sensu agent resource will install and configure the agent.

Properties

  • version which version to install, default: latest
  • repo which repo to pull package from, default: sensu/nightly
  • config_home where to store the generated object definitions, default: /etc/sensu
  • config a hash of configuration

Examples

sensu_agent 'default'

sensu_ctl

Installs and configures the sensuctl cli

Properties

  • version which version to install, default: latest
  • repo which repo to pull package from, default: sensu/nightly
  • username username for connecting to the sensu backend
  • password password for connecting to the sensu backend
  • backend_url url for the sensu backend, default: http://127.0.0.1:8080

Examples

sensu_ctl 'default'
sensu_ctl 'default' do
  backend_url 'https://sensu.startup.horse'
end

sensu_check

The sensu_check resource is used to define check objects.

Properties

  • config_home default: /etc/sensu
  • check_hooks an array of hook name to run in response to the check
  • command required the check command to execute, default: /bin/true
  • cron a schedule for the check, in cron format or a predefined schedule
  • environment the Sensu RBAC environment that this check belongs to, default: default
  • extended_attributes custom extended attributes to add to the check
  • handlers required an array of handlers to run in response to the check, default: []
  • high_flap_threshold The flap detection high threshold, in percent
  • interval The frequency in seconds the check is executed.
  • low_flap_threshold The flap detection low threshold, in percent
  • organization The Sensu RBAC organization that this check belongs to, default: default
  • proxy_entity_id The check ID, used to create a proxy entity for an external resource
  • proxy_requests A Sensu Proxy Request, representing Sensu entity attributes to match entities in the registry.
  • publish If check requests are published for the check
  • round_robin If the check should be executed in a round robin fashion
  • runtime_assets An array of Sensu assets required at runtime for the execution of the command
  • stdin If the Sensu agent writes JSON serialized entity and check data to the command process' STDIN
  • subdue A Sensu subdue, which is a hash of days of the week
  • subscriptions required an array of Sensu entity subscriptions that check requests will be sent to, default []
  • timeout The check execution duration timeout in seconds
  • ttl The value in seconds until check results are considered stale
  • output_metric_format (optional) the metric format that the output of this check conforms to
  • output_metric_handlers (optional) an array of handlers for output metrics from this check

Examples

sensu_check 'cron' do
  command '/bin/true'
  cron '@hourly'
  subscriptions %w(dad_jokes)
  handlers %w(pagerduty email)
  extended_attributes(runbook: 'https://www.xkcd.com/378/')
  publish false
  ttl 100
  high_flap_threshold 60
  low_flap_threshold 20
  subdue(days: { all: [{ begin: '12:00 AM', end: '11:59 PM' },
                       { begin: '11:00 PM', end: '1:00 AM' }] })
  action :create
end

sensu_handler

Properties

  • command the command to run only allowd if type is pipe
  • env_vars an array of environment variables to use with command execution only allowed if type is pipe
  • environment the Sensu RBAC environment that this check belongs to, default: default
  • filters an array of Sensu event filter names to use
  • handlers an array of Sensu event handler names to use for events
  • mutator mutator to use to mutate event data for the handler
  • organization the Sensu RBAC organization that this check belongs to, default: default
  • socket the socket definition scope, used to configure the TCP/UDP handler socket
  • timeout the handler execution duration timeout in seconds, only used with pipe and tcp types
  • type required handler type, one of pipe, tcp, udp or set

Examples

sensu_handler 'tcp_handler' do
  type 'tcp'
  socket({host: '10.0.1.99',
          port: 4444
         })
  timeout 30
end

sensu_filter

Used to define filters for sensu checks

Properties

  • filter_action required action to take with the event if the filter statements match. One of: allow, deny
  • environment the Sensu RBAC environment that this check belongs to, default: default
  • organization the Sensu RBAC organization that this check belongs to, default: default
  • statements required filter statements to be compared with event data.
  • when the when definition scope, used to determine when a filter is applied with time windows

Examples

sensu_filter 'production_filter' do
  filter_action 'allow'
  statements [
    "event.Entity.Environment == 'production'",
  ]
end
sensu_filter 'state_change_only' do
  filter_action 'allow'
  statements [
    "event.Check.Occurrences == 1"
  ]
end

sensu_mutator

A handler can specify a mutator to transform event data. This resource can define named resources to be used by handlers.

Properties

  • command required the command to run
  • env_vars an array of environment variables to use with command execution
  • environment the Sensu RBAC environment that this check belongs to, default: default
  • organization the Sensu RBAC organization that this check belongs to, default: default
  • timeout the execution duration timeout in seconds

Examples

The following defines a filter that uses a Sensu plugin called example_mutator.rb to modify event data prior to handling the event.

sensu_mutator 'example-mutator' do
  command 'example_mutator.rb'
  timeout 60
end

sensu_asset

At runtime the agent can sequentially fetch assets and store them in its local cache but these must first be defined by name for the sensu backend.

Properties

  • filters a set of filter criteria used by the agent to determine of the asset should be installed.
  • metadata arbitrary information about the asset, in the form of key value pairs.
  • organization the Sensu RBAC organization that this check belongs to, default: default
  • sha512 required the checksum of the asset.
  • url required the URL location of the asset.

Examples

sensu_asset 'asset_example' do
  url 'http://example.com/asset/example.tar'
  sha512 '4f926bf4328fbad2b9cac873d117f771914f4b837c9c85584c38ccf55a3ef3c2e8d154812246e5dda4a87450576b2c58ad9ab40c9e2edc31b288d066b195b21b'
  filters [
    "System.OS==linux"
  ]
end

sensu_organization

An organization is a top-level resource for RBAC, and can contain multiple environemnts. Sensu ships with a default organization.

Properties

  • name required the name of the organization.
  • description a description for the organization.

Examples

sensu_organization 'example_organization do
  description 'example description'
  name 'example'
  action :create
end

sensu_environment

An environment contains a set of resources, and belongs to a single organization.

Properties

  • name required the name of the environment.
  • description a description for the environment.
  • organization required the name of the organization the environment belongs to.

Examples

sensu_environment 'example_environment' do
  description 'example description'
  name 'example'
  organization 'example'
  action :create
end

sensu_entity

An entity is a representation of anything that needs to be monitored. It can be either an agent or a proxy.

Properties

  • subscriptions An array of subscriptions. If no subscriptions are provided, it defaults to an entity-specific subscription list: [entity:{ID}].
  • class_ required the entity type, must be either agent or proxy.
  • organization the name of the organization the entity belongs to, defaults to default
  • environment the name of the environment the entity belongs to, defaults to default

Examples

sensu_entity 'example-entity' do
  subscriptions ['example-entity']
  class_ 'proxy'
end

License & Authors

If you would like to see the detailed LICENSE click here.

Copyright (c) 2018 Sensu

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.