Installation and Configuration¶
Requirements¶
- PHP (>= 7.0)
- Icinga Web 2 (>= 2.9.0)
- Icinga Web 2 libraries:
- Icinga PHP Library (ipl) (>= 0.8)
- Icinga Web 2 modules:
- The
monitoring
oricingadb
module needs to be configured and enabled.
Install the Icinga Module for JIRA®¶
Install it like any other module.
Use jira
as name.
Configuration¶
Currently you have to manually create a related configuration file. In future we’d love to allow you to provide these settings directly in the Web GUI. For now please create a dedicated module configuration directory, like:
install -d -m 2770 -o www-data -g icingaweb2 /etc/icingaweb2/modules/jira
Please adjust owner and group to fit your system, and also the directory in case
your ICINGAWEB_CONFIGDIR
is not /etc/icingaweb2
.
We need a new file named config.ini
in this newly created directory:
[api]
host = "jira.example.com"
; port = 443
; path = "/"
; scheme = "https"
username = "icinga"
password = "Base64 encoded password here"
[ui]
; default_project = "SO"
; default_issuetype = "Event"
[icingaweb]
url = "https://icinga.example.com/icingaweb2"
The port
and path
settings are optional, protocol is always HTTPS. The
given user needs permissions to create (and show) issues in at least one JIRA
project.
If you want to have links pointing back to your Icinga Installation in your
JIRA issues, you need to fill the url
setting.
The ui
section allows to optionally pre-select a specific project and/or a
specific issue type in the “Create New Issue” form. Please note that those
values must represent “real” names, not display names. In the above example
the project named “Service Operations” had the shortcut “SO”.
If you want to run icingacli
commands (read: send notifications), then your
Icinga user must be member of the icingaweb2
group. In case it isn’t, this
can usually be fixed as follows:
usermod -a -G icingaweb2 icinga2
Depending on your OS configuration, it might be required to restart Icinga 2 afterwards:
systemctl restart icinga2.service
Required JIRA Custom Fields¶
This module requires you to create two custom fields in JIRA:
icingaKey
: a searchable text fieldicingaStatus
: a short text field, 12 characters are enough
icingaKey field value¶
TL;DR: you do not need to read this, it is just for those who are curios how this field is going to be used.
This module uses icingaKey
to figure out whether an issue for the given object
already exists. Hosts use their host name, services use hostname!servicename.
As JIRA seems to offer no exact search for custom text fields out of the box (at
least not without installing extra plugins), we are cheating. Search is down via
~
and we add surrounding escaped double quotes. Still, this doesn’t seem to be
enough. So we prefix the key with BEGIN
and postfix it with END
.
Said all this, the icingaKey
for Disk Space
on example.com
will result in the
following JQL construct:
icingaKey ~ "\"BEGINexample.com!Disk SpaceEND\""
A little bit weird, but it should work fine. And as this field is usually not shown anywhere, it shouldn’t disturb.
Fill JIRA Custom Fields¶
Hint: This is optional, do not blindly copy & paste. Use this as an example in case you need to feed different workflows with special paprameters.
For your customized workflows you might need this module to ship additional
fields. This is as easy as creating corresponding templates in your templates.ini
in <ICINGAWEB_CONFIGDIR>/modules/jira/templates.ini
:
[my-workflow]
Task = "API"
SearchCategory = "CI"
SearchTerm = "${host}.example.com"
Activity.value = "proactive"
customfield_1232 = "Icinga"
duedate = "3 days"
Pass my-workflow
to your NotificationCommand through the --template
parameter
and your issue will fill in and pass all above fields.
-
It is possible to use the internal field name (like
customfield_1232
), but the visible name is also fine. Even special characters like inAktivität
are allowed -
In case your Custom Field expects an Array of values, please use numeric keys as in this example:
[my-workflow]
; ...
Teams.0.value = "My Team"
Teams.1.value = "Another Team"
Tags.0 = "ama"
Tags.1 = "zing"
-
You can use placeholders for variables via
${varname}
. You can use some of the predefined ones, but you can also add new ones. You can for example use${location}
and pass$host.vars.location$
via--location
, just make sure that the parameter name matches the placeholder/variable name -
Predefined variable names are host, service, state, project, issuetype, summary and description
That’s it, now you should be ready to start Sending Notifications.