search

sensu / sensu-go-chef

Chef Library Cookbook for Sensu Go
https://sensu.io
MIT License
11 stars 22 forks source link

readme

sensu-go

CI State Build Status Build Status Cookbook Version Community Slack License

[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 5.x See the sensu cookbook if you wish to manage Sensu 1.x via Chef.

Requirements

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
amazonlinux X
amazonlinux-2 X
centos-6 X
centos-7 X
fedora X
ubuntu-16.04 X
ubuntu-18.04 X
ubuntu-20.04 X
windows-2012r2 Agent Only
windows-2016 Agent Only
windows-2019 Agent Only

Cookbook Dependencies

Usage

This is a library style cookbook that provides a set of resources to install and configure the Sensu 5.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.

sensu_backend 'default' do
  action [:install, :init]
end

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)
  annotations(runbook: 'https://www.xkcd.com/378/')
  publish false
  ttl 100
  high_flap_threshold 60
  low_flap_threshold 20
  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'
  expressions [
    "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 5.x object definitions to a local path and then using the sensuctl command line to reconfigure the definitions known to the sensu backend.

Resource Details

Common properties

Sensu resources that support metadata attributes share these common properties:

name metadata will be set automatically from the resource name

sensu_backend

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

Properties

Examples

sensu_backend 'default'

For using packages built from source:

sensu_backend 'default' do
  distribution 'source'
  repo 'https://my-custom-repo.com/yum/$releasever/$basearch/'
end

Optionally pass configuration values for the backend:

(insecure example, don't really do this)
sensu_backend 'default' do
  repo 'sensu/stable'
  config({'state-dir' => '/var/lib/sensu/sensu-backend',
          '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. As of Sensu Go 6.0.0, it is no longer possible to update an existing agent configuration with this resource, and an agent entity should be made via sensu_entity. NOTE: windows agent install is pinned to version 5.10 until available in a consumable package format (likely chocolately)

Properties

Examples

sensu_agent 'default'
(insecure example, don't really do this)
sensu_agent 'default' do
  config(
    "name": node['fqdn'],
    "namespace": "default",
    "backend-url": ["wss://sensu-backend.example.com:8081"],
    "insecure-skip-tls-verify": true,
    "subscriptions": ["centos", "haproxy"],
    "labels": {
      "app_id": "mycoolapp",
      "app_tier": "loadbalancer"
    },
    "annotations": {
      "color": "green"
    }
  )
end

sensu_ctl

Installs and configures the sensuctl cli

Properties

Examples

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

Migrating on Windows from version 1.3.0 or earlier of this cookbook to a later version.

sensuctl 'default' do
  action [:cleanup_legacy_cookbook_install, :install]
  version '6.1.0.3465'
end

sensu_check

The sensu_check resource is used to define check objects.

Properties

Examples

sensu_check 'cron' do
  command '/bin/true'
  cron '@hourly'
  subscriptions %w(dad_jokes)
  handlers %w(pagerduty email)
  annotations(runbook: 'https://www.xkcd.com/378/')
  publish false
  ttl 100
  secrets [{ "name": "AGGREGATE_USER_KEY", "secret": 'sensu-aggregate-key'}]
  high_flap_threshold 60
  low_flap_threshold 20
  action :create
end

# Since this is a ruby based script, the check below defines two runtime_assets.
# One is the ruby-runtime asset, the other is the actual disk usage asset
sensu_check 'disk' do
  command 'check-disk-usage.rb -t xfs -w 95 -c 99'
  interval 60
  subscriptions %w(linux)
  handlers %w(pagerduty splunk)
  publish true
  ttl 100
  runtime_assets ['sensu-ruby-runtime', 'sensu-plugins-disk-checks']
  action :create
end

sensu_handler

Properties

Examples

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

sensu_hook

Used to define hooks for sensu checks

Properties

Examples

sensu_hook 'restart_nginx' do
  command 'sudo systemctl start nginx'
  timeout 60,
  stdin false
end
sensu_hook 'process_tree' do
  command 'ps aux'
  timeout 60,
  stdin false
end

sensu_filter

Used to define filters for sensu checks

Properties

Examples

sensu_filter 'production_filter' do
  filter_action 'allow'
  expressions [
    "event.Entity.Environment == 'production'",
  ]
end
sensu_filter 'state_change_only' do
  filter_action 'allow'
  expressions [
    "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

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

Examples

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

sensu_namespace

A Namespace partitions resources within Sensu, this replaces organizations/environments. The resource name is the namespace name.

Examples

sensu_namespace 'example_namespace' do
  action :create
end

sensu_entity

An entity is a representation of anything that needs to be monitored. From Sensu Go 6.0.0 onward, updates of an existing agent entity's subscriptions, labels, annotations, and attributes should be done via this resource, as updating via sensu_agent will be ignored.

Properties

Examples

This example assumes that you've designed your proxy check to look for subscriptions (e.g., "entity.subscriptions.indexOf('hypervisor') >= 0" for the proxy_requests' entity_attributes).

sensu_entity 'example-hypervisor-entity' do
  entity_class 'proxy'
  subscriptions ['hypervisor']
  redact ['snmp_community_string']
  system(
    'hostname': 'example-hypervisor',
    'platform': 'Citrix Hypervisor',
    'platform_version': '8.1.0',
    'network': {
      'interfaces': [
        {
          'name': 'lo',
          'addresses': ['127.0.0.1/8'],
        },
        {
          'name': 'xapi0',
          'mac': '52:54:00:20:1b:3c',
          'addresses': ['172.0.1.72/24'],
        },
      ],
    },
  )
end

This example provides a proxy check for the label where proxy_requests entity_attributes matches "entity.labels.proxy_type == 'website'". You must define both the entity and the check in your chef recipe.

Define the entity resource:

sensu_entity 'example-website-entity' do
  entity_class 'proxy'
  labels (
    'proxy_type': 'website',
    'url': 'https://my-website-url.com'
  )
end

And define the corresponding proxy check resource:

sensu_check 'proxy_check_proxy_requests' do
  proxy_entity_name 'example-website-entity'
  proxy_requests(entity_attributes: [ "entity.labels.proxy_type == 'website'"])
  subscriptions %w(proxy)
  handlers %w(pagerduty email)
  command 'http_check.sh {{ .labels.url }}'
  interval 60
  publish true
  action :create
end

Note that this check uses token substitution so the command must be in single quotes.

Consult the proxy check section of the checks reference documentation for further details.

sensu_role

The combination of Roles and RoleBindings grant users and groups permissions to resources within a namespace. Roles describe which resources and verbs a subject has access to.

Properties

sensu_role_binding

The combination of Roles and RoleBindings grant users and groups permissions to resources within a namespace. RoleBindings describe the association of a role with one or more subjects.

Properties

See Role binding and Cluster Role binding specification for additional details.

sensu_cluster_role

The combination of ClusterRoles and ClusterRoleBindings grant users and groups permissions to resources across all namespaces. ClusterRoles describe which resources and verbs a subject has access to.

Properties

sensu_cluster_role_binding

The combination of ClusterRoles and ClusterRoleBindings grant users and groups permissions to resources within a namespace. ClusterRoleBindings describe the association of a role with one or more subjects.

Properties

sensu_postgres_config

Configure Sensu to store events in a PostgreSQL database.

Properties

See PostgreSQL docs for more information about connection strings.

Examples

sensu_postgres_config 'default' do
    dsn "postgresql://sensu:pgtesting123@127.0.0.1:5432/sensu_events?sslmode=disable"
    pool_size 10
end

sensu_active_directory

An active directory configuration to be applied to Sensu Go (commercial feature).

Properties

Examples

sensu_active_directory 'active_directory' do
  servers [{
    'host': '127.0.0.1',
    'group_search': {
      'base_dn': 'dc=acme,dc=org',
    },
    'user_search': {
      'base_dn': 'dc=acme,dc=org',
    },
  }]
end

sensu_auth_oidc

An OIDC configuration applied to Sensu Go (commercial feature). Configuring OIDC is beyond the scope of this document, consult the sensu documentation for OpenID Connect authentication and for Registering an OIDC application

Examples

sensu_auth_oidc 'fake_okta' do
  additional_scopes ["groups", "email"]
  client_id "a8e43af034e7f2608780"
  # Demo only! The client secret value should come from somewhere like chef-vault
  client_secret "b63968394be6ed2edb61c93847ee792f31bf6216"
  redirect_uri "http://sensu-backend.example.com:8080/api/enterprise/authentication/v2/oidc/callback"
  server "https://oidc.example.com:9031"
end

sensu_auth_ldap

An ldap configuration to be applied to Sensu Go (commercial feature).

Properties

Examples

sensu_auth_ldap 'openldap' do
  servers [{
    'host': '127.0.0.1',
    'group_search': {
      'base_dn': 'dc=acme,dc=org',
      'attribute': 'member'
      'object_class': 'groupOfNames'
    },
    'user_search': {
      'base_dn': 'dc=acme,dc=org',
      'attribute': 'uid',
      'name_attribute': 'cn',
      'object_class': 'person'
    },
  }]
end

sensu_secret

Create a secret that Sensu can grab from a secret provider so that sensitive information is not exposed (commercial feature).

Properties

Examples

Environment secret referencing the environment variable CONSUL_TOKEN on the backend server:

sensu_secret 'sensu-consul-token' do
  id 'CONSUL_TOKEN'
  secrets_provider 'env'
end

Vault secret referencing the key token at the path secret/consul:

sensu_secret 'sensu-consul-token' do
  id 'secret/consul#token'
  secrets_provider 'vault'
end

sensu_secrets_provider

Create a secret provider for Sensu to connect to for secrets (commercial feature). Currently supports only Vault integration or Sensu Go's built-in secrets provider.

Either a token or a TLS hash must be provided.

Properties

Examples

Minimal with token:

sensu_secrets_provider 'vault' do
  address 'https://vaultserver.example.com:8200'
end
  provider_type 'VaultProvider'
  token 'yourVaultToken'

Complete with TLS:

sensu_secrets_provider 'vault' do
  address 'https://vaultserver.example.com:8200'
  max_retries 2
  provider_type 'VaultProvider'
  rate_limiter(
    'limit': 10,
    'burst': 100
  )
  tls('ca_cert': '/path/to/your/ca.pem',
      'client_cert': '/path/to/backend/pem/for/vault.pem',
      'client_key': '/path/to/backend/key/for/vault.pem',
      'cname': 'sensu-backend.example.com'
     )
  timeout '60s'
  version 'v2'
end

sensu_etcd_replicator

Etcd replicators allow you to manage RBAC resources in one place and mirror the changes to follower clusters. This resource allows you to set up etcd mirrors for one-way key replication (commercial feature).

Properties

Examples

sensu_etcd_replicator 'insecure_role_replicator' do
  insecure true # NOTE: Disable transport security with care.
  url 'http://127.0.0.1:2379'
  resource 'Role'
end

sensu_etcd_replicator 'role_replicator' do
  cert '/etc/ssl/fake.pem'
  key '/etc/ssl/fake.key'
  url 'http://127.0.0.1:2379'
  resource 'Role'
end

sensu_etcd_replicator 'role_binding_replicator' do
  cert '/etc/ssl/fake.pem'
  key '/etc/ssl/fake.key'
  url 'http://127.0.0.1:2379'
  resource 'RoleBinding'
end

sensu_search

Create a save search that can be used in the Sensu web interface (commercial feature).

Properties

Examples

sensu_search 'check-config' do
  parameters [
      "published:true",
      "subscription:linux",
      "labelSelector: region == \"us-west-1\""
  ]
  resource 'core.v2/CheckConfig'
end

sensu_global_config

Web UI configuration allows you to define certain display options for the Sensu web UI, such as which web UI theme to use, the number of items to list on each page, and which URLs and linked images to expand. You can define a single custom web UI configuration to federate to all, some, or only one of your clusters (commercial feature).

Properties

Examples

sensu_global_config 'custom-web-ui' do
  default_preferences(page_size: 50,
                      theme: "deuteranopia")
  link_policy(allow_list: true,
              urls: [
                "https://example.com",
                "steamapp://34234234",
                "//google.com",
                "//*.google.com",
                "//bob.local"
              ])
end

sensu_tessen_config

Tessen sends anonymized data about Sensu instances to Sensu Inc., including the version, cluster size, number of events processed, and number of resources created. This resource allows users to control their preference for cluster analytics collection.

This does not affect licensed Sensu instances since Tessen is enabled by default and required in those cases.

Properties

Examples

sensu_tessen_config 'default' do
  opt_out true
end

sensu_user

Manage non SSO sensu users. This resource requires a bcrypt password hash, you can use sensuctl user hash-password to generate one.

Properties

Examples

# Disable someone who had their password exposed
sensu_user 'doofus' do
  password_hash '$2y$12$OrEQ61blxyTFi3PJHeJ94ej/Z857eSAnAdlSD4Kn7ywItTLrzTqVy'
  groups %w(view admin managers)
  disabled true
end

# Add a user with only view rights.
sensu_user 'reinstated' do
  password_hash '$2y$12$yga83H/KqKFKDYnLogQ6CeN3xrFmhVwMdVkh.hRPX/BhF2NJfYq8O'
  groups %w(view)
end

License & Authors

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

Copyright (c) 2020 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.