Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.x] [Docs][Actions] Add docs for Jira and IBM Resilient (#78316) #78773

Merged
merged 1 commit into from
Sep 29, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docs/user/alerting/action-types.asciidoc
Original file line number Diff line number Diff line change
@@ -11,10 +11,19 @@ a| <<email-action-type, Email>>

| Send email from your server.

a| <<resilient-action-type, IBM Resilient>>

| Create an incident in IBM Resilient.

a| <<index-action-type, Index>>

| Index data into Elasticsearch.

a| <<jira-action-type, Jira>>

| Create an incident in Jira.


a| <<pagerduty-action-type, PagerDuty>>

| Send an event in PagerDuty.
@@ -53,10 +62,12 @@ before {kib} starts.
If you preconfigure a connector, you can also <<preconfigured-action-type-example, preconfigure its action type>>.

include::action-types/email.asciidoc[]
include::action-types/resilient.asciidoc[]
include::action-types/index.asciidoc[]
include::action-types/jira.asciidoc[]
include::action-types/pagerduty.asciidoc[]
include::action-types/server-log.asciidoc[]
include::action-types/servicenow.asciidoc[]
include::action-types/slack.asciidoc[]
include::action-types/webhook.asciidoc[]
include::action-types/pre-configured-connectors.asciidoc[]
include::action-types/servicenow.asciidoc[]
77 changes: 77 additions & 0 deletions docs/user/alerting/action-types/jira.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
[role="xpack"]
[[jira-action-type]]
=== Jira action

The Jira action type uses the https://developer.atlassian.com/cloud/jira/platform/rest/v2/[REST API v2] to create Jira issues.

[float]
[[jira-connector-configuration]]
==== Connector configuration

Jira connectors have the following configuration properties:

Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
URL:: Jira instance URL.
Project key:: Jira project key.
Email (or username):: The account email (or username) for HTTP Basic authentication.
API token (or password):: Jira API authentication token (or password) for HTTP Basic authentication.

[float]
[[Preconfigured-jira-configuration]]
==== Preconfigured action type

[source,text]
--
my-jira:
name: preconfigured-jira-action-type
actionTypeId: .jira
config:
apiUrl: https://elastic.atlassian.net
projectKey: ES
secrets:
email: testuser
apiToken: tokenkeystorevalue
--

`config` defines the action type specific to the configuration and contains the following properties:

[cols="2*<"]
|===

| `apiUrl`
| An address that corresponds to *URL*.

| `projectKey`
| A key that corresponds to *Project Key*.

|===

`secrets` defines sensitive information for the action type:

[cols="2*<"]
|===

| `email`
| A string that corresponds to *Email*.

| `apiToken`
| A string that corresponds to *API Token*. Should be stored in the <<creating-keystore, {kib} keystore>>.

|===

[[jira-action-configuration]]
==== Action configuration

Jira actions have the following configuration properties:

Issue type:: The type of the issue.
Priority:: The priority of the incident.
Labels:: The labels of the incident.
Title:: A title for the issue, used for searching the contents of the knowledge base.
Description:: The details about the incident.
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.

[[configuring-jira]]
==== Configuring and testing Jira

Jira offers free https://www.atlassian.com/software/jira/free[Instances], which you can use to test incidents.
2 changes: 1 addition & 1 deletion docs/user/alerting/action-types/pagerduty.asciidoc
Original file line number Diff line number Diff line change
@@ -36,7 +36,7 @@ This is required to encrypt parameters that must be secured, for example PagerDu
If you have security enabled:

* You must have
application privileges to access Metrics, APM, Uptime, or SIEM.
application privileges to access Metrics, APM, Uptime, or Security.
* If you are using a self-managed deployment with security, you must have
Transport Security Layer (TLS) enabled for communication <<configuring-tls-kib-es, between Elasticsearch and Kibana>>.
Alerts uses API keys to secure background alert checks and actions,
76 changes: 76 additions & 0 deletions docs/user/alerting/action-types/resilient.asciidoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
[role="xpack"]
[[resilient-action-type]]
=== IBM Resilient action

The IBM Resilient action type uses the https://developer.ibm.com/security/resilient/rest/[RESILIENT REST v2] to create IBM Resilient incidents.

[float]
[[resilient-connector-configuration]]
==== Connector configuration

IBM Resilient connectors have the following configuration properties:

Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
URL:: IBM Resilient instance URL.
Organization ID:: IBM Resilient organization ID.
API key ID:: The authentication key ID for HTTP Basic authentication.
API key secret:: The authentication key secret for HTTP Basic authentication.

[float]
[[Preconfigured-resilient-configuration]]
==== Preconfigured action type

[source,text]
--
my-resilient:
name: preconfigured-resilient-action-type
actionTypeId: .resilient
config:
apiUrl: https://elastic.resilient.net
orgId: ES
secrets:
apiKeyId: testuser
apiKeySecret: tokenkeystorevalue
--

`config` defines the action type specific to the configuration and contains the following properties:

[cols="2*<"]
|===

| `apiUrl`
| An address that corresponds to *URL*.

| `orgId`
| An ID that corresponds to *Organization ID*.

|===

`secrets` defines sensitive information for the action type:

[cols="2*<"]
|===

| `apiKeyId`
| A string that corresponds to *API key ID*.

| `apiKeySecret`
| A string that corresponds to *API Key secret*. Should be stored in the <<creating-keystore, {kib} keystore>>.

|===

[[resilient-action-configuration]]
==== Action configuration

IBM Resilient actions have the following configuration properties:

Incident types:: The incident types of the incident.
Severity code:: The severity of the incident.
Name:: A name for the issue, used for searching the contents of the knowledge base.
Description:: The details about the incident.
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.

[[configuring-resilient]]
==== Configuring and testing IBM Resilient

IBM Resilient offers https://www.ibm.com/security/intelligent-orchestration/resilient[Instances], which you can use to test incidents.
8 changes: 4 additions & 4 deletions docs/user/alerting/action-types/servicenow.asciidoc
Original file line number Diff line number Diff line change
@@ -10,7 +10,7 @@ The ServiceNow action type uses the https://developer.servicenow.com/app.do#!/re

ServiceNow connectors have the following configuration properties:

Name:: The name of the connector. The name is used to identify a connector in the management UI connector listing, or in the connector list when configuring an action.
Name:: The name of the connector. The name is used to identify a connector in the **Stack Management** UI connector listing, and in the connector list when configuring an action.
URL:: ServiceNow instance URL.
Username:: Username for HTTP Basic authentication.
Password:: Password for HTTP Basic authentication.
@@ -37,7 +37,7 @@ Password:: Password for HTTP Basic authentication.
|===

| `apiUrl`
| An address that corresponds to *Sender*.
| An address that corresponds to *URL*.

|===

@@ -47,7 +47,7 @@ Password:: Password for HTTP Basic authentication.
|===

| `username`
| A string that corresponds to *User*.
| A string that corresponds to *Username*.

| `password`
| A string that corresponds to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
@@ -62,7 +62,7 @@ ServiceNow actions have the following configuration properties:
Urgency:: The extent to which the incident resolution can delay.
Severity:: The severity of the incident.
Impact:: The effect an incident has on business. Can be measured by the number of affected users or by how critical it is to the business in question.
Short description:: A short description of the incident, used for searching the contents of the knowledge base.
Short description:: A short description for the incident, used for searching the contents of the knowledge base.
Description:: The details about the incident.
Additional comments:: Additional information for the client, such as how to troubleshoot the issue.

6 changes: 3 additions & 3 deletions docs/user/alerting/alerting-getting-started.asciidoc
Original file line number Diff line number Diff line change
@@ -6,7 +6,7 @@ beta[]

--

Alerting allows you to detect complex conditions within different {kib} apps and trigger actions when those conditions are met. Alerting is integrated with <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*SIEM*>>, <<xpack-uptime,*Uptime*>>, can be centrally managed from the <<management,*Management*>> UI, and provides a set of built-in <<action-types, actions>> and <<alert-types, alerts>> for you to use.
Alerting allows you to detect complex conditions within different {kib} apps and trigger actions when those conditions are met. Alerting is integrated with <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*Security*>>, <<xpack-uptime,*Uptime*>>, can be centrally managed from the <<management,*Management*>> UI, and provides a set of built-in <<action-types, actions>> and <<alert-types, alerts>> for you to use.

image::images/alerting-overview.png[Alerts and actions UI]

@@ -148,7 +148,7 @@ Functionally, {kib} alerting differs in that:
* {kib} alerts tracks and persists the state of each detected condition through *alert instances*. This makes it possible to mute and throttle individual instances, and detect changes in state such as resolution.
* Actions are linked to *alert instances* in {kib} alerting. Actions are fired for each occurrence of a detected condition, rather than for the entire alert.

At a higher level, {kib} alerts allow rich integrations across use cases like <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*SIEM*>>, and <<xpack-uptime,*Uptime*>>.
At a higher level, {kib} alerts allow rich integrations across use cases like <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*Security*>>, and <<xpack-uptime,*Uptime*>>.
Pre-packaged *alert types* simplify setup, hide the details complex domain-specific detections, while providing a consistent interface across {kib}.

[float]
@@ -171,7 +171,7 @@ To access alerting in a space, a user must have access to one of the following f

* <<xpack-apm,*APM*>>
* <<xpack-infra,*Metrics*>>
* <<xpack-siem,*SIEM*>>
* <<xpack-siem,*Security*>>
* <<xpack-uptime,*Uptime*>>

See <<kibana-feature-privileges, feature privileges>> for more information on configuring roles that provide access to these features.
2 changes: 1 addition & 1 deletion docs/user/alerting/defining-alerts.asciidoc
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
[[defining-alerts]]
== Defining alerts

{kib} alerts can be created in a variety of apps including <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*SIEM*>>, <<xpack-uptime,*Uptime*>> and from <<management,*Management*>> UI. While alerting details may differ from app to app, they share a common interface for defining and configuring alerts that this section describes in more detail.
{kib} alerts can be created in a variety of apps including <<xpack-apm,*APM*>>, <<xpack-infra,*Metrics*>>, <<xpack-siem,*Security*>>, <<xpack-uptime,*Uptime*>> and from <<management,*Management*>> UI. While alerting details may differ from app to app, they share a common interface for defining and configuring alerts that this section describes in more detail.

[float]
=== Alert flyout