Sensu Go Jira Handler

Table of Contents

• Overview
• Enterprise Plugin
• Usage examples
  • Help
  • Authenticating Using Jira's Cloud Version
  • Resolving Issue Configuration
• Configuration
  • Asset registration
  • Handler definition
  • Environment Variables
  • Templating Support
  • Argument Annotations
  • Proxy support

Overview

The Sensu Go Jira handler is a Sensu Event Handler that creates or updates a Jira issue.

Enterprise Plugin

The Sensu Go Jira Handler is an Enterprise plugin that requires a valid Sensu license to run.
Sensu Go >= 5.21 will add the SENSU_LICENSE_FILE environment variable to the handler execution.
To run the plugin independently of Sensu (ex. test/dev), you must set the env var:

SENSU_LICENSE_FILE=$(sensuctl license info --format json)

Usage Examples

Help

The Sensu Go Handler for managing Jira issues

Usage:
  sensu-jira-handler [flags]
  sensu-jira-handler [command]

Available Commands:
  help        Help about any command
  version     Print the version number of this plugin

Flags:
  -h, --help                                   help for sensu-jira-handler
  -T, --http-timeout uint                      The HTTP timeout
  -t, --jira-issue-type string                 The type of Jira issue to create
  -p, --jira-password string                   The Jira password
  -k, --jira-project-key string                The Jira project key
  -n, --jira-project-name string               The Jira project name
  -s, --jira-resolution-state string           The key of the status to transition the issue to when resolving it
  -d, --jira-issue-description string          The template to use to populate the issue description (default full event JSON)
  -c, --jira-issue-resolution-comment string   The template to use to populate the issue resolution comment (default "Sensu has resolved the event.")
  -U, --jira-url string                        The Jira URL
  -u, --jira-username string                   The Jira username
  -v, --verbose                                Verbose mode

Use "sensu-jira-handler [command] --help" for more information about a command.

Authenticating Using Jira's Cloud Version

While the on-premise version of Jira uses basic HTTP authentication with only
a simple username and password the cloud version requires the use of an API
token to authenticate. To create the API token perform the following steps:

1. Navigate to Atlassian's API Tokens Screen
2. Click on the Create API Token button
3. In the popup box enter Sensu Jira Handler or any label of your liking
4. Click on the Create button
5. Click on Copy to clipboard to copy your token

The token copied becomes the password you use to authenticate using the
JIRA_PASSWORD environment variable (preferably as a secret), or the
--jira-password option.

Resolving Issue Configuration

Unless a state is specified (either by --jira-resolution-state or via
annotation) when attempting to resolve an issue, this
handler will default to using the first transition state found in the Done
status category for that issue type.

To make sure this works, a screen with the Resolution needs to be configured
in the transition to the Done state. If this is not setup correctly the issue
resolution will fail.

Configuration

Sensu Go

Asset registration

Sensu Assets 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-jira-handler

If you're using an earlier version of sensuctl, you can find the asset on the
Bonsai Asset Index.

Handler definition

---
type: Handler
api_version: core/v2
metadata:
  name: jira
  namespace: default
spec:
  type: pipe
  command: sensu-jira-handler --jira-url 'https://example.atlassian.net' --jira-project-key SEN
  timeout: 10
  runtime_assets:
  - sensu/sensu-jira-handler
  filters:
  - is_incident
  secrets:
  - name: JIRA_USERNAME
    secret: jira_username
  - name: JIRA_PASSWORD
    secret: jira_password

Environment Variables

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.

Security Note: Care should be taken to not expose the API 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 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.

---
type: Secret
api_version: secrets/v1
metadata:
  name: jira_username
spec:
  provider: env
  id: JIRA_USERNAME
---
type: Secret
api_version: secrets/v1
metadata:
  name: jira_password
spec:
  provider: env
  id: JIRA_PASSWORD

Templating Support

The --jira-issue-description and --jira-issue-resolution-comment options
allow the customization of the issue description and resolution comments using
Golang Templates. Within the templates all fields from the event
are available for use.

For example, to add entity name, check name, and check state to both the issue description and resolution commments, use this templating in your handler command:

--jira-issue-description "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}" --jira-issue-resolution-comment "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}"

These templates will result in issue description and resolution comments similar to the following example:

webserver03/check-nginx: passing

Here's a complete handler example that uses templates in the command to include issue description and resolution comment details:

---
type: Handler
api_version: core/v2
metadata:
  name: jira
  namespace: default
spec:
  type: pipe
  command: sensu-jira-handler --jira-url 'https://example.atlassian.net' --jira-project-key SEN --jira-issue-description "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.State}}" --jira-issue-resolution-comment "{{.Entity.Name}}/{{.Check.Name}}: {{.Check.TotalStateChange}}/{{.Check.State}}"
  timeout: 10
  runtime_assets:
  - sensu/sensu-jira-handler
  filters:
  - is_incident
  secrets:
  - name: JIRA_USERNAME
    secret: jira_username
  - name: JIRA_PASSWORD
    secret: jira_password

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/jira/config.

Examples

To change the issue type for a particular check, for that checks's metadata
add the following:

type: CheckConfig
api_version: core/v2
metadata:
  annotations:
    sensu.io/plugins/jira/config/jira-issue-type: Bug
[...]

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.