From 2f587deb8cf59e10ab64847e7399e3f4bf39ab71 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Thu, 25 Feb 2021 16:03:21 -0800 Subject: [PATCH 1/5] [Alerting][Docs] Changed alerting documentation to poin to a single source of explaining the configurations. --- docs/settings/alert-action-settings.asciidoc | 20 +++++++++++++++++ .../pre-configured-connectors.asciidoc | 2 +- .../alerting-getting-started.asciidoc | 2 +- ...lerting-production-considerations.asciidoc | 4 ++-- docs/user/alerting/defining-alerts.asciidoc | 22 +------------------ x-pack/plugins/triggers_actions_ui/README.md | 2 +- 6 files changed, 26 insertions(+), 26 deletions(-) diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc index d6f5fb1baba8eb..b650e4cc062f77 100644 --- a/docs/settings/alert-action-settings.asciidoc +++ b/docs/settings/alert-action-settings.asciidoc @@ -41,6 +41,9 @@ You can configure the following settings in the `kibana.yml` file. [cols="2*<"] |=== +| `xpack.actions.enabled` {ess-icon} + | Feature toggle that enables Actions in {kib}. It defaults to `true`. + | `xpack.actions.allowedHosts` {ess-icon} | A list of hostnames that {kib} is allowed to connect to when built-in actions are triggered. It defaults to `[*]`, allowing any host, but keep in mind the potential for SSRF attacks when hosts are not explicitly added to the allowed hosts. An empty list `[]` can be used to block built-in actions from making any external connections. + + @@ -51,6 +54,23 @@ You can configure the following settings in the `kibana.yml` file. + Disabled action types will not appear as an option when creating new connectors, but existing connectors and actions of that type will remain in {kib} and will not function. +| `xpack.actions.preconfigured` + | Specifies preconfigured action IDs and configs. It defaults to {}. + +| `xpack.actions.proxyUrl` {ess-icon} + | Specifies the proxy URL to use, if using a proxy for actions. By default is no proxy used. + +| `xpack.actions.proxyHeader` {ess-icon} + | Specifies HTTP headers for proxy, if using a proxy for actions. + +| `xpack.actions.proxyRejectUnauthorizedCertificates` {ess-icon} + | Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. It defaults to `true`. + +| `xpack.actions.rejectUnauthorized` {ess-icon} + | Set to `false` to bypass certificate validation for actions. It defaults to `true`. + + + + As an alternative to both `xpack.actions.proxyRejectUnauthorizedCertificates` and `xpack.actions.rejectUnauthorized`, the OS level environment variable `NODE_EXTRA_CA_CERTS` can be set to point to a file that contains the root CA(s) needed for certificates to be trusted. + |=== [float] diff --git a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc index 722607ac05f87b..01e4e47ce67822 100644 --- a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc +++ b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc @@ -95,7 +95,7 @@ This example shows a preconfigured action type with one out-of-the box connector name: 'Server log #xyz' ``` -<1> `enabledActionTypes` excludes the preconfigured action type to prevent creating and deleting connectors. +<1> `enabledActionTypes` excludes the preconfigured action type to prevent creating and deleting connectors. For more details check <>. <2> `preconfigured` is the setting for defining the list of available connectors for the preconfigured action type. [[managing-pre-configured-action-types]] diff --git a/docs/user/alerting/alerting-getting-started.asciidoc b/docs/user/alerting/alerting-getting-started.asciidoc index 0a7c17576de3d3..e824cea76563b3 100644 --- a/docs/user/alerting/alerting-getting-started.asciidoc +++ b/docs/user/alerting/alerting-getting-started.asciidoc @@ -157,7 +157,7 @@ Pre-packaged *alert types* simplify setup, hide the details complex domain-speci If you are using an *on-premises* Elastic Stack deployment: -* In the kibana.yml configuration file, add the <> setting. +* In the kibana.yml configuration file, add the <> setting. * For emails to have a footer with a link back to {kib}, set the <> configuration setting. If you are using an *on-premises* Elastic Stack deployment with <>: diff --git a/docs/user/alerting/alerting-production-considerations.asciidoc b/docs/user/alerting/alerting-production-considerations.asciidoc index 0442b760669cc6..605c611a4936f4 100644 --- a/docs/user/alerting/alerting-production-considerations.asciidoc +++ b/docs/user/alerting/alerting-production-considerations.asciidoc @@ -4,7 +4,7 @@ {kib} alerting run both alert checks and actions as persistent background tasks managed by the Kibana Task Manager. This has two major benefits: -* *Persistence*: all task state and scheduling is stored in {es}, so if {kib} is restarted, alerts and actions will pick up where they left off. Task definitions for alerts and actions are stored in the index specified by `xpack.task_manager.index` (defaults to `.kibana_task_manager`). It is important to have at least 1 replica of this index for production deployments, since if you lose this index all scheduled alerts and actions are also lost. +* *Persistence*: all task state and scheduling is stored in {es}, so if {kib} is restarted, alerts and actions will pick up where they left off. Task definitions for alerts and actions are stored in the index specified by <> (defaults to `.kibana_task_manager`). It is important to have at least 1 replica of this index for production deployments, since if you lose this index all scheduled alerts and actions are also lost. * *Scaling*: multiple {kib} instances can read from and update the same task queue in {es}, allowing the alerting and action load to be distributed across instances. In cases where a {kib} instance no longer has capacity to run alert checks or actions, capacity can be increased by adding additional {kib} instances. [float] @@ -12,7 +12,7 @@ {kib} background tasks are managed by: -* Polling an {es} task index for overdue tasks at 3 second intervals. This interval can be changed using the `xpack.task_manager.poll_interval` setting. +* Polling an {es} task index for overdue tasks at 3 second intervals. This interval can be changed using the <> setting. * Tasks are then claiming them by updating them in the {es} index, using optimistic concurrency control to prevent conflicts. Each {kib} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval. * Tasks are run on the {kib} server. * In the case of alerts which are recurring background checks, upon completion the task is scheduled again according to the <>. diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 77a4e5cc41ef29..2e4b22c06f7622 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -101,29 +101,9 @@ image::images/alert-flyout-add-action.png[You can add multiple actions on an ale [NOTE] ============================================== -Actions are not required on alerts. In some cases you may want to run an alert without actions first to understand its behavior, and configure actions later. +Actions are not required on alerts. In some cases you may want to run an alert without actions first to understand its behavior, and <> later. ============================================== -[float] -[[actions-configuration]] -=== Global actions configuration -Some actions configuration options apply to all actions. -If you are using an *on-prem* Elastic Stack deployment, you can set these in the kibana.yml file. -If you are using a cloud deployment, you can set these via the console. - -Here's a list of the available global configuration options and an explanation of what each one does: - -* `xpack.actions.enabled`: Feature toggle that enables Actions in {kib}. Default: `true` -* `xpack.actions.allowedHosts`: Specifies an array of host names which actions such as email, Slack, PagerDuty, and webhook can connect to. An element of * indicates any host can be connected to. An empty array indicates no hosts can be connected to. Default: [ {asterisk} ] -* `xpack.actions.enabledActionTypes`: Specifies an array of action types that are enabled. An {asterisk} indicates all action types registered are enabled. The action types that {kib} provides are `.email`, `.index`, `.jira`, `.pagerduty`, `.resilient`, `.server-log`, `.servicenow`, `.servicenow-sir`, `.slack`, `.teams`, and `.webhook`. Default: [ {asterisk} ] -* `xpack.actions.preconfigured`: Specifies preconfigured action IDs and configs. Default: {} -* `xpack.actions.proxyUrl`: Specifies the proxy URL to use, if using a proxy for actions. -* `xpack.actions.proxyHeader`: Specifies HTTP headers for proxy, if using a proxy for actions. -* `xpack.actions.proxyRejectUnauthorizedCertificates`: Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. -* `xpack.actions.rejectUnauthorized`: Set to `false` to bypass certificate validation for actions. - -*NOTE:* As an alternative to both `xpack.actions.proxyRejectUnauthorizedCertificates` and `xpack.actions.rejectUnauthorized`, the OS level environment variable `NODE_EXTRA_CA_CERTS` can be set to point to a file that contains the root CA(s) needed for certificates to be trusted. - [float] === Managing alerts diff --git a/x-pack/plugins/triggers_actions_ui/README.md b/x-pack/plugins/triggers_actions_ui/README.md index 61cad0fc7fd7b5..54e627d384936b 100644 --- a/x-pack/plugins/triggers_actions_ui/README.md +++ b/x-pack/plugins/triggers_actions_ui/README.md @@ -1149,7 +1149,7 @@ triggersActionsUi.actionTypeRegistry.register(getSomeNewActionType()); ## Create and register new action type UI -Before starting the UI implementation, the [server side registration](https://github.com/elastic/kibana/tree/master/x-pack/plugins/actions#kibana-actions-configuration) should be done first. +Before starting the UI implementation, the [server side registration](https://github.com/elastic/kibana/tree/master/x-pack/plugins/actions#action-types) should be done first. Action type UI is expected to be defined as `ActionTypeModel` object. From defc5e27da0b39dc2f42bf11468152e9ab7efebf Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Mon, 1 Mar 2021 14:56:26 -0800 Subject: [PATCH 2/5] fixed due to comments --- docs/settings/alert-action-settings.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc index b650e4cc062f77..cdfe234672a6be 100644 --- a/docs/settings/alert-action-settings.asciidoc +++ b/docs/settings/alert-action-settings.asciidoc @@ -40,8 +40,7 @@ You can configure the following settings in the `kibana.yml` file. [cols="2*<"] |=== - -| `xpack.actions.enabled` {ess-icon} +| `xpack.actions.enabled` | Feature toggle that enables Actions in {kib}. It defaults to `true`. | `xpack.actions.allowedHosts` {ess-icon} @@ -60,10 +59,11 @@ You can configure the following settings in the `kibana.yml` file. | `xpack.actions.proxyUrl` {ess-icon} | Specifies the proxy URL to use, if using a proxy for actions. By default is no proxy used. -| `xpack.actions.proxyHeader` {ess-icon} +| `xpack.actions.proxyHeaders` {ess-icon} | Specifies HTTP headers for proxy, if using a proxy for actions. -| `xpack.actions.proxyRejectUnauthorizedCertificates` {ess-icon} +a|`xpack.actions.` +`proxyRejectUnauthorizedCertificates` {ess-icon} | Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. It defaults to `true`. | `xpack.actions.rejectUnauthorized` {ess-icon} From 8895764d35e4bda99f05ad3c0a86998b04dccedf Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Mon, 1 Mar 2021 15:02:04 -0800 Subject: [PATCH 3/5] fixed due to comments --- docs/user/alerting/alerting-getting-started.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/alerting/alerting-getting-started.asciidoc b/docs/user/alerting/alerting-getting-started.asciidoc index e824cea76563b3..48622f03b8a0e8 100644 --- a/docs/user/alerting/alerting-getting-started.asciidoc +++ b/docs/user/alerting/alerting-getting-started.asciidoc @@ -157,7 +157,7 @@ Pre-packaged *alert types* simplify setup, hide the details complex domain-speci If you are using an *on-premises* Elastic Stack deployment: -* In the kibana.yml configuration file, add the <> setting. +* In the kibana.yml configuration file, add the <> setting. * For emails to have a footer with a link back to {kib}, set the <> configuration setting. If you are using an *on-premises* Elastic Stack deployment with <>: From c0c7ef623cfbcba262bbcb154d1b4232ed98f581 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Mon, 1 Mar 2021 16:17:57 -0800 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com> --- docs/settings/alert-action-settings.asciidoc | 14 +++++++------- .../pre-configured-connectors.asciidoc | 2 +- .../alerting-production-considerations.asciidoc | 8 ++++---- docs/user/alerting/defining-alerts.asciidoc | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc index cdfe234672a6be..9abad71e19896b 100644 --- a/docs/settings/alert-action-settings.asciidoc +++ b/docs/settings/alert-action-settings.asciidoc @@ -41,7 +41,7 @@ You can configure the following settings in the `kibana.yml` file. [cols="2*<"] |=== | `xpack.actions.enabled` - | Feature toggle that enables Actions in {kib}. It defaults to `true`. + | Feature toggle that enables Actions in {kib}. Defaults to `true`. | `xpack.actions.allowedHosts` {ess-icon} | A list of hostnames that {kib} is allowed to connect to when built-in actions are triggered. It defaults to `[*]`, allowing any host, but keep in mind the potential for SSRF attacks when hosts are not explicitly added to the allowed hosts. An empty list `[]` can be used to block built-in actions from making any external connections. + @@ -54,22 +54,22 @@ You can configure the following settings in the `kibana.yml` file. Disabled action types will not appear as an option when creating new connectors, but existing connectors and actions of that type will remain in {kib} and will not function. | `xpack.actions.preconfigured` - | Specifies preconfigured action IDs and configs. It defaults to {}. + | Specifies preconfigured action IDs and configs. Defaults to {}. | `xpack.actions.proxyUrl` {ess-icon} - | Specifies the proxy URL to use, if using a proxy for actions. By default is no proxy used. + | Specifies the proxy URL to use, if using a proxy for actions. By default, no proxy is used. | `xpack.actions.proxyHeaders` {ess-icon} - | Specifies HTTP headers for proxy, if using a proxy for actions. + | Specifies HTTP headers for the proxy, if using a proxy for actions. a|`xpack.actions.` `proxyRejectUnauthorizedCertificates` {ess-icon} - | Set to `false` to bypass certificate validation for proxy, if using a proxy for actions. It defaults to `true`. + | Set to `false` to bypass certificate validation for the proxy, if using a proxy for actions. Defaults to `true`. | `xpack.actions.rejectUnauthorized` {ess-icon} - | Set to `false` to bypass certificate validation for actions. It defaults to `true`. + + | Set to `false` to bypass certificate validation for actions. Defaults to `true`. + + - As an alternative to both `xpack.actions.proxyRejectUnauthorizedCertificates` and `xpack.actions.rejectUnauthorized`, the OS level environment variable `NODE_EXTRA_CA_CERTS` can be set to point to a file that contains the root CA(s) needed for certificates to be trusted. + As an alternative to setting both `xpack.actions.proxyRejectUnauthorizedCertificates` and `xpack.actions.rejectUnauthorized`, you can point the OS level environment variable `NODE_EXTRA_CA_CERTS` to a file that contains the root CAs needed to trust certificates. |=== diff --git a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc index 01e4e47ce67822..a748a06398ef3a 100644 --- a/docs/user/alerting/action-types/pre-configured-connectors.asciidoc +++ b/docs/user/alerting/action-types/pre-configured-connectors.asciidoc @@ -95,7 +95,7 @@ This example shows a preconfigured action type with one out-of-the box connector name: 'Server log #xyz' ``` -<1> `enabledActionTypes` excludes the preconfigured action type to prevent creating and deleting connectors. For more details check <>. +<1> `enabledActionTypes` prevents the preconfigured action type from creating and deleting connectors. For more details, check <>. <2> `preconfigured` is the setting for defining the list of available connectors for the preconfigured action type. [[managing-pre-configured-action-types]] diff --git a/docs/user/alerting/alerting-production-considerations.asciidoc b/docs/user/alerting/alerting-production-considerations.asciidoc index 605c611a4936f4..58b4a263459b32 100644 --- a/docs/user/alerting/alerting-production-considerations.asciidoc +++ b/docs/user/alerting/alerting-production-considerations.asciidoc @@ -2,9 +2,9 @@ [[alerting-production-considerations]] == Production considerations -{kib} alerting run both alert checks and actions as persistent background tasks managed by the Kibana Task Manager. This has two major benefits: +{kib} alerting runs both alert checks and actions as persistent background tasks managed by the Kibana Task Manager. This has two major benefits: -* *Persistence*: all task state and scheduling is stored in {es}, so if {kib} is restarted, alerts and actions will pick up where they left off. Task definitions for alerts and actions are stored in the index specified by <> (defaults to `.kibana_task_manager`). It is important to have at least 1 replica of this index for production deployments, since if you lose this index all scheduled alerts and actions are also lost. +* *Persistence*: all task state and scheduling is stored in {es}, so if you restart {kib}, alerts and actions will pick up where they left off. Task definitions for alerts and actions are stored in the index specified by <>. The default is `.kibana_task_manager`. You must have at least one replica of this index for production deployments. If you lose this index, all scheduled alerts and actions are lost. * *Scaling*: multiple {kib} instances can read from and update the same task queue in {es}, allowing the alerting and action load to be distributed across instances. In cases where a {kib} instance no longer has capacity to run alert checks or actions, capacity can be increased by adding additional {kib} instances. [float] @@ -12,7 +12,7 @@ {kib} background tasks are managed by: -* Polling an {es} task index for overdue tasks at 3 second intervals. This interval can be changed using the <> setting. +* Polling an {es} task index for overdue tasks at 3 second intervals. You can change this interval using the <> setting. * Tasks are then claiming them by updating them in the {es} index, using optimistic concurrency control to prevent conflicts. Each {kib} instance can run a maximum of 10 concurrent tasks, so a maximum of 10 tasks are claimed each interval. * Tasks are run on the {kib} server. * In the case of alerts which are recurring background checks, upon completion the task is scheduled again according to the <>. @@ -32,4 +32,4 @@ For details on the settings that can influence the performance and throughput of [float] === Deployment considerations -{es} and {kib} instances use the system clock to determine the current time. To ensure schedules are triggered when expected, you should synchronize the clocks of all nodes in the cluster using a time service such as http://www.ntp.org/[Network Time Protocol]. \ No newline at end of file +{es} and {kib} instances use the system clock to determine the current time. To ensure schedules are triggered when expected, you should synchronize the clocks of all nodes in the cluster using a time service such as http://www.ntp.org/[Network Time Protocol]. diff --git a/docs/user/alerting/defining-alerts.asciidoc b/docs/user/alerting/defining-alerts.asciidoc index 2e4b22c06f7622..e809120a8e6e11 100644 --- a/docs/user/alerting/defining-alerts.asciidoc +++ b/docs/user/alerting/defining-alerts.asciidoc @@ -101,7 +101,7 @@ image::images/alert-flyout-add-action.png[You can add multiple actions on an ale [NOTE] ============================================== -Actions are not required on alerts. In some cases you may want to run an alert without actions first to understand its behavior, and <> later. +Actions are not required on alerts. You can run an alert without actions to understand its behavior, and then <> later. ============================================== [float] From 187d6f35e8cc22d1c29450f3fa5d277e5c12a7c7 Mon Sep 17 00:00:00 2001 From: Yuliia Naumenko Date: Mon, 1 Mar 2021 16:22:19 -0800 Subject: [PATCH 5/5] fixed due to comments --- docs/settings/alert-action-settings.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/settings/alert-action-settings.asciidoc b/docs/settings/alert-action-settings.asciidoc index 9abad71e19896b..6813a77776b5ba 100644 --- a/docs/settings/alert-action-settings.asciidoc +++ b/docs/settings/alert-action-settings.asciidoc @@ -60,7 +60,7 @@ You can configure the following settings in the `kibana.yml` file. | Specifies the proxy URL to use, if using a proxy for actions. By default, no proxy is used. | `xpack.actions.proxyHeaders` {ess-icon} - | Specifies HTTP headers for the proxy, if using a proxy for actions. + | Specifies HTTP headers for the proxy, if using a proxy for actions. Defaults to {}. a|`xpack.actions.` `proxyRejectUnauthorizedCertificates` {ess-icon}