actuator

README

Actuator

The actuator is a simple library and tool which allows the Prometheus Alertmanager to trigger actions via webhooks.

Usage

To configure the actuator server, create a YAML file. By default, actuator looks for /etc/actuator/actuator.yml.

It is your responsibility to make sure you don't put some potentially catastrophic command behind this webhook!

---
handlers:
    - path: /reboot-the-modem
      token: ThisIsSomeToken
      action: reboot-the-modem
actions:
    - name: reboot-the-modem
      command: |
        ssh root@the-modem "shutdown -r now"

Then start the actuator server. By default, it listens on 0.0.0.0:9942. The full command options are:

$ actuator --help
NAME:
   actuator - Execute commands in response to fired alerts

USAGE:
   actuator [global options] command [command options] [arguments...]

COMMANDS:
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --server.address value, -a value  ip:port from which to serve Prometheus metrics (default: "0.0.0.0:9942")
   --config.file value, -c value     actuator config file location (default: "/etc/actuator/actuator.yml")
   --help, -h                        show help (default: false)

Alertmanager

Then, configure the Alertmanager to route to the configured webhook. For example, alertmanager routes using the actuator might look like:

route:
  group_by: [alertname, severity, site]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

  receiver: your-default-receiver

  routes:
    # ExternalConnectivityHosed goes to the actuator.
    # This route repeats hourly, which means we reboot the modem hourly while the
    # connection is down.
    - match:
        severity: critical
        alertname: ExternalConnectivityHosed
      receiver: reboot-the-modem
      repeat_interval: 1h
      continue: true
    - match:
        severity: critical
      receiver: pager

And the corresponding receivers might look like:

receivers:
  - name: your-default-receiver
  - name: pager
    email_configs:
      - to: alerts@example.com
    pagerduty_configs:
      - service_key: youknowwhatevergoeshere
  - name: reboot-the-modem
    webhook_configs:
      - url: "http://localhost:9942/reboot-the-modem"
        http_config:
          authorization:
            credentials: ThisIsSomeToken

Documentation

Index

• func DefaultHandler() http.Handler
• func FromConfig(r io.Reader) (http.Handler, error)
• func Handle(path string, with Action, opts ...Option) http.Handler
• type Action
  • func CommandAction(command string) (Action, error)
• type AlermanagerWebhookPayload
• type Alert
• type AlertStatus
• type LabelKey
• type LabelValue
• type LogAction
  • func (*LogAction) Act(payload AlermanagerWebhookPayload) error
• type Option
  • func WithToken(token string) Option

Functions

func DefaultHandler

func DefaultHandler() http.Handler

DefaultHandler for any HTTP requests not matching a configured alertmanager webhook handler.

func FromConfig

func FromConfig(r io.Reader) (http.Handler, error)

func Handle

func Handle(path string, with Action, opts ...Option) http.Handler

Handle alertmanager webhook payloads at path, with the provided Action, using the provided opts (if any).

Types

type Action

type Action interface {
	// Act on the alertmanager webhook payload.
	Act(AlermanagerWebhookPayload) error
}

Action which can be taken when an alertmanager payload is sent to a handler.

func CommandAction

func CommandAction(command string) (Action, error)

CommandAction executes a command in response to an alertmanager payload.

type AlermanagerWebhookPayload

type AlermanagerWebhookPayload struct {
	Version           string                  `json:"version"`
	GroupKey          string                  `json:"groupKey"`
	TruncatedAlerts   int                     `json:"truncatedAlerts"`
	Status            AlertStatus             `json:"status"`
	Receiver          string                  `json:"receiver"`
	GroupLabels       map[LabelKey]LabelValue `json:"groupLabels"`
	CommonLabels      map[LabelKey]LabelValue `json:"commonLabels"`
	CommonAnnotations map[string]string       `json:"commonAnnotations"`
	Alertmanager      string                  `json:"externalURL"`
	Alerts            []Alert                 `json:"alerts"`
}

type Alert

type Alert struct {
	Status      AlertStatus             `json:"status"`
	Labels      map[LabelKey]LabelValue `json:"labels"`
	Annotations map[string]string       `json:"annotations"`
	Start       time.Time               `json:"startsAt"`
	End         time.Time               `json:"endsAt"`
	Generator   string                  `json:"generatorURL"`
	Fingerprint string                  `json:"fingerprint"`
}

type AlertStatus

type AlertStatus string

const (
	AlertStatusFiring   AlertStatus = "firing"
	AlertStatusResolved AlertStatus = "resolved"
)

type LabelKey

type LabelKey string

type LabelValue

type LabelValue string

type LogAction

type LogAction struct{}

LogAction does nothing but log an alertmanager payload.

func (*LogAction) Act

func (*LogAction) Act(payload AlermanagerWebhookPayload) error

type Option

type Option func(*actionHandler)

Option which may be passed to Handle.

func WithToken

func WithToken(token string) Option

WithToken option sets a Bearer token to protect calls to the handler.