Skip to content

Commit

Permalink
Merge branch 'main' into enhancement/pager-teams
Browse files Browse the repository at this point in the history
  • Loading branch information
@jspaleta
jspaleta committed Feb 19, 2021
2 parents 22de003 + 5d1e674 commit fbf5bdc
Show file tree
Hide file tree
Showing 5 changed files with 222 additions and 170 deletions.
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,16 @@ Versioning](http://semver.org/spec/v2.0.0.html).

## Unreleased

### Changed
- Updated README for specifying templates in check annotations

## 2.1.0 - 2020-10-29

### Changed
- Made the details a templated item, with the --details-template flag
- Updated to the latest plugin SDK (0.10.1)
- Made summary template its own function to facilitate testing

## [2.0.1] - 2020-05-28

### Changed
Expand Down
286 changes: 130 additions & 156 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,35 @@
<div class=badges>
<a href="https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler">
<img src="https://img.shields.io/badge/Sensu%20PagerDuty%20Handler-Download%20Me-brightgreen.svg?colorB=89C967&logo=sensu" alt="Bonsai Asset Badge">
</a>
<a href="https://github.com/sensu/sensu-pagerduty-handler/actions?query=workflow%3A%22Go+Test%22">
<img src="https://github.com/sensu/sensu-pagerduty-handler/workflows/Go%20Test/badge.svg" alt="Go Test Actions Workflow">
</a>
<a href="https://github.com/sensu/sensu-pagerduty-handler/actions?query=workflow%3Agoreleaser">
<img src="https://github.com/sensu/sensu-pagerduty-handler/workflows/goreleaser/badge.svg" alt="Goreleaser Actions Workflow">
</a>
</div>
# Sensu PagerDuty Handler

[![Bonsai Asset Badge](https://img.shields.io/badge/Sensu%20PagerDuty%20Handler-Download%20Me-brightgreen.svg?colorB=89C967&logo=sensu)](https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler)
![Go Test](https://github.com/sensu/sensu-pagerduty-handler/workflows/Go%20Test/badge.svg)
![goreleaser](https://github.com/sensu/sensu-pagerduty-handler/workflows/goreleaser/badge.svg)

# Sensu PagerDuty Handler

## Table of Contents
- [Overview](#overview)
- [Quick start](#quick-start)
- [Usage](#usage)
- [Usage examples](#usage-examples)
- [Help](#help)
- [Environment variables](#environment-variables)
- [Event-based templating](#event-based-templating)
- [Argument annotations](#argument-annotations)
- [Proxy support](#proxy-support)
- [Deduplication key](#deduplication-key)
- [PagerDuty severity mapping](#pagerduty-severity-mapping)
- [Deduplication Key](#deduplication-key)
- [PagerDuty Severity Mapping](#pagerduty-severity-mapping)
- [Configuration](#configuration)
- [Asset registration](#asset-registration)
- [Asset definition](#asset-definition)
- [Handler definition](#handler-definition)
- [Install from source](#install-from-source)
- [Contribute](#contribute)
- [Environment Variables](#environment-variables)
- [Argument Annotations](#argument-annotations)
- [Proxy support](#proxy-support)
- [Installation from source](#installation-from-source)
- [Contributing](#contributing)

## Overview

The Sensu PagerDuty Handler is a [Sensu event handler][3] that manages [PagerDuty][2] incidents for alerting operators.
With this handler, [Sensu][1] can trigger and resolve PagerDuty incidents.

## Quick start

We recommend installing the Sensu PagerDuty Handler plugin via the [monitoring-pipelines PagerDuty template](https://github.com/sensu-community/monitoring-pipelines/blob/master/incident-management/pagerduty.yaml).
The template includes additional template-specific instructions, Sensu resource definitions for the handler, the versioned asset you will need, and information about supported options.
Make sure to read the template's inline comments for template-specific instructions and edit the template to match your configuration before you install it with `sensuctl create`.

**NOTE**: The monitoring-pipelines and monitoring-checks templates use specially defined handler sets by default.
For more information about how these templates work, read the [monitoring pipelines readme](https://github.com/sensu-community/monitoring-pipelines/blob/master/README.md).
The Sensu PagerDuty Handler is a [Sensu Event Handler][3] which manages
[PagerDuty][2] incidents, for alerting operators. With this handler,
[Sensu][1] can trigger and resolve PagerDuty incidents.

## Usage
## Usage Examples

### Help

```
The Sensu Go PagerDuty handler for incident management
Expand All @@ -70,84 +52,19 @@ Use "sensu-pagerduty-handler [command] --help" for more information about a comm
```

### Environment variables

You can set most arguments for the Sensu PagerDuty Handler via environment variables.
However, any arguments specified directly on the command line will override the corresponding environment variable.

|Argument |Environment Variable |
|--------------------|------------------------------|
|--token |`PAGERDUTY_TOKEN` |
|--dedup-key-template|`PAGERDUTY_DEDUP_KEY_TEMPLATE`|
|--summary-template |`PAGERDUTY_SUMMARY_TEMPLATE` |
|--status-map |`PAGERDUTY_STATUS_MAP` |

**IMPORTANT**: Take care to avoid exposing the handler authentication token by specifying it on the command line or directly setting the `PAGERDUTY_TOKEN`
environment variable in the handler definition.
Consider using [secrets management][8] to surface the token as an environment variable as shown in the [handler definition][10].

To use Sensu's built-in [env secrets provider][9] to set the `PAGERDUTY_TOKEN` environment variable:

```yml
---
type: Secret
api_version: secrets/v1
metadata:
name: pagerduty_token
spec:
provider: env
id: PAGERDUTY_TOKEN
```
### Event-based templating
The Sensu Pagerduty Handler supports templating based on event data via the `--dedup-key-template` and `--summary-template` arguments.
Read [Create handler templates](https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-process/handler-templates/) for more information about event-based templating.

### Argument annotations

You can tune all arguments for the Sensu PagerDuty Handler on a per entity or per check basis based on annotations.
The annotations keyspace for the handler is `sensu.io/plugins/sensu-pagerduty-handler/config`.

#### Annotation example

To change the token argument for a particular check, add this annotation to the checks's metadata:

```yml
type: CheckConfig
api_version: core/v2
metadata:
annotations:
sensu.io/plugins/sensu-pagerduty-handler/config/token: abcde12345fabcd67890efabc12345de
[...]
```

### Proxy support

The Sensu PagerDuty Handler supports the environment variables `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (or the lowercase versions thereof).
`HTTPS_PROXY` takes precedence over `HTTP_PROXY` for HTTPS requests.

The environment values may be a complete URL or a "host[:port]".
If you use a "host[:port]", the "http" scheme is assumed.
### Deduplication Key

### Deduplication key
The deduplication key is determined via the `--dedup-key-template` argument. It
is a Golang template containing the event values and defaults to
`{{.Entity.Name}}-{{.Check.Name}}`.

The deduplication key is determined via the `--dedup-key-template` argument.
The key is a Golang template that contains the event values and defaults to `{{.Entity.Name}}-{{.Check.Name}}`.
### PagerDuty Severity Mapping

### PagerDuty severity mapping

If you wish, you can provide mapping information between the Sensu check status and the PagerDuty incident severity.
To do this, use the `--status-map` command line option or the `PAGERDUTY_STATUS_MAP` environment variable.

The valid [PagerDuty alert severity levels][5] are:
* `info`
* `warning`
* `critical`
* `error`

Use a JSON document to provide the mapping information.
For example:
Optionally you can provide mapping information between the Sensu check status
and the PagerDuty incident severity. To provide the mapping you need to use the
`--status-map` command line option or the `PAGERDUTY_STATUS_MAP` environment
variable. The option accepts a JSON document containing the mapping
information. Here's an example of the JSON document:

```json
{
Expand All @@ -173,47 +90,28 @@ For example:
}
```

## Configuration

**NOTE**: If you use the [monitoring-pipelines PagerDuty template][11], the template provides the asset and handler resource definitions you need.
Read the inline comments in the template for information about template configuration options.

### Asset registration
The valid [PagerDuty alert severity levels][5] are the following:
* `info`
* `warning`
* `critical`
* `error`

[Sensu assets][6] are the best way to install and use this plugin.
If you're not using an asset, please consider doing so!
## Configuration
### Sensu Go
#### Asset registration

If you're using sensuctl 5.13 with Sensu backend 5.13 or later, you can use the following command to add the asset:
[Sensu Assets][6] are the best way to make use of this plugin. If you're not
using an asset, please consider doing so! If you're using sensuctl 5.13 with
Sensu Backend 5.13 or later, you can use the following command to add the asset:

```
sensuctl asset add sensu/sensu-pagerduty-handler
```

If you're using an earlier version of sensuctl, you can find the asset on [Bonsai, the Sensu asset index][7].

### Asset definition

This is an example of a manually created asset definition:

```yml
---
type: Asset
api_version: core/v2
metadata:
name: sensu-pagerduty-handler_linux_amd64
spec:
url: https://assets.bonsai.sensu.io/e930fc9c21b835896216ca4594c7990111b54630/sensu-pagerduty-handler_2.0.1_linux_amd64.tar.gz
sha512: 6d499ae6edeb910eb807abfb141be3b9a72951911f804d5a7cc98fbbea15dc4cc6c456f1663124c1db51111c8fd42dab39d1d093356e555785f21ef5f95ffb06
filters:
- entity.system.os == 'linux'
- entity.system.arch == 'amd64'
```

You can use this definition with `sensu create` to register a version of this asset without using the Bonsai integration.

### Handler definition
If you're using an earlier version of sensuctl, you can find the asset on the
[Bonsai Asset Index][7].

This is an example of a manually created handler definition:
#### Handler definition

```yml
---
Expand All @@ -235,29 +133,105 @@ spec:
secret: pagerduty_authtoken
```
## Install from source
#### Environment Variables
Download the latest version of the sensu-pagerduty-handler from [releases][4] or create an executable from this source.
Most arguments for this handler are available to be set via environment
variables. However, any arguments specified directly on the command line
override the corresponding environment variable.
From the local path of the sensu-pagerduty-handler repository, run:
|Argument |Environment Variable |
|--------------------|----------------------------|
|--token |PAGERDUTY_TOKEN |
|--summary-template |PAGERDUTY_SUMMARY_TEMPLATE |
|--dedup-key-template|PAGERDUTY_DEDUP_KEY_TEMPLATE|
|--status-map |PAGERDUTY_STATUS_MAP |
**Security Note:** Care should be taken to not expose the auth token for this
handler by specifying it on the command line or by directly setting the
environment variable in the handler definition. It is suggested to make use of
[secrets management][8] to surface it as an environment variable. The handler
definition above references it as a secret. Below is an example secrets
definition that make use of the built-in [env secrets provider][9].
```yml
---
type: Secret
api_version: secrets/v1
metadata:
name: pagerduty_token
spec:
provider: env
id: PAGERDUTY_TOKEN
```
go build -o /usr/local/bin/sensu-pagerduty-handler
#### Argument Annotations
All arguments for this handler are tunable on a per entity or check basis based
on annotations. The annotations keyspace for this handler is
`sensu.io/plugins/sensu-pagerduty-handler/config`.

**NOTE**: Due to [check token substituion][10], supplying a template value such
as for `details-template` as a check annotation requires that you place the
desired template as a [golang string literal][11] (enlcosed in backticks)
within another template definition. This does not apply to entity annotations.

###### Examples

To change the `--details-template` argument for a particular check, and taking
into account the note above regarding templates, for that check's metadata add
the following:

```yml
type: CheckConfig
api_version: core/v2
metadata:
annotations:
sensu.io/plugins/sensu-pagerduty-handler/config/details-template: "{{`{{.Check.Output}}`}}"
[...]
```

## Contribute
To change the `--token` argument for a particular check, for that checks's metadata
add the following:

```yml
type: CheckConfig
api_version: core/v2
metadata:
annotations:
sensu.io/plugins/sensu-pagerduty-handler/config/token: abcde12345fabcd67890efabc12345de
[...]
```

#### Proxy Support

This handler supports the use of the environment variables HTTP_PROXY,
HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). HTTPS_PROXY takes
precedence over HTTP_PROXY for https requests. The environment values may be
either a complete URL or a "host[:port]", in which case the "http" scheme is
assumed.

## Installation from source

Download the latest version of the sensu-pagerduty-handler from [releases][4],
or create an executable script from this source.

From the local path of the sensu-pagerduty-handler repository:
```
go build -o /usr/local/bin/sensu-pagerduty-handler
```

See https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md to contribute to this project.
## Contributing

See https://github.com/sensu/sensu-go/blob/master/CONTRIBUTING.md

[1]: https://github.com/sensu/sensu-go
[2]: https://www.pagerduty.com/
[3]: https://docs.sensu.io/sensu-go/5.0/reference/handlers/
[3]: https://docs.sensu.io/sensu-go/5.0/reference/handlers/#how-do-sensu-handlers-work
[4]: https://github.com/sensu/sensu-pagerduty-handler/releases
[5]: https://support.pagerduty.com/docs/dynamic-notifications#section-eventalert-severity-levels
[6]: https://docs.sensu.io/sensu-go/latest/operations/deploy-sensu/assets/
[7]: https://bonsai.sensu.io/assets/sensu/sensu-pagerduty-handler
[8]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets-management/
[9]: https://docs.sensu.io/sensu-go/latest/operations/manage-secrets/secrets-management/#use-env-for-secrets-management
[10]: #handler-definition
[11]: https://github.com/sensu-community/monitoring-pipelines/blob/master/incident-management/pagerduty.yaml
[6]: https://docs.sensu.io/sensu-go/latest/reference/assets/
[7]: https://bonsai.sensu.io/sensu/sensu-pagerduty-handler
[8]: https://docs.sensu.io/sensu-go/latest/guides/secrets-management/
[9]: https://docs.sensu.io/sensu-go/latest/guides/secrets-management/#use-env-for-secrets-management
[10]: https://docs.sensu.io/sensu-go/latest/observability-pipeline/observe-schedule/checks/#check-token-substitution
[11]: https://golang.org/ref/spec#String_literals
Loading

0 comments on commit fbf5bdc

Please sign in to comment.