Extended alerting documentation with information about using Kibana k…

…eystore and action types for preconfigured connectors (elastic#65201) * Extended alerting documentation with information about using Kibana keystore and action types for preconfigured connectors * Fixed due to comments and merged two preconfig pages * Fixed due to review comments * Update docs/user/alerting/action-types/index.asciidoc Co-authored-by: gchaps <[email protected]> * Fixed due to comments * - Co-authored-by: gchaps <[email protected]>
YulNaumenko · May 11, 2020 · f9231da · f9231da
1 parent f32519b
commit f9231da
Show file tree

Hide file tree

Showing 10 changed files with 197 additions and 84 deletions.
diff --git a/docs/user/alerting/action-types.asciidoc b/docs/user/alerting/action-types.asciidoc
@@ -43,11 +43,10 @@ see https://www.elastic.co/subscriptions[the subscription page].
 [[create-connectors]]
 === Preconfigured connectors and action types
 
-You can create connectors for actions in <<managing-alerts-and-actions, Alerts and Actions>> or via the action API.
-For out-of-the-box and standardized connectors, you can <<pre-configured-connectors, preconfigure connectors>>
+For out-of-the-box and standardized connectors, you can <<preconfigured-connector-example, preconfigure connectors>>
 before {kib} starts.
 
-Action type with only preconfigured connectors could be specified as a <<pre-configured-action-types, preconfigured action type>>.
+If you preconfigure a connector, you can also <<preconfigured-action-type-example, preconfigure its action type>>.
 
 include::action-types/email.asciidoc[]
 include::action-types/index.asciidoc[]
@@ -56,4 +55,3 @@ include::action-types/server-log.asciidoc[]
 include::action-types/slack.asciidoc[]
 include::action-types/webhook.asciidoc[]
 include::pre-configured-connectors.asciidoc[]
-include::pre-configured-action-types.asciidoc[]
diff --git a/docs/user/alerting/action-types/email.asciidoc b/docs/user/alerting/action-types/email.asciidoc
@@ -19,6 +19,37 @@ Username::  username for 'login' type authentication.
 Password::  password for 'login' type authentication.
 
 [float]
+[[Preconfigured-email-configuration]]
+==== Preconfigured action type
+
+[source,text]
+--
+ id: 'my-email'
+ name: preconfigured-email-action-type
+ actionTypeId: .email
+ config:
+   from: [email protected] <1.1>
+   host: validhostname <1.2>
+   port: 8080 <1.3>
+   secure: false <1.4>
+ secrets:
+   user: testuser <2.1>
+   password: passwordkeystorevalue <2.2>
+--
+
+`config` defines the action type specific to the configuration and contains the following properties:
+
+<1.1> `from:` is an email address and correspond to *Sender*.
+<1.2> `host:` is a string and correspond to *Host*.
+<1.3> `port:` is a number and correspond to *Port*.
+<1.4> `secure:` is a boolean and correspond to *Secure*.
+
+`secrets` defines action type sensitive configuration:
+
+<2.1> `user:` is a string and correspond to *User*.
+<2.2> `password:` is a string and correspond to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
+
+
 [[email-action-configuration]]
 ==== Action configuration
 

diff --git a/docs/user/alerting/action-types/index.asciidoc b/docs/user/alerting/action-types/index.asciidoc
@@ -15,6 +15,28 @@ Index::     The {es} index to be written to.
 Refresh::   Setting for the {ref}/docs-refresh.html[refresh] policy for the write request.
 Execution time field::  This field will be automatically set to the time the alert condition was detected.
 
+[float]
+[[Preconfigured-index-configuration]]
+==== Preconfigured action type
+
+[source,text]
+--
+ id: 'my-index'
+ name: action-type-index
+ actionTypeId: .index
+ config:
+   index: .kibana <1>
+   refresh: true <2>
+   executionTimeField: somedate <3>
+--
+
+`config` defines the action type specific to the configuration and contains the following properties:
+
+<1> `index:` is a string and correspond to *Index*.
+<2> `refresh:` is a boolean and correspond to *Refresh*.
+<3> `executionTimeField:` is a string and correspond to *Execution time field*.
+
+
 [float]
 [[index-action-configuration]]
 ==== Action configuration

diff --git a/docs/user/alerting/action-types/pagerduty.asciidoc b/docs/user/alerting/action-types/pagerduty.asciidoc
@@ -135,6 +135,29 @@ Name::      The name of the connector. The name is used to identify a  connector
 API URL::   An optional PagerDuty event URL. Defaults to `https://events.pagerduty.com/v2/enqueue`. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted.
 Integration Key::   A 32 character PagerDuty Integration Key for an integration on a service, also referred to as the routing key.
 
+[float]
+[[Preconfigured-pagerduty-configuration]]
+==== Preconfigured action type
+
+[source,text]
+--
+ id: 'my-pagerduty'
+ name: preconfigured-pagerduty-action-type
+ actionTypeId: .pagerduty
+ config:
+   apiUrl: https://test.host <1.1>
+ secrets:
+   routingKey: testroutingkey <2.1>
+--
+
+`config` defines the action type specific to the configuration and contains the following properties:
+
+<1.1> `apiUrl:` is URL string and correspond to *API URL*.
+
+`secrets` defines action type sensitive configuration:
+
+<2.1> `routingKey:` is a string and correspond to *Integration Key*.
+
 [float]
 [[pagerduty-action-configuration]]
 ==== Action configuration

diff --git a/docs/user/alerting/action-types/server-log.asciidoc b/docs/user/alerting/action-types/server-log.asciidoc
@@ -12,6 +12,17 @@ Server log 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.
 
+[float]
+[[Preconfigured-server-log-configuration]]
+==== Preconfigured action type
+
+[source,text]
+--
+ id: 'my-server-log'
+ name: test
+ actionTypeId: .server-log
+--
+
 [float]
 [[server-log-action-configuration]]
 ==== Action configuration

diff --git a/docs/user/alerting/action-types/slack.asciidoc b/docs/user/alerting/action-types/slack.asciidoc
@@ -13,6 +13,24 @@ Slack 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.
 Webhook URL::   The URL of the incoming webhook. See https://api.slack.com/messaging/webhooks#getting_started[Slack Incoming Webhooks] for instructions on generating this URL. If you are using the <<action-settings, `xpack.actions.whitelistedHosts`>> setting, make sure the hostname is whitelisted.
 
+[float]
+[[Preconfigured-slack-configuration]]
+==== Preconfigured action type
+
+[source,text]
+--
+ id: 'my-slack'
+ name: preconfigured-slack-action-type
+ actionTypeId: .slack
+ config:
+   webhookUrl: 'https://hooks.slack.com/services/abcd/efgh/ijklmnopqrstuvwxyz' <1>
+--
+
+`config` defines the action type specific to the configuration and contains the following properties:
+
+<1> `webhookUrl:` is URL string and correspond to *Webhook URL*.
+
+
 [float]
 [[slack-action-configuration]]
 ==== Action configuration

diff --git a/docs/user/alerting/action-types/webhook.asciidoc b/docs/user/alerting/action-types/webhook.asciidoc
@@ -17,6 +17,36 @@ Headers::   A set of key-value pairs sent as headers with the request
 User::      An optional username. If set, HTTP basic authentication is used. Currently only basic authentication is supported.
 Password::  An optional password. If set, HTTP basic authentication is used. Currently only basic authentication is supported.
 
+[float]
+[[Preconfigured-webhook-configuration]]
+==== Preconfigured action type 
+
+[source,text]
+--
+ id: 'my-webhook'
+ name: preconfigured-webhook-action-type
+ actionTypeId: .webhook
+ config:
+   url: https://test.host <1.1>
+   method: POST <1.2>
+   headers: <1.3>
+     testheader: testvalue
+ secrets:
+   user: testuser <2.1>
+   password: passwordkeystorevalue <2.2>
+--
+
+`config` defines the action type specific to the configuration and contains the following properties:
+
+<1.1> `url:` is URL string and correspond to *URL*.
+<1.2> `method:` is a string and correspond to *Method*.
+<1.3> `headers:` is Record<String, String> and correspond to *Headers*.
+
+`secrets` defines action type sensitive configuration:
+
+<2.1> `user:` is a string and correspond to *User*.
+<2.2> `password:` is a string and correspond to *Password*. Should be stored in the <<creating-keystore, {kib} keystore>>.
+
 [float]
 [[webhook-action-configuration]]
 ==== Action configuration

diff --git a/docs/user/alerting/images/pre-configured-action-type-select-type.png b/docs/user/alerting/images/pre-configured-action-type-select-type.png
diff --git a/docs/user/alerting/pre-configured-action-types.asciidoc b/docs/user/alerting/pre-configured-action-types.asciidoc
diff --git a/docs/user/alerting/pre-configured-connectors.asciidoc b/docs/user/alerting/pre-configured-connectors.asciidoc
@@ -1,11 +1,10 @@
 [role="xpack"]
-[[pre-configured-connectors]]
+[[pre-configured-action-types-and-connectors]]
 
-== Preconfigured connectors
+== Preconfigured connectors and action types
 
-You can preconfigure an action connector to have all the information it needs prior to startup
+You can preconfigure an action type or a connector to have all the information it needs prior to startup
 by adding it to the `kibana.yml` file.
-Sensitive configuration information, such as credentials, can use the {kib} keystore.
 
 Preconfigured connectors offer the following capabilities:
 
@@ -14,11 +13,15 @@ action are predefined, including the connector name and ID.
 - Appear in all spaces because they are not saved objects.
 - Cannot be edited or deleted.
 
+Sensitive configuration information, such as credentials, can use the <<creating-keystore, {kib} keystore>>.
+
+A preconfigured action types has only preconfigured connectors. Preconfigured connectors can belong to either the preconfigured action type or to the regular action type.
+
 [float]
 [[preconfigured-connector-example]]
-=== Example of a preconfigured connector
+=== Creating a preconfigured connector
 
-The following example shows a valid configuration 2 out-of-the box connector.
+The following example shows a valid configuration of two out-of-the box connectors: <<slack-action-type, Slack>> and <<webhook-action-type, Webhook>>.
 
 ```js
   xpack.actions.preconfigured:
@@ -49,26 +52,30 @@ The following example shows a valid configuration 2 out-of-the box connector.
 
 [NOTE]
 ==============================================
-Sensitive properties, such as passwords, can also be stored in the {kib} keystore.
+Sensitive properties, such as passwords, can also be stored in the <<creating-keystore, {kib} keystore>>.
 ==============================================
 
 [float]
-[[pre-configured-connector-alert-form]]
-=== Creating an alert with a preconfigured connector
+[[preconfigured-action-type-example]]
+=== Creating a preconfigured action type
 
-When attaching an action to an alert,
-select from a list of available action types, and
-then select the Slack or Webhook type. Those action types were configured previously.
-The preconfigured connector is installed and is automatically selected.
+In the `kibana.yml` file:
 
-[role="screenshot"]
-image::images/alert-pre-configured-slack-connector.png[Create alert with selected Slack action type]
+. Exclude the action type from `xpack.actions.enabledActionTypes`.
+. Add all its preconfigured connectors.
 
-The dropdown is populated with additional preconfigured Slack connectors.
-The `preconfigured` label distinguishes them from space-aware connectors that use saved objects.
+The following example shows a valid configuration of preconfigured action type with one out-of-the box connector.
 
-[role="screenshot"]
-image::images/alert-pre-configured-connectors-dropdown.png[Dropdown list with pre-cofigured connectors]
+```js
+  xpack.actions.enabledActionTypes: ['.slack', '.email', '.index'] <1>
+  xpack.actions.preconfigured:                                     <2>
+    - id: 'my-server-log'
+      actionTypeId: .server-log
+      name: 'Server log #xyz'
+```
+
+<1> `enabledActionTypes` should exclude preconfigured action type to prevent creating and deleting connectors.
+<2> `preconfigured` is the setting for defining the list of available connectors for the preconfigured action type.
 
 [float]
 [[managing-pre-configured-connectors]]
@@ -85,3 +92,37 @@ A message indicates that this is a preconfigured connector.
 
 [role="screenshot"]
 image::images/pre-configured-connectors-view-screen.png[Pre-configured connector view details]
+
+The connector details preview is disabled for preconfigured connectors.
+
+[role="screenshot"]
+image::images/pre-configured-action-type-managing.png[Connectors managing tab with pre-cofigured]
+
+
+[float]
+[[managing-pre-configured-action-types]]
+=== Managing preconfigured action types
+
+Clicking *Create connector* shows the list of available action types.
+Disabled action types are not included.
+
+[role="screenshot"]
+image::images/pre-configured-action-type-select-type.png[Pre-configured connector create menu]
+
+[float]
+[[pre-configured-connector-alert-form]]
+=== Alert with a preconfigured connector
+
+When attaching an action to an alert,
+select from a list of available action types, and
+then select the Slack or Webhook type. Those action types were configured previously.
+The preconfigured connector is installed and is automatically selected.
+
+[role="screenshot"]
+image::images/alert-pre-configured-slack-connector.png[Create alert with selected Slack action type]
+
+The dropdown is populated with additional preconfigured Slack connectors.
+The `preconfigured` label distinguishes them from space-aware connectors that use saved objects.
+
+[role="screenshot"]
+image::images/alert-pre-configured-connectors-dropdown.png[Dropdown list with pre-cofigured connectors]