• Stars
    star
    165
  • Rank 228,906 (Top 5 %)
  • Language
    Ruby
  • License
    MIT License
  • Created over 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Sensu Puppet module.

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. Examples
  6. Limitations - OS compatibility, etc.
  7. Development - Guide for contributing to the module
  8. License

Module description

Installs and manages Sensu Go, 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://sensu.io/support.

Documented with Puppet Strings

Puppet Strings documentation

Compatibility - supported Sensu versions

If not explicitly stated it should always support the latest Sensu release. Beginning with v5.0.0 this module will only support Sensu Go 6.0+. Please log an issue if you identify any incompatibilities.

Sensu Go Version Recommended Puppet Module Version
5.0 - 5.15 latest v3
5.16+ latest v4
6.0 v5.0.0
6.1+ v5.1.0+

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.0.0 to < 5.16.0. Version 4 of this module supports Sensu Go >= 5.16.0 < 6.0.0. Version 5.0.0 of this module supports Sensu Go >= 6.0.0 < 6.1.0. Version 5.1.0+ of this module supports Sensu Go >= 6.1.0 < 7.0.0.

Users wishing to use the previous Ruby based Sensu should use the sensu/sensuclassic module.

Updating this module from 4.x to 5.x

This module begins supporting Sensu Go 6 with version >= 5.0.0

NOTE Upgrading to support Sensu Go 6 requires backends have Puppet applied before agents will begin to work as there is an agent specifc Sensu user and role added to support modifying agent entities via the API.

Class parameter changes:

  • Remove deprecated sensu::old_password and sensu::old_agent_password, these parameters are no longer needed and were removed

Type property changes:

  • Remove deprecated url, sha512 and filters properties from sensu_asset, use builds property instead

Changes for backend

There is a manual step to perform to upgrade the sensu-backend after upgrading the backend to 6.x. This module provides the sensu::backend_upgrade bolt task as a way to execute the necessary sensu-backend upgrade command.

Changes for agents

Beginning with Sensu Go 6, some changes to agent.yml will only bootstrap an agent entity, they will not update the entity. If you wish to make changes to values such as subscriptions, labels or annotations after a host is added to Sensu this must be done via the Sensu Go API. To support this it's now required that agents have the ability to make API calls.

In order to ensure agents can make API calls either via API or sensuctl the agent must be told about the admin password and API host:

class { 'sensu':
  api_host                     => 'sensu-backend.example.com',
  agent_entity_config_password => 'supersecret',
}
class { 'sensu::agent':
  ...
}

See API Providers for example Hiera that can be used in a file like common.yaml to easily share the admin password with agents.

This module will still continue to write subscriptions and other agent configurations to agent.yml so that if an agent entity is deleted it can be recreated by restarting the sensu-agent service.

Beginning with Sensu Go 6.2.0 you can go back to making agent.yml the authoritative source for an agent's config by setting sensu::agent::agent_managed_entity to true.

Updating this module from 3.x to 4.x

Class parameter changes:

  • Move sensu::backend::cli_package_name to sensu::cli::package_name
  • Move sensu::backend::sensuctl_chunk_size to sensu::cli::sensuctl_chunk_size
  • Move sensu::backend::url_host to sensu::api_host
  • Move sensu::backend::url_port to sensu::api_port
  • Move sensu::backend::password to sensu::password
  • Move sensu::backend::old_password to sensu::old_password
  • Move sensu::backend::agent_password to sensu::agent_password
  • Move sensu::backend::agent_old_password to sensu::agent_old_password
  • The following parameters were moved from sensu::backend class to sensu::resources class. (Example: sensu::backend::checks becomes sensu::resources::checks)
    • ad_auths
    • assets
    • bonsai_assets
    • checks
    • cluster_members
    • cluster_role_bindings
    • cluster_roles
    • configs (removed)
    • entities
    • etcd_replicators
    • filters
    • handlers
    • hooks
    • ldap_auths
    • mutators
    • namespaces
    • oidc_auths
    • role_bindings
    • roles
    • users

Type property changes:

  • Replace sensu_check proxy_requests* properties with proxy_requests Hash
  • Replace sensu_entity deregistration_handler with deregistration Hash
  • Replace sensu_handler socket_* properties with socket Hash
  • Refactor sensu_ldap_auth and sensu_ad_auth on how properties are defined.
    • Move server_binding, server_group_search and server_user_search into servers property

Breaking changes:

  • Remove sensu_event type, replaced with sensu::event Bolt task
  • Remove sensu_silenced type, replaced with sensu::silenced Bolt task
  • Remove sensu_config type, replaced with sensu::cli::config_format and sensu::cli::config_namespace parameters

Setup

What sensu affects

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.

Soft module dependencies

For systems using apt:

For systems using yum and Puppet >= 6.0.0:

For Windows:

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

Beginning with a Sensu federated cluster

Multiple Vagrant boxes are available for testing a Sensu Go federated cluster. First build and provision both then provision the first a second time to view that the custom role was replicated.

vagrant up sensu-backend-federated1 sensu-backend-federated2
vagrant provision sensu-backend-federated1

The provision command should output from sensuctl the test Sensu Go Role that was created on the other backend. The output should look like the following:

    sensu-backend-federated1:   Name   Namespace   Rules  
    sensu-backend-federated1:  ────── ─────────── ─────── 
    sensu-backend-federated1:   test   default         1  

Usage

Location of Resources

Sensu Go is designed to have resources like checks and assets defined on the backend host. For Puppet this means that the simplest configuration will be one where checks and other resources are defined on the host using sensu::backend class. Hosts with only the sensu::agent class do not need to have checks defined on them, rather just have to have a subscription assigned that matches a check.

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 is advisable to not rely on the default password. NOTE When changing the password value, it's necessary to run Puppet on the backend first to update the admin password.

  class { 'sensu':
    password => 'supersecret',
  }
  include sensu::backend
  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':
    api_host                     => 'sensu-backend.example.com',
    agent_entity_config_password => 'supersecret',
  }
  class { 'sensu::agent':
    backends      => ['sensu-backend.example.com:8081'],
    subscriptions => ['linux', 'apache-servers'],
  }

Basic Sensu CLI

The following example will manage the resources necessary to use sensuctl.

class { 'sensu':
  api_host => 'sensu-backend.example.com',
  password => 'supersecret',
}
include sensu::cli

NOTE: The sensu::backend class calls the sensu::cli class so it is only necessary to directly call the sensu::cli class on hosts not using the sensu::backend class.

For Windows the install_source parameter must be provided:

class { 'sensu':
  api_host => 'sensu-backend.example.com',
  password => 'supersecret',
}
class { 'sensu::cli':
  install_source => 'https://s3-us-west-2.amazonaws.com/sensu.io/sensu-go/5.14.1/sensu-go_5.14.1_windows_amd64.zip',
}

API Providers

All the core resources have a provider that manages resources using the Sensu Go API. The new provider can be used by setting provider parameter on a resource to sensu_api. The default provider is still sensuctl but it's possible to change the provider when defining a resource. For example the following will create a check which can be defined on an host that's not the sensu-backend.

include ::sensu::api
sensu_check { "check-cpu-${facts['hostname']}":
  ensure        => 'present',
  command       => 'check-cpu.sh -w 75 -c 90',
  interval      => 60,
  subscriptions => ["entity:${facts['hostname']}"],
  provider      => 'sensu_api',
}

The sensu::api class is required in order to configure the credentials and URL used to communicate with the Sensu backend API.

The API URL, username and password used for the API are set in the sensu class and can be set easily with Hiera:

sensu::api_host: sensu-backend.example.com
sensu::api_port: 8080
sensu::username: admin
sensu::password: supersecret
sensu::agent_entity_config_password: supersecret

Manage Windows Agent

This module supports Windows Sensu Go agent via chocolatey beginning with version 5.12.0.

class { 'sensu':
  api_host                     => 'sensu-backend.example.com',
  agent_entity_config_password => 'supersecret',
}
class { 'sensu::agent':
  backends      => ['sensu-backend.example.com:8081'],
  subscriptions => ['windows'],
}

If you do not wish to install using chocolatey then you must define package_source as either a URL, a Puppet source or a filesystem path.

Install sensu-go-agent on Windows from URL:

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

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

class { 'sensu::agent':
  package_name   => '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_name   => 'Sensu Agent',
  package_source => 'C:\Temp\sensu-go-agent.msi',
}

Advanced agent

If you wish to have the agent.yml be authoritative for agent entity configs:

class { 'sensu::agent':
  agent_managed_entity  => true,
}

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

class { 'sensu':
  agent_password => 'supersecret',
}
class { 'sensu::agent':
  show_diff => false,
}

The config_hash parameter allows custom configuration for agent.yml outside the sensu::agent class parameters.

class { 'sensu::agent':
  config_hash => {
    'log-level' => 'debug',
  },
}

The following parameters in sensu::agent class are used to populate agent.yml:

  • entity_name - Passed to name key in agent.yml
  • subscriptions
  • annotations
  • labels
  • namespace
  • redact

Agent configurations can also be set via sensu::agent::config_entry. See Advanced agent - Custom config entries.

Advanced agent - Subscriptions

It is possible to define subscriptions in many locations and the values merged into agent.yml:

class { 'sensu::agent':
  subscriptions => ['base'],
}

Then in a profile class for Apache you could define the following:

sensu::agent::subscription { 'apache': }

The resulting agent.yml would contain subscriptions for both base and apache.

NOTE: Subscriptions defined using the sensu::agent class and sensu::agent::subscription are merged to produce the final subscription array.

Advanced agent - Annotations and Labels

It is possible to define annotations and labels in many locations and the values merged into agent.yml:

class { 'sensu::agent':
  labels      => { 'location' => 'uswest', 'contacts' => '[email protected]' },
  annotations => { 'cpu.warning' => '90', 'cpu.critical' => '100' },
}

Then in a profile class you can define the following:

sensu::agent::label { 'contacts': value => '[email protected]' }
sensu::agent::label { 'environment': value => 'dev' }
sensu::agent::annotation { 'cpu.warning': value => '75' }
sensu::agent::annotation { 'fatigue_check/occurrences': value => '2' }

The resulting agent.yml will contain the following:

labels:
  location: uswest
  contacts: [email protected]
  environment: dev
annotations:
  cpu.warning: '75'
  cpu.critical: '100'
  fatigue_check/occurrences: '2'

NOTE sensu::agent::annotation and sensu::agent::label take precedence over values set by the class sensu::agent

If you wish to redact a label or annotation you can use the redact parameter and the key will be added to the redact list in agent.yml:

sensu::agent::label { 'secret':
  value  => 'mysecret',
  redact => true,
}
sensu::agent::annotation { 'ec2_access_key':
  value  => 'some-key',
  redact => true,
}

Advanced agent - Disable validations

In some cases it might be desired to disable API and entity validations when agents are managing their own entity.

class { 'sensu':
  validate_api => false,
}
class { 'sensu::agent':
  agent_managed_entity => true,
  validate_entity      => false,
}

Advanced agent - Custom config entries

It is possible to define config entries for agent.yml in many locations in Puppet:

sensu::agent::config_entry { 'keepalive-interval': value => 20 }

This would add the following to agent.yml:

keepalive-interval: 20

NOTE sensu::agent::config_entry takes precendence over values defined in sensu::agent class.

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 api_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',
  api_host      => 'sensu-backend.example.com',
}
class { 'sensu::backend':
  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'],
  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 types sensu_ad_auth and sensu_ldap_auth require a valid enterprise license.

Contact routing

See Sensu Go - Route alerts with event filters for details. The following is one way to configure contact routing in Puppet.

Add the sensu-go-has-contact-filter bonsai asset:

sensu_bonsai_asset { 'sensu/sensu-go-has-contact-filter':
  ensure  => 'present',
  version => '0.2.0',
}

Add the filters for the defined contacts

sensu_filter { 'contact_dev':
  ensure         => 'present',
  action         => 'allow',
  runtime_assets => ['sensu/sensu-go-has-contact-filter'],
  expressions    => ['has_contact(event, "dev")'],
}
sensu_filter { 'contact_ops':
  ensure         => 'present',
  action         => 'allow',
  runtime_assets => ['sensu/sensu-go-has-contact-filter'],
  expressions    => ['has_contact(event, "ops")'],
}

Add the handlers asset and handlers for each contact

sensu_bonsai_asset { 'sensu/sensu-email-handler':
  ensure  => 'present',
  version => '0.2.0',
}
sensu_handler { 'email_dev':
  ensure          => 'present',
  type            => 'pipe',
  command         => 'sensu-email-handler -f root@localhost -t [email protected] -s localhost -i',
  timeout         => 10,
  runtime_assets  => ['sensu/sensu-email-handler'],
  filters         => ['is_incident','not_silenced','contact_dev'],
}
sensu_handler { 'email_ops':
  ensure          => 'present',
  type            => 'pipe',
  command         => 'sensu-email-handler -f root@localhost -t [email protected] -s localhost -i',
  timeout         => 10,
  runtime_assets  => ['sensu/sensu-email-handler'],
  filters         => ['is_incident','not_silenced','contact_ops'],
}

Create a handler set to centralize handler management for emails

sensu_handler { 'email':
  ensure    => 'present',
  type      => 'set',
  handlers  => ['email_dev','email_ops'],
}

Lastly define a service that use the contact and the email handler:

sensu_check { 'check_cpu':
  ensure         => 'present',
  labels         => {
    'contacts' => 'dev, ops',
  },
  command        => 'check-cpu.rb -w 75 -c 90',
  handlers       => ['email'],
  interval       => 30,
  publish        => true,
  subscriptions  => ['linux'],
  runtime_assets => ['sensu-plugins-cpu-checks','sensu-ruby-runtime'],
}

Agents can also have contacts defined:

class { 'sensu::agent':
  labels => {
    'contacts' => 'dev, ops',
  },
}

PostgreSQL datastore support

NOTE: This features require a valid Sensu Go enterprise license.

The following example will add a PostgreSQL server and database to the sensu-backend host and configure Sensu Go to use PostgreSQL as the event datastore.

class { 'postgresql::globals':
  manage_package_repo => true,
  version             => '11',
}
class { 'postgresql::server': }
class { 'sensu::backend':
  license_source      => 'puppet:///modules/profile/sensu/license.json',
  datastore           => 'postgresql',
  postgresql_password => 'secret',
}

Refer to the puppetlabs/postgresql module documentation for details on how to manage PostgreSQL with Puppet.

The following example uses an external PostgreSQL server.

class { 'sensu::backend':
  license_source       => 'puppet:///modules/profile/sensu/license.json',
  datastore            => 'postgresql',
  postgresql_password  => 'secret',
  postgresql_host      => 'postgresql.example.com',
  manage_postgresql_db => false,
}

NOTE Set postgresql_password to false if you want the DSN to only contain a username.

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'],
    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'],
    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 => [],
  }

If gems are required and not pulled in as gem dependencies they can also be installed.

class { 'sensu::plugins':
  plugins          => ['memory-checks'],
  gem_dependencies => ['vmstat'],
}

You can uninstall plugins by passing ensure as absent.

  class { 'sensu::agent':
    backends      => ['sensu-backend.example.com:8081'],
    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':
    password => 'supersecret',
  }
  include sensu::backend
  class { 'sensu::plugins':
    extensions => ['graphite'],
  }

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

  class { 'sensu':
    password => 'supersecret',
  }
  include sensu::backend
  class { 'sensu::plugins':
    extensions => {
      'graphite' => { 'version' => 'latest' },
    },
  }

You can uninstall extensions by passing ensure as absent.

  class { 'sensu':
    password => 'supersecret',
  }
  include sensu::backend
  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::resources::checks.

The sensu class must be included either directly or via sensu::agent or sensu::backend.

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

sensu::resources::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::resources::filters:
  hourly:
    ensure: present
    action: allow
    expressions:
      - 'event.check.occurrences == 1 || event.check.occurrences % (3600 / event.check.interval) == 0'
sensu::resources::handlers:
  email:
    ensure: present
    type: pipe
    command: "sensu-email-handler -f root@localhost -t [email protected] -s localhost -i"
    timeout: 10
    runtime_assets:
      - sensu-email-handler
    filters:
      - is_incident
      - not_silenced
      - hourly
sensu::resources::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. This example will remove all unmanaged Sensu checks:

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

To selectively purge sensu_agent_entity_config entries, you can specify the type of config to purge. If agent_entity_configs is omitted then all unmanaged sensu_agent_entity_config resources will be purged. The following example will only purge subscriptions:

sensu_resources { 'sensu_agent_entity_config':
  purge                => true,
  agent_entity_configs => ['subscriptions'],
}

NOTE: The Puppet built-in resources can also be used for purging but you must ensure that resources that support namespaces are defined using composite names in the form of $name in $namespace. See Composite Names for Namespaces for details on composite names.

Using the Puppet built-in resources would look like this:

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.

Sensu backend federation

This module supports defining Etcd replicators which allows resources to be sent from one Sensu cluster to another cluster. It is necessary that Etcd be listening on an interface that can be accessed by other Sensu backends. First configure backend Etcd to listen on an interface besides localhost and also use SSL:

class { 'sensu::backend':
  config_hash => {
    'etcd-listen-client-urls'    => "https://0.0.0.0:2379",
    'etcd-advertise-client-urls' => "https://0.0.0.0:2379",
    'etcd-cert-file'             => "/etc/sensu/etcd-ssl/${facts['fqdn'].pem",
    'etcd-key-file'              => "/etc/sensu/etcd-ssl/${facts['fqdn']}-key.pem",
    'etcd-trusted-ca-file'       => "/etc/sensu/etcd-ssl/ca.pem",
    'etcd-client-cert-auth'      => true,
  },
}

Next configure the Etcd replicator on the backend you wish to push resources from. In the following example all defined Role resources will be replicated to the backend at the IP address 192.168.52.30.

sensu_etcd_replicator { 'role_replicator':
  ensure        => 'present',
  ca_cert       => '/etc/sensu/etcd-ssl/ca.pem',
  cert          => '/etc/sensu/etcd-ssl/client.pem',
  key           => '/etc/sensu/etcd-ssl/client-key.pem',
  url           => 'https://192.168.52.30:2379',
  resource_name => 'Role',
}
sensu_role { 'test':
  ensure => 'present',
  rules  => [{'verbs' => ['get','list'], 'resources' => ['checks'], 'resource_names' => ['']}],
}

This module also supports defining a federated cluster:

sensu_cluster_federation { 'us-west-2a':
  ensure   => 'present',
  api_urls => [
    'https://sensu-backend-site1.example.com:8080',
    'https://sensu-backend-site2.example.com:8080',
  ],
}

It is also possible to add a backend to an existing Sensu federated cluster. The following example adds the API URL https://sensu-backend-site3.example.com:8080 to the federated cluster named us-west-2a.

sensu_cluster_federation_member { 'https://sensu-backend-site3.example.com:8080 in us-west-2a':
  ensure => 'present',
}

The above can also be defined using the following example:

sensu_cluster_federation_member { 'https://sensu-backend-site3.example.com:8080':
  ensure  => 'present',
  cluster => 'us-west-2a',
}

Large Environment Considerations

If the backend system has a large number of resources it may be necessary to query resources using chunk size added in Sensu Go 5.8.

class { 'sensu::backend':
  sensuctl_chunk_size => 100,
}

If many thousands of resources such as sensu_check are defined there will be an execution of sensuctl namespace list for each check to validate the namespace exists if the namespace is not defined in Puppet. A similar validation is performed with sensu_api provider. To avoid this extra overhead it may be necessary to disable this validation if you are defining namespaces outside of Puppet.

NOTE: If namespace validation is disabled it's necessary to ensure a namespace is defined in Puppet in order to assign resources to that namespace.

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

Composite Names for Namespaces

All resources that support having a namespace also support a composite name to define the namespace.

For example, the sensu_check with name check-cpu in team1 would be named check-cpu and put into the team1 namespace.

Using composite names is necessary if you wish to have multiple resources with the same name but in different namespaces.

For example to define the same check in two namespaces using the same check name:

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

The example above would add the check-cpu check to both the default and team1 namespaces.

NOTE: If you use composite names for namespaces, the namespace property takes precedence.

Installing Bonsai Assets

Install a bonsai asset. The latest version will be installed but not automatically upgraded.

sensu_bonsai_asset { 'sensu/sensu-pagerduty-handler':
  ensure  => 'present',
}

Install specific version of a bonsai asset.

sensu_bonsai_asset { 'sensu/sensu-pagerduty-handler':
  ensure  => 'present',
  version => '1.2.0',
}

Install latest version of a bonsai asset. Puppet will update the Bonsai asset if a new version is released.

sensu_bonsai_asset { 'sensu/sensu-pagerduty-handler':
  ensure  => 'present',
  version => 'latest',
}

Bolt Tasks

The following Bolt tasks are provided by this Module:

sensu::backend_upgrade: Perform backend upgrade via sensu-backend upgrade command.

Example: bolt task run sensu::backend_upgrade --targets sensu_backend

sensu::agent_event: Create a Sensu Go agent event via the agent API

Example: bolt task run sensu::agent_event name=bolttest status=1 output=test --targets sensu_agent

sensu::apikey: Manage Sensu Go API keys

Example: bolt task run sensu::apikey action=create username=foobar --targets sensu_backend Example: bolt task run sensu::apikey action=list --targets sensu_backend Example: bolt task run sensu::apikey action=delete key=replace-with-uuid-key --targets sensu_backend

sensu::assets_outdated: Retreive outdated Sensu Go assets

Example: bolt task run sensu::assets_outdated --targets sensu_backend

sensu::check_execute: Execute a Sensu Go check

Example: bolt task run sensu::check_execute check=test subscription=entity:sensu_agent --targets sensu_backend

sensu::event.json: Manage Sensu Go events

Example: bolt task run sensu::event action=resolve entity=sensu_agent check=test --targets sensu_backend

Example: bolt task run sensu::event action=delete entity=sensu_agent check=test --targets sensu_backend

sensu::silenced: Manage Sensu Go silencings

Example: bolt task run sensu::silenced action=create subscription=entity:sensu_agent expire_on_resolve=true --targets sensu_backend

Example: bolt task run sensu::silenced action=delete subscription=entity:sensu_agent --targets sensu_backend

sensu::install_agent: Install Sensu Go agent (Windows and Linux)

Example: bolt task run sensu::install_agent backend=sensu_backend:8081 subscription=linux output=true --targets linux

Example: bolt task run sensu::install_agent backend=sensu_backend:8081 subscription=windows output=true --targets windows

Bolt Inventory

This module provides a plugin to populate Bolt v2 inventory targets.

In order to use the sensu inventory plugin the host executing Bolt must have sensuctl configured, see Basic Sensu CLI.

Example of configuring the Bolt inventory with two groups. The linux group pulls Sensu Go entities in the default namespace with the linux subscription. The linux-qa group is the same as linux group but instead pulling entities from the qa namespace.

version: 2
groups:
  - name: linux
    targets:
      - _plugin: sensu
        namespace: default
        subscription: linux
  - name: linux-qa
    targets:
      - _plugin: sensu
        namespace: qa
        subscription: linux

If your entities have more than one network interface it may be necessary to specify the order of interfaces to search when looking for the IP address:

version: 2
groups:
  - name: linux
    targets:
      - _plugin: sensu
        namespace: default
        subscription: linux
        interface_list:
          - eth0
          - eth1

The following rules for interface matching determine the value used for uri.

  1. If interface_list was defined then find first match
  2. If interface_list not defined and only one interface, use that as ipaddress
  3. If interface_list is not defined and more than one interface, use name

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"
}

Examples

Examples can be found in the examples directory.

Limitations

Changing sensu::etc_dir is only supported on systems using systemd.

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

When changing the sensu::password value, it's necessary to run Puppet on the backend first to update the admin password.

Notes regarding support

This module is built for use with Puppet versions 6 and 7 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
  • EL 8
  • Debian 9
  • Debian 10
  • Ubuntu 16.04 LTS
  • Ubuntu 18.04 LTS
  • Ubuntu 20.04 LTS
  • Amazon 2018.03
  • Amazon 2
  • Windows Server 2008 R2
  • Windows Server 2012 R2
  • Windows Server 2016
  • Windows Server 2019

Development

See CONTRIBUTING.md

License

See LICENSE file.

More Repositories

1

sensu

Monitoring for today's infrastructure.
Ruby
2,914
star
2

sensu-go

Simple. Scalable. Multi-cloud monitoring.
Go
1,027
star
3

uchiwa

Uchiwa is a simple yet effective open-source dashboard for the Sensu monitoring framework.
Go
919
star
4

sensu-community-plugins

Sensu community plugins for checks, handlers, & mutators.
468
star
5

sensu-chef

Sensu Chef cookbook.
Ruby
225
star
6

sensu-ansible

An Ansible role to deploy a fully dynamic Sensu stack!
Ruby
126
star
7

sensu-dashboard

A dashboard for Sensu, for displaying & managing events & clients.
CoffeeScript
96
star
8

sensu-admin

An admin webui for Sensu
Ruby
86
star
9

sensu-docs-legacy

[Deprecated] Sensu documentation for versions < 0.29. Note that new docs are close enough to old ones so you should probably visit them instead!
Ruby
48
star
10

sensu-build

Deprecated build tooling for Sensu versions prior to 0.27
Ruby
41
star
11

sensu-docs

Sensu documentation
HTML
41
star
12

sensu-go-ansible

Official Ansible module for Sensu Go
Python
36
star
13

uchiwa-chef

Ruby
33
star
14

web

Open-source Web UI for Sensu Go clusters
TypeScript
30
star
15

sensu-prometheus-collector

Collect Prometheus metrics with Sensu!
Go
28
star
16

sensu-go-workshop

Sensu Go 6 Monitoring as Code workshop.
Shell
22
star
17

grafana-sensu-go-datasource

A Grafana data source plugin for querying the Sensu Go API
TypeScript
22
star
18

sandbox

The place to get started for new Sensu users
Shell
21
star
19

uchiwa-web

Uchiwa is a simple yet effective open-source dashboard for the Sensu monitoring framework.
JavaScript
20
star
20

sensu-influxdb-handler

Sensu Go InfluxDB Metrics Handler
Go
14
star
21

sensu-salt

Your source to use Sensu with SaltStack
14
star
22

sensu-transport

The Sensu transport abstraction library.
Ruby
14
star
23

sensu-k8s-quick-start

Shell
14
star
24

sensu-kube-demo

The Sensu Kubernetes monitoring demo repository.
Shell
13
star
25

sensu-omnibus

Build full-stack platform-specific Sensu packages
Ruby
12
star
26

sensu-go-chef

Chef Library Cookbook for Sensu Go
Ruby
11
star
27

sensu-perf

The Sensu performance testing project.
Shell
11
star
28

sensu-email-handler

Sensu Go Email Handler Plugin
Go
11
star
29

sensu-alpha-documentation

Sensu 2.0 Alpha Documentation and Examples
10
star
30

sensu-slides

Sensu intro slide deck, using ShowOff.
CSS
9
star
31

uchiwa-build

Omnibus build tooling for Uchiwa, a Sensu dashboard.
9
star
32

sensu-settings

The Sensu settings library, loader and validator.
Ruby
9
star
33

sensu-extensions-occurrences

The Sensu Core built-in occurrences filter extension
Ruby
9
star
34

catalog

Monitoring as code for Sensu Go. "There's a template for that!"
Shell
8
star
35

sensu-operator

An operator to manage Sensu 2.0 clusters
Go
8
star
36

sensu-extensions-check-dependencies

Ruby
7
star
37

sensu-plugin-sdk

A framework for creating Sensu plugins
Go
7
star
38

sensu-translator

A CLI tool for translating Sensu 1.x configuration into the Sensu Go format.
Ruby
7
star
39

sensu-flow

Github Action for Sensu flow resource management pattern.
Shell
7
star
40

sensu-go-fatigue-check-filter

An event filter for Sensu Go for managing alert fatigue
JavaScript
6
star
41

sensu-pagerduty-handler

Sensu Go PagerDuty Handler
Go
6
star
42

sensu-aws

Sensu Go AWS Plugins
Go
6
star
43

sensu-plugin-tool

Go
5
star
44

monitoring-plugins

Sensu Assets for the monitoring-plugins.org project
Shell
5
star
45

sensu-admin-chef

Sensu Admin Chef cookbook.
Ruby
5
star
46

sensu-summit-notes

Place to share takeaways from Community Day year over year
5
star
47

snmptrapd2sensu

Convert SNMP traps from Net-SNMP snmptrapd into Sensu Go events via the Sensu Go API.
Go
4
star
48

sensu-go-graphite-handler

Go
4
star
49

sensu-bash

Do not try this at home.
Shell
4
star
50

sensu-go-plugin

Template repo for Sensu Go plugins
Go
4
star
51

sensu-extensions

The Sensu extension loader library.
Ruby
4
star
52

sensu-extension

The Sensu extension library.
Ruby
4
star
53

sensu-go-python

Python client library for Sensu Go
Python
4
star
54

sensu-go-bonsai-asset

Shell
3
star
55

sensu-slack-handler

The Sensu Go Slack handler for notifying a channel.
Go
3
star
56

sensu-ruby-runtime

The Sensu Go Ruby Runtime Asset
Shell
3
star
57

sensu-spawn

The Sensu spawn process library.
Ruby
3
star
58

system-profile-linux

A Sensu plugin for collecting system resource metrics from the procfile system, with the aim to provide a Sensu-native alternative to Collectd's built-in system resource telemetry.
Go
3
star
59

sensu-docker

Official Docker images for the Sensu Go commercial distribution. Visit https://sensu.io/downloads for the latest Sensu Go downloads, including the newest Docker images.
Shell
3
star
60

sensu-remediation-handler

Sensu Go handler for implementing "self healing" workflows
Go
2
star
61

sensu-ruby32-runtime

Shell
2
star
62

homebrew-tap

Sensu Homebrew formulas
Ruby
2
star
63

sensu-logger

The Sensu logger library.
Ruby
2
star
64

check-disk-usage

Go
2
star
65

sensu-omnibus-packer

Shell
2
star
66

sensu-redis

The Sensu Redis client library.
Ruby
2
star
67

check-ntp

Sensu NTP offset check for Linux (ntpd or chrony)
Go
2
star
68

training-vagrant

Shell
2
star
69

http-checks

HTTP checks for use with Sensu
Go
2
star
70

nginx-check

A Sensu check and metrics collector for NGINX
Go
2
star
71

sensu-check-log

The Sensu Go log file monitoring check plugin and asset.
Go
2
star
72

package-deployer

Ruby
2
star
73

sensu-logo

The Sensu logo.
1
star
74

handler-plugin-template

Go
1
star
75

sensu-homebrew

Shell
1
star
76

sensu-core-extensions

1
star
77

sensu-api-tools

API Tools for sensu-go
Go
1
star
78

puppet-module-sensuclassic

Puppet module to manage Sensu Classic (ruby version)
Ruby
1
star
79

sensu-json

The Sensu JSON parser abstraction library.
Ruby
1
star
80

sensu-opcua-checks

Sensu checks for OPC-UA endpoints
Go
1
star
81

docker-buildx-orb

1
star
82

sensu-2.0-migration-workshop

Vagrant/Virtualbox resources for a walk through migrating 1.x sensu core workload to 2.x sensu
Ruby
1
star
83

system-check

Go
1
star
84

sensu-kubernetes-events

Go
1
star
85

sensu-eval-stack

AWS Provisioned Sensu Enterprise Evaluation Stack
Ruby
1
star
86

sensu-timescaledb-handler

Sensu Go TimescaleDB Handler https://sensu.io
Go
1
star
87

sensu-project-status

Simple status overview of Sensu Core projects
HTML
1
star
88

sensu-extensions-debug

The Sensu Core built-in debug handler
Ruby
1
star
89

sensu-1.x-filter-wrapper

Proof-of-concept ruby gRPC extension for wrapping evaluation of sensu 1.x filters in 2.x
Ruby
1
star
90

sensu-data-analysis

Configure Sensu Monitoring Jobs to query data platforms and analyze observability data.
Go
1
star
91

check-memory-usage

Simple cross-platform memory and swap usage checks
Go
1
star
92

core

Core API for sensu-go
Go
1
star
93

sensu-install

The Sensu Ruby Plugin installer
Ruby
1
star
94

sensu-kafka-handler

Sensu handler to send Sensu events to Kafka messages
Go
1
star
95

sensu-ruby26-runtime

Shell
1
star
96

sensu-plugins-omnibus

Ruby
1
star
97

sensu-test-day

Repository for coordinating Sensu Test Day activities. File issues here to report on test day success and failures.
Shell
1
star
98

sensu-cloudwatch-check

AWS Cloudwatch plugin for Sensu Go (including AWS service presets)
Go
1
star
99

awscli-windows-orb

1
star
100

sensu-relay-handler

The Sensu Go Relay handler to relay Events to another Sensu Go installation.
Go
1
star