Merge pull request #47 from sensu/contact-routing

Add support for basic contact routing

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v1
         with:
-          go-version: 1.14.x
+          go-version: 1.18.x
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v1
         with:

.github/workflows/test.yml

@@ -12,10 +12,10 @@ jobs:
     steps:
     - name: Checkout code
       uses: actions/checkout@v2
-    - name: Set up Go 1.14
+    - name: Set up Go 1.18
       uses: actions/setup-go@v1
       with:
-        go-version: 1.14
+        go-version: 1.18.x
       id: go
     - name: Test
       run: go test -v ./...

CHANGELOG.md

@@ -7,7 +7,11 @@ Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+- Add new `--contact-routing` mode for sending multiple Pagerduty updates, one per configured contact
+- Updated the README with more details on `--contact-routing`
+
 ## 2.2.1 - 2021-03-15
+
 ### Changed
 - Add additional logging to help troubleshoot pager team annotations
 

README.md

@@ -42,6 +42,7 @@ Available Commands:
   version     Print the version number of this plugin
 
 Flags:
+      --contact-routing             Enable contact routing
   -k, --dedup-key-template string   The PagerDuty V2 API deduplication key template, can be set with PAGERDUTY_DEDUP_KEY_TEMPLATE (default "{{.Entity.Name}}-{{.Check.Name}}")
   -d, --details-template string     The template for the alert details, can be set with PAGERDUTY_DETAILS_TEMPLATE (default full event JSON)
   -h, --help                        help for sensu-pagerduty-handler
@@ -217,7 +218,7 @@ metadata:
 
 ### Pager teams
 
-Instead of specifying the authentication token directly in the check or agent annotations, you can instead reference a pager team name, which will then be used to lookup the corresponding token from the handler environment. 
+Instead of specifying the authentication token directly in the check or agent annotations, you can instead reference a pager team name, which will then be used to lookup the corresponding token from the handler environment.
 Corresponding pager team token environment variables can be populated in the handler environment in 3 different ways
 1. Explicitly set in the handler definition
 2. Kept as Sensu [secrets][13] and referenced in the handler definition
@@ -234,15 +235,16 @@ First set the team annotation in the check or agent resource.
 ###### Check Snippet:
 ```
 ---
-type: CheckConfig 
-api_version: core/v2 
-metadata: 
-  name: example-check 
-  annotations: 
+type: CheckConfig
+api_version: core/v2
+metadata:
+  name: example-check
+  annotations:
     sensu.io/plugins/sensu-pagerduty-handler/config/team: team_1
 ```
 
 And define the corresponding evironment variable for the pager team's token in the handler's environment.
+
 ###### Handler Snippet:
 ```
 ---
@@ -267,11 +269,72 @@ spec:
   secrets:
   - name: PAGERDUTY_TOKEN
     secret: pagerduty_authtoken
-  env_vars: 
+  env_vars:
   - team_1_pagerduty_token="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-  
+
 ```
 
+### Contact Routing
+
+The Sensu Pagerduty Handler provides support for generating one Pagerduty event per "contact" via the `--contact-routing` flag.
+
+With `--contact-routing` enabled, the Sensu Pagerduty Handler will do the following:
+
+* Check for and merge the entity, check, and/or event `contacts` annotation.
+
+  The `contacts` annotation supports a comma-separated list of contact names containing alpha-numeric characters and underscore (`_`) characters only.
+
+  Example:
+
+  ```
+  annotations:
+    contacts: "team_a,team_b"
+  ```
+
+  _NOTE: when `--contact-routing` is enabled, the handler will log a message like `Pagerduty contact routing is enabled (contacts: team_a, team_b)`.
+  If `--contact-routing` is enabled and no `contacts` annotations are found, the handler will log an error like `contact routing enabled but no contacts were found`._
+
+* Lookup contact-specific environment variables for Pagerduty API Authentication
+
+  When `--contact-routing` is enabled, the Sensu Pagerduty Handler will attempt to create or update an event per configured "contact".
+  For each configured "contact", the Sensu Pagerduty Handler will look for a matching environment variable containing a Pagerduty token.
+  Pagerduty token environment variables should be prefixed with `PAGERDUTY_TOKEN_` and match the contact name in all-uppercase (e.g. the contact "team_a" needs a corresponding `PAGERDUTY_TOKEN_TEAM_A` environment variable).
+
+  _NOTE: contact names are converted to environment variables via `fmt.Sprintf("PAGERDUTY_TOKEN_%s",strings.ToUpper(contact))`._
+
+  If a matching contact environment variable is found, the event will be processed.
+  If the contact environment variable is not found, the handler will log a warning (e.g. `WARNING: skipping contact: "team-a" (no environment variable found for "PAGERDUTY_TOKEN_TEAM_A")`\n).
+
+#### Contact Routing Example
+
+```yaml
+---
+api_version: core/v2
+type: Handler
+metadata:
+  name: pagerduty
+spec:
+  type: pipe
+  command: >-
+    sensu-pagerduty-handler
+    --contact-routing
+    --dedup-key-template "{{.Entity.Namespace}}-{{.Entity.Name}}-{{.Check.Name}}"
+    --status-map "{\"info\":[0],\"warning\": [1],\"critical\": [2],\"error\": [3,127]}"
+    --summary-template "[{{.Entity.Namespace}}] {{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}"
+    --details-template "{{ .Check.Name }} is {{ .Check.State }} on {{ .Entity.Name }} (namespace: {{ .Entity.Namespace }})"
+  timeout: 10
+  filters: []
+  runtime_assets: []
+  env_vars: []
+  secrets:
+    - name: PAGERDUTY_TOKEN_TEAM_A
+      secret: pagerduty_token_team_a
+    - name: PAGERDUTY_TOKEN_TEAM_B
+      secret: pagerduty_token_team_b
+```
+
+_NOTE: contact routing is compatible with Sensu Secrets or environment variables set via Handler `env_vars`, but given the sensitive nature of a Pagerduty API token, using secrets management is strongly encouraged._
+
 ### Proxy support
 
 This handler supports the use of the environment variables HTTP_PROXY,

go.mod

@@ -1,33 +1,53 @@
 module github.com/sensu/sensu-pagerduty-handler
 
-go 1.14
+go 1.18
 
 require (
 	github.com/PagerDuty/go-pagerduty v1.3.0
-	github.com/coreos/etcd v3.3.25+incompatible // indirect
+	github.com/sensu-community/sensu-plugin-sdk v0.11.0
+	github.com/sensu/sensu-go/api/core/v2 v2.9.1-alpha
+	github.com/stretchr/testify v1.6.0
+	golang.org/x/exp v0.0.0-20220428152302-39d4317da171
+)
+
+require (
+	github.com/blang/semver/v4 v4.0.0 // indirect
+	github.com/coreos/go-semver v0.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/echlebek/timeproxy v1.0.0 // indirect
 	github.com/fsnotify/fsnotify v1.4.9 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/golang/protobuf v1.4.3 // indirect
+	github.com/golang-jwt/jwt/v4 v4.0.0 // indirect
+	github.com/golang/protobuf v1.5.2 // indirect
+	github.com/google/go-querystring v1.0.0 // indirect
 	github.com/google/uuid v1.2.0 // indirect
-	github.com/json-iterator/go v1.1.10 // indirect
+	github.com/hashicorp/hcl v1.0.0 // indirect
+	github.com/inconshreveable/mousetrap v1.0.0 // indirect
 	github.com/magiconair/properties v1.8.4 // indirect
 	github.com/mitchellh/mapstructure v1.4.1 // indirect
 	github.com/pelletier/go-toml v1.8.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/robertkrimen/otto v0.0.0-20200922221731-ef014fd054ac // indirect
-	github.com/sensu-community/sensu-plugin-sdk v0.11.0
-	github.com/sensu/sensu-go/api/core/v2 v2.6.0
-	github.com/sensu/sensu-go/types v0.5.0 // indirect
+	github.com/robfig/cron/v3 v3.0.1 // indirect
+	github.com/sensu/sensu-go/types v0.9.1-alpha2 // indirect
+	github.com/sensu/sensu-licensing v0.1.2 // indirect
 	github.com/sirupsen/logrus v1.7.0 // indirect
 	github.com/spf13/afero v1.5.1 // indirect
 	github.com/spf13/cast v1.3.1 // indirect
 	github.com/spf13/cobra v1.1.3 // indirect
 	github.com/spf13/jwalterweatherman v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/spf13/viper v1.7.1 // indirect
-	github.com/stretchr/testify v1.6.0
-	golang.org/x/net v0.0.0-20210119194325-5f4716e94777 // indirect
-	golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c // indirect
+	github.com/subosito/gotenv v1.2.0 // indirect
+	go.etcd.io/etcd/api/v3 v3.5.0 // indirect
+	golang.org/x/net v0.0.0-20210405180319-a5a99cb37ef4 // indirect
+	golang.org/x/sys v0.0.0-20211019181941-9d821ace8654 // indirect
 	golang.org/x/text v0.3.5 // indirect
-	google.golang.org/genproto v0.0.0-20210207032614-bba0dbe2a9ea // indirect
-	google.golang.org/grpc v1.35.0 // indirect
+	google.golang.org/genproto v0.0.0-20210602131652-f16073e35f0c // indirect
+	google.golang.org/grpc v1.38.0 // indirect
+	google.golang.org/protobuf v1.26.0 // indirect
 	gopkg.in/ini.v1 v1.62.0 // indirect
+	gopkg.in/sourcemap.v1 v1.0.5 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c // indirect
 )