From 447cb1948de1b11594ec6de5310b10e41eb82292 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Thu, 24 Mar 2022 09:31:34 -0700 Subject: [PATCH 1/9] Added notifications plugin Signed-off-by: keithhc2 --- _notifications-plugin/api.md | 829 +++++++++++++++++++++++++++++++++ _notifications-plugin/index.md | 135 ++++++ 2 files changed, 964 insertions(+) create mode 100644 _notifications-plugin/api.md create mode 100644 _notifications-plugin/index.md diff --git a/_notifications-plugin/api.md b/_notifications-plugin/api.md new file mode 100644 index 0000000000..f1102b9e9d --- /dev/null +++ b/_notifications-plugin/api.md @@ -0,0 +1,829 @@ +--- +layout: default +title: API +nav_order: 50 +has_children: false +redirect_from: +--- + +# Notifications API + +If you don’t want to use OpenSearch Dashboards, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages. + +If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages. + +--- + +#### Table of contents +1. TOC +{:toc} + +--- + +## List supported features + +Lists supported channel types and email limitations, such as accepted file sizes and connect timeouts. + +#### Sample Request + +```json +GET /_plugins/_notifications/features +``` + +#### Sample Response + +```json +{ + "config_type_list" : [ + "slack", + "chime", + "webhook", + "email", + "sns", + "smtp_account", + "email_group" + ], + "plugin_features" : { + "opensearch.notifications.spi.email.sizeLimit" : "10000000", + "opensearch.notifications.spi.email.minimumHeaderLength" : "160", + "opensearch.notifications.spi.http.maxConnections" : "60", + "opensearch.notifications.spi.http.maxConnectionPerRoute" : "20", + "opensearch.notifications.spi.http.connectionTimeout" : "5000", + "opensearch.notifications.spi.http.socketTimeout" : "50000", + "opensearch.notifications.spi.tooltip_support" : "false" + } +} +``` + +## Create channel + +Creates a notification channel. + +#### Sample Request + +```json +POST /_plugins/_notifications/configs/ +{ + "id": "sample-id", + "name": "sample-name", + "config": { + "name": "Sample Slack Channel", + "description": "This is a Slack channel", + "config_type": "slack", + "feature_list": [ + "reports" + ], + "is_enabled": true, + "slack": { + "url": "https://sample-slack-webhook" + } + } +} +``` + +The create channel API operation accepts the following fields in its request body: + + +Field | Data Type | Description | Required +:--- | :--- | :--- | :--- +config | Object | Contains all of relevant information such as channel name, configuration type, and plugin source. | Yes +name | String | Name of the channel. | Yes +description | String | The channel's description. | No +config_type | String | The destination of your notification. Valid options are `chime`, `sns`, `slack`, `email`, and `webhook`. | Yes +feature_list | Array of strings | The OpenSearch plugins you want to associate with the channel. Valid options are `alerting`, `reports`, and `index_management`. | Yes +is_enabled | Boolean | Whether to enable to channel to receive and send notifications. Default is true. | No + +The create channel operation accepts multiple `config_types` as possible notification destinations, so just follow the format for your preferred `config_type`. + +```json +"sns": { + "topic_arn": "", + "role_arn": "" //optional +} +"slack": { + "url": "https://sample-chime-webhoook" +} +"chime": { + "url": "https://sample-amazon-chime-webhoook" +} +"webhook" : { + "url" : "https://sample-webhook", + "header_params" : { + "Content-Type" : "application/json" + }, + "method" : "POST" +} +"email" : { + "email_account_id" : "", + "recipient_list" : [ + "sample@email.com" + ], + "email_group_id_list" : [ + "" + ] +} +``` + +The following example demonstrates how to create a channel using email as a `config_type`: + +```json +POST /_plugins/_notifications/configs/ +{ + "id": "sample-email-id", + "name": "sample-name", + "config": { + "name": "Sample Email Channel", + "description": "Sample email description", + "config_type": "email", + "feature_list": [ + "reports" + ], + "is_enabled" : true, + "email" : { + "email_account_id" : "", + "recipient_list" : [ + "sample@email.com" + ] + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +## Send test notification + +Sends a test notification. + +#### Sample Request + +```json +GET _plugins/_notifications/events +``` + +#### Sample Response + +```json +{ + "event_id" : "" +} +``` + +## List all sent notifications + +Lists all sent notifications. + +#### Sample Request + +```json +GET _plugins/_notifications/events +``` + +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 10, + "total_hit_relation" : "eq", + "event_list" : [ + { + "event_id" : "", + "last_updated_time_ms" : 1629226098683, + "created_time_ms" : 1629226098222, + "tenant" : "__user__", + "event" : { + "event_source" : { + "title" : "Sample notification event", + "reference_id" : "", + "feature" : "reporting", + "severity" : "info", + "tags" : [ ] + }, + "status_list" : [ + { + "config_id" : "", + "config_type" : "webhook", + "config_name" : "This is a config name", + "email_recipient_status" : [ ], + "delivery_status" : { + "status_code" : "200", + "status_text" : "Example status text" + } + } + ] + } + } + ] +} +``` + +To filter down your results, specify the following parameters in your request path. All parameters are optional. + +Parameter | Description +:--- | :--- +event_id_list | Comma-separated list of notification event IDs to retrieve. +from_index | The starting index to search from. +max_items | The maximum number of items the request should return. +sort_order | Specifies the direction to sort results in. Valid options are asc and desc. +sort_field | Field to sort results with. +last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. +created_time_ms | The unix time in milliseconds of when the channel was created. +event_source.reference_id | The notification event's reference ID. +event_source.feature | The OpenSearch plugin that triggered the notification event. +event_source.severity | The severity of the of the notification event. Valid options are info and high. +event_source.tags | Any tags associated with the notification event. +event_source.title | The notification event's title. +status_list.config_id | The channel's config ID. +status_list.config_type | The channel's notification type. Valid options are slack, chime, sns, email, and webhook. +status_list.config_name | The channel's name. +status_list.delivery_status.status_code | The notification event's delivery status code. +status_list.delivery_status.status_text | Status text related to the notification's delivery status. +status_list.email_recipient_status.recipient | Any statuses associated with email recipients. +status_list.email_recipient_status.delivery_status.status_code | Any status codes associated with email recipients. +status_list.email_recipient_status.delivery_status.status_text | Status text related to email recipients' delivery statuses. + +For example, the following request returns a notification sent to Slack that was triggered by the Alerting plugin. + +#### Sample Request + +```json +GET _plugins/_notifications/events?status_list.config_type=slack&event_source.feature=alerting +``` + +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 1, + "total_hit_relation" : "eq", + "event_list" : [ + { + "event_id" : "", + "last_updated_time_ms" : 1630354617088, + "created_time_ms" : 1630354617082, + "tenant" : "__user__", + "event" : { + "event_source" : { + "title" : "Sample notification event", + "reference_id" : "", + "feature" : "alerting", + "severity" : "info", + "tags" : [ ] + }, + "status_list" : [ + { + "config_id" : "", + "config_type" : "slack", + "config_name" : "Sample Slack Channel", + "email_recipient_status" : [ ], + "delivery_status" : { + "status_code" : "200", + "status_text" : "Example status text" + } + } + ] + } + } + ] +} +``` + +## List all channels + +Lists all notification channels. + +#### Sample Request + +```json +GET _plugins/_notifications/configs +``` + +#### Sample Response* + +```json +{ + "start_index" : 0, + "total_hits" : 3, + "total_hit_relation" : "eq", + "config_list" : [ + { + "config_id" : "f8gxMnsBgleqOc4sp278", + "last_updated_time_ms" : 1628634720251, + "created_time_ms" : 1628634720251, + "tenant" : "__user__", + "config" : { + "name" : "Testing Gmail Channel", + "description" : "", + "config_type" : "smtp_account", + "feature_list" : [ + "alerting", + "index_management", + "reports" + ], + "is_enabled" : true, + "smtp_account" : { + "host" : "smtp.gmail.com", + "port" : 80, + "method" : "ssl", + "from_address" : "example@gmail.com" + } + } + }, + { + "config_id" : "g20bN3sBUeso9oKNgb8C", + "last_updated_time_ms" : 1628717154562, + "created_time_ms" : 1628717154562, + "tenant" : "__user__", + "config" : { + "name" : "Slack Channel 1", + "description" : "This is an optional description", + "config_type" : "slack", + "feature_list" : [ + "reports" + ], + "is_enabled" : true, + "slack" : { + "url" : "https://hooks.slack.com/a-sample-url" + } + } + }, + { + "config_id" : "0W0kN3sBUeso9oKNur-_", + "last_updated_time_ms" : 1628717759167, + "created_time_ms" : 1628717759167, + "tenant" : "__user__", + "config" : { + "name" : "Another Sample Slack Channel", + "description" : "Sample description", + "config_type" : "slack", + "feature_list" : [ + "reports" + ], + "is_enabled" : true, + "slack" : { + "url" : "https://hooks.slack.com/another-sample-url" + } + } + } + ] +} +``` + +You can include query parameters in your request path to filter the notification channels this request returns. All parameters are optional. + +Parameter | Description +:--- | :--- +config_id Unique | identifier of a channel. +config_id_list | Comma-separated list of channel IDs. +from_index | The starting index to search from. +max_items | The maximum amount of items to return in your request. +sort_order | Specifies the direction to sort results in. Valid options are asc and desc. +sort_field | Field to sort results with. +last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. +created_time_ms | The unix time in milliseconds of when the channel was created. +is_enabled | Whether the channel is enabled. +config_type | The channel type. Valid options are slack, chime, sns, email, and webhook. +feature_list | The OpenSearch plugin associated with the channel. +name | The channel's name. +description | The channel's description. +email.email_account_id | The sender emails the channel uses. +email.email_group_id_list | The email groups the channel uses. +smtp_account.method | The email encryption method. +slack.url | The Slack channel's URL. +chime.url | The Amazon Chime connection's URL. +webhook.url | The webhook's URL. +email.recipient_list | The channel's recipient list. +email_group.recipient_list | The channel's list of email recipient groups. +smtp_account.host | The domain of the smtp account. +smtp_account.from_address | The email account's sender address. +smtp_account.recipient_list | The channel's recipient list. +sns.topic_arn | The Amazon SNS topic's ARN. +sns.role_arn | The Amazon SNS topic's role ARN. +ses_account.region | The Amazon SES account's region. +ses_account.role_arn | The Amazon SES account's role ARN. +ses_account.from_address | The Amazon SES account's sender email address. + +## Get channel configuration + +Get a channel’s configuration by config_id. + +#### Sample Request + +```json +GET _plugins/_notifications/configs/ +``` +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 1, + "total_hit_relation" : "eq", + "config_list" : [ + { + "config_id" : "", + "last_updated_time_ms" : 1628634720251, + "created_time_ms" : 1628634720251, + "tenant" : "__user__", + "config" : { + "name" : "Testing Gmail Channel", + "description" : "", + "config_type" : "smtp_account", + "feature_list" : [ + "alerting", + "index_management", + "reports" + ], + "is_enabled" : true, + "smtp_account" : { + "host" : "smtp.gmail.com", + "port" : 80, + "method" : "ssl", + "from_address" : "example@gmail.com" + } + } + } + ] +} +``` + +## Update channel configuration + +Updates a channel’s configuration. + +#### Sample Request + +```json +PUT _plugins/_notifications/configs/ +{ + "config": { + "name": "Slack Channel", + "description": "This is an updated channel configuration", + "config_type": "slack", + "feature_list": [ + "index_management" + ], + "is_enabled": true, + "slack": { + "url": "https://hooks.slack.com/sample-url" + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +#### Delete channel + +Deletes a channel. + +#### Sample Request + +```json +DELETE /_plugins/_notifications/configs/ +``` + +#### Sample Response* + +```json +{ + "delete_response_list" : { + "" : "OK" + } +} +``` + +You can also submit a comma-separated list of channel IDs you want to delete, and OpenSearch deletes all of the specified notification channels. + +#### Sample Request + +```json +DELETE /_plugins/_notifications/configs/?config_id_list=,,... +``` + +#### Sample Response + +```json +{ + "delete_response_list" : { + "" : "OK", + "" : "OK", + "" : "OK" + } +} +``` + +#### Create email sender + +Creates an email sender for use when creating an email channel. + +#### Sample Request + +```json +POST _plugins/_notifications/configs +{ + "config": { + "name": "test_email_08-20-2021", + "config_type": "smtp_account", + "feature_list" : [ + "alerting" + ], + "is_enabled" : true, + "smtp_account": { + "host": "smtp.gmail.com", + "port": 465, + "method": "ssl", + "from_address": "test@gmail.com" + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +## Get email sender + +Retrieves an email sender. + +#### Sample Request + +```json +GET _plugins/_notifications/configs/ +``` + +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 1, + "total_hit_relation" : "eq", + "config_list" : [ + { + "config_id" : "6j2jZXsBnB7tlos71NNu", + "last_updated_time_ms" : 1629497886595, + "created_time_ms" : 1629497840749, + "tenant" : "__user__", + "config" : { + "name" : "Sample_Email_2021", + "description" : "", + "config_type" : "smtp_account", + "feature_list" : [ + "alerting" + ], + "is_enabled" : true, + "smtp_account" : { + "host" : "smtp.gmail.com", + "port" : 465, + "method" : "ssl", + "from_address" : "address@gmail.com" + } + } + } + ] +} +``` + +## Update email sender + +Updates an email sender with new fields. + +#### Sample Request + +```json +PUT _plugins/_notifications/configs/ +{ + "config": { + "name": "This is a new name", + "config_type": "smtp_account", + "feature_list" : [ + "alerting" + ], + "is_enabled" : false, + "smtp_account": { + "host": "smtp.gmail.com", + "port": 587, + "method": "ssl", + "from_address": "new_address@gmail.com" + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +## Delete email sender + +Deletes an email sender. + +#### Sample Request + +```json +DELETE _plugins/_notifications/configs/ +``` + +#### Sample Response + +```json +{ + "delete_response_list" : { + "" : "OK" + } +} +``` + +To delete multiple email senders, specify all of the necessary IDs in a comma-separated list. + +#### Sample Request + +```json +DELETE _plugins/_notifications/configs/?config_id_list=,, +``` + +#### Sample Response + +```json +{ + "delete_response_list" : { + "" : "OK", + "" : "OK", + "" : "OK", + "" : "OK" + } +} +``` + +## Create email recipient group + +Creates an email recipient group + +#### Sample Request + +```json +POST _plugins/_notifications/configs/ +{ + "config": { + "name": "Sample Email Group Name", + "description": "This is an email group", + "config_type": "email_group", + "feature_list": [ + "alerting" + ], + "is_enabled": true, + "email_group": { + "recipient_list": [ + "some_address@email.com" + ] + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +## Get email recipient group + +Returns an email recipient group + +#### Sample Request + +```json +GET _plugins/_notifications/configs/ +``` + +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 1, + "total_hit_relation" : "eq", + "config_list" : [ + { + "config_id" : "", + "last_updated_time_ms" : 1630106022155, + "created_time_ms" : 1630106022155, + "tenant" : "__user__", + "config" : { + "name" : "Sample Email Group Name", + "description" : "This is an email group", + "config_type" : "email_group", + "feature_list" : [ + "alerting" + ], + "is_enabled" : true, + "email_group" : { + "recipient_list" : [ + "some_address@email.com" + ] + } + } + } + ] +} +``` + +## Update email recipient group + +Updates an email recipient group + +#### Sample Request + +```json +PUT _plugins/_notifications/configs/ +{ + "config": { + "name": "This is an updated email group", + "description": "This is an updated description", + "config_type": "email_group", + "feature_list": [ + "alerting" + ], + "is_enabled": true, + "email_group": { + "recipient_list": [ + "some_address@email.com" + ] + } + } +} +``` + +#### Sample Response + +```json +{ + "config_id" : "" +} +``` + +## Delete email recipient group + +Deletes an email recipient group + +#### Sample Request + +```json +DELETE _plugins/_notifications/configs/ +``` + +#### Sample Response + +```json +{ + "delete_response_list" : { + "" : "OK" + } +} +``` + +The delete email group operation also supports deleting multiple email groups with one request. + +#### Sample Request + +```json +DELETE _plugins/_notifications/configs/?config_id_list=, +``` + +#### Sample Response + +```json +{ + "delete_response_list" : { + "" : "OK", + "" : "OK" + } +} +``` diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md new file mode 100644 index 0000000000..73b7d30726 --- /dev/null +++ b/_notifications-plugin/index.md @@ -0,0 +1,135 @@ +--- +layout: default +title: Notifications +nav_order: 1 +has_children: false +redirect_from: + - /notifications-plugin/ +--- + +# Notifications + +The notifications plugin provides a central location for all of your notifications from OpenSearch plugins. Using the plugin, you can configure which communication service you want to use as well as see relevant statistics and troubleshooting information. Currently, the plugin supports sending notifications from the Alerting, Index State Management (ISM), and Reporting plugins. + +You can use either OpenSearch Dashboards or the REST API to configure notifications. Dashboards offers a more organized way of selecting a channel type and selecting which OpenSearch plugin sources you want to use, whereas the REST API lets you programmatically define your notification channels for better versioning and reuse later on. + +1. Use the Dashboards UI to first create a channel that receives notifications from other plugins. Supported communication channels include Amazon Chime, Amazon SNS, Email, Slack, and custom webhooks when selecting how you want the plugin to send notifications. After you’ve configured your channel and plugin sources, send messages and start tracking your notifications from the notifications plugin’s Dashboard. +2. Use the Notifications REST API to configure all of the settings of your channel. To use the API, you must prepare your notification’s details beforehand, which contains the notification’s name, description, channel type, which OpenSearch plugins to use as sources, and other associated URLs or groups. + +## Create a channel + +In OpenSearch Dashboards, choose **Notifications**, **Channels**, and then **Create channel**. + +1. In the **Name and description** section, specify a name and optional description for your channel. +2. In the **Configurations** section, select the channel type and enter the necessary information for each type. For more information about configuring a channel that uses Amazon SNS or emails, refer to the sections below. If you want to use Amazon Chime or Slack, you need to specify the webhook URL. For more information about using webhooks, see the documentation for [Slack](https://api.slack.com/messaging/webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html). + +If you want to use custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with a key of Authorization and a value of `Basic `. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`. + +This information is stored in plain text in the OpenSearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other OpenSearch users. + +1. In the **Availability** section, select the OpenSearch plugins you want to use with the notification channel. +2. Choose **Create**. + +### Amazon SNS as a channel type + +OpenSearch supports Amazon SNS for notifications. This integration with Amazon SNS means that, in addition to the other channel types, the notifications plugin can send emails, text messages, and even run AWS Lambda functions using SNS topics. For more information about Amazon SNS, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). + +The notifications plugin currently supports two ways of user authentication: + +1. Providing the user with full access to Amazon SNS. +2. Letting the user assume an IAM role that has permissions to Amazon SNS. Once you configure the notification channel to use the right Amazon SNS permissions, select the OpenSearch plugins that can trigger notifications. + +### Provide full Amazon SNS access permissions + +If you want to provide full Amazon SNS access to the IAM user, ensure that the user has the following permissions. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Action": [ + "sns:*" + ], + "Effect": "Allow", + "Resource": "*" + } + ] +} +``` + +### Assuming an IAM role with Amazon SNS permissions + +If you want to let the user send notifications without directly having full permissions to Amazon SNS, let the user assume a role that does have the necessary permissions. + +The IAM user must have the following permissions to assume a role. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ec2:Describe*", + "iam:ListRoles", + "sts:AssumeRole" + ], + "Resource": "*" + } + ] +} +``` + +Then add this policy into the IAM user’s trust relationship to actually assume the role. + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam:::user/", + }, + "Action": "sts:AssumeRole" + } + ] +} +``` + + +## Email as a channel type + +To send or receive notifications with emails, choose **Email** as the channel type. Next, select at least one sender and default recipient. If you want to send notifications to more than a few people at a time, select a recipient group. If the Notifications plugin doesn’t currently have the necessary senders or groups, you can add them by choosing **Create sender** or **Create recipient group**. + +### Create a sender + +1. Specify a unique name to associate with the sender. +2. Enter an email address, its host (for example, smtp.gmail.com), and the port. +3. Choose an encryption method, or use the default value of None. However, most email providers require SSL or TLS, which requires a username and password in the OpenSearch keystore. Refer to Authenticate sender account to learn more. +4. Choose **Create** to save the configuration and create the sender. You can create a sender even before you add your credentials to the OpenSearch keystore. However, you must authenticate each sender account before you use the the sender in your channel configuration. + +### Create a recipient group + +1. After choosing **Create recipient group**, enter a unique name to associate with the email group and an optional description. +2. Select or enter the emails you want to add to the recipient group. +3. Choose **Create**. + +### Authenticate sender account + +If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the CLI. Run the following commands (in your OpenSearch directory) to enter your username and password. The <sender_name> is the name you entered for **Sender** earlier. + +```json +./bin/opensearch-keystore add plugins.alerting.destination.email..username +./bin/opensearch-keystore add plugins.alerting.destination.email..password +``` + +To change or update your credentials (after you’ve added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch: + +```json +POST _nodes/reload_secure_settings +{ + "secure_settings_password": "1234" +} +``` From a3f2b7ff2d01ee915664a8be77bcdbacfc9d3636 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 18 May 2022 11:37:47 -0700 Subject: [PATCH 2/9] Changed behavior in ISM and Alerting, and added more details Signed-off-by: keithhc2 --- _config.yml | 6 + _im-plugin/ism/policies.md | 20 +- _monitoring-plugins/alerting/monitors.md | 76 +-- _notifications-plugin/api.md | 788 ++++++----------------- _notifications-plugin/index.md | 16 +- 5 files changed, 215 insertions(+), 691 deletions(-) diff --git a/_config.yml b/_config.yml index 63d4cb50d4..4f161714a8 100644 --- a/_config.yml +++ b/_config.yml @@ -51,6 +51,9 @@ collections: monitoring-plugins: permalink: /:collection/:path/ output: true + notifications-plugin: + permalink: /:collection/:path/ + output: true clients: permalink: /:collection/:path/ output: true @@ -90,6 +93,9 @@ just_the_docs: monitoring-plugins: name: Monitoring plugins nav_fold: true + notifications-plugin: + name: Notifications plugin + nav_fold: true clients: name: Clients and tools nav_fold: true diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index 1d8f44b1ba..d36ccf287f 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -441,7 +441,7 @@ For information on writing cron expressions, see [Cron expression reference]({{s ## Error notifications The `error_notification` operation sends you a notification if your managed index fails. -It notifies a single destination with a custom message. +It notifies a single destination or [notification channel]({{site.url}}{{site.baseurl}}/notifications-plugin/index) with a custom message. Set up error notifications at the policy level: @@ -459,7 +459,8 @@ Set up error notifications at the policy level: Parameter | Description | Type | Required :--- | :--- |:--- |:--- | -`destination` | The destination URL. | `Slack, Amazon Chime, or webhook URL` | Yes +`destination` | The destination URL. | `Slack, Amazon Chime, or webhook URL` | Yes if `channel` isn't specified +`channel` | A notification channel's ID | `string` | Yes if `destination` isn't specified` `message_template` | The text of the message. You can add variables to your messages using [Mustache templates](https://mustache.github.io/mustache.5.html). | `object` | Yes The destination system **must** return a response otherwise the `error_notification` operation throws an error. @@ -515,6 +516,21 @@ The destination system **must** return a response otherwise the `error_notificat } ``` +#### Example 4: Using a notification channel + +```json +{ + "error_notification": { + "channel": { + "id": "some-channel-config-id" + }, + "message_template": { + "source": "The index {% raw %}{{ctx.index}}{% endraw %} failed during policy execution." + } + } +} +``` + You can use the same options for `ctx` variables as the [notification](#notification) operation. ## Sample policy with ISM template diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 1b81fe9933..9ddc2ab2db 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -23,76 +23,7 @@ Monitor | A job that runs on a defined schedule and queries OpenSearch indices. Trigger | Conditions that, if met, generate *alerts*. Alert | An event associated with a trigger. When an alert is created, the trigger performs *actions*, which can include sending a notification. Action | The information that you want the monitor to send out after being triggered. Actions have a *destination*, a message subject, and a message body. -Destination | A reusable location for an action. Supported locations are Amazon Chime, Email, Slack, or custom webhook. - - ---- - -## Create destinations - -1. Choose **Alerting**, **Destinations**, **Add destination**. -1. Specify a name for the destination so that you can identify it later. -1. For **Type**, choose Slack, Amazon Chime, custom webhook, or [email](#email-as-a-destination). - -For Email, refer to the [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. See the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html) to learn more about webhooks. - -If you're using custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with a key of `Authorization` and a value of `Basic `. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`. - -This information is stored in plain text in the OpenSearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other OpenSearch users. - - -### Email as a destination - -To send or receive an alert notification as an email, choose **Email** as the destination type. Next, add at least one sender and recipient. We recommend adding email groups if you want to notify more than a few people of an alert. You can configure senders and recipients using **Manage senders** and **Manage email groups**. - - -#### Manage senders - -Senders are email accounts from which the alerting plugin sends notifications. - -To configure a sender email, do the following: - -1. After you choose **Email** as the destination type, choose **Manage senders**. -1. Choose **Add sender**, **New sender** and enter a unique name. -1. Enter the email address, SMTP host (e.g. `smtp.gmail.com` for a Gmail account), and the port. -1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which require a username and password in OpenSearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more. -1. Choose **Save** to save the configuration and create the sender. You can create a sender even before you add your credentials to the OpenSearch keystore. However, you must [authenticate each sender account](#authenticate-sender-account) before you use the destination to send your alert. - -You can reuse senders across many different destinations, but each destination only supports one sender. - - -#### Manage email groups or recipients - -Use email groups to create and manage reusable lists of email addresses. For example, one alert might email the DevOps team, whereas another might email the executive team and the engineering team. - -You can enter individual email addresses or an email group in the **Recipients** field. - -1. After you choose **Email** as the destination type, choose **Manage email groups**. Then choose **Add email group**, **New email group**. -1. Enter a unique name. -1. For recipient emails, enter any number of email addresses. -1. Choose **Save**. - - -#### Authenticate sender account - -If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the CLI. Run the following commands (in your OpenSearch directory) to enter your username and password. The `` is the name you entered for **Sender** earlier. - -```bash -./bin/opensearch-keystore add plugins.alerting.destination.email..username -./bin/opensearch-keystore add plugins.alerting.destination.email..password -``` - -Note: Keystore settings are node-specific. You must run these commands on each node. -{: .note} - -To change or update your credentials (after you've added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch: - -```json -POST _nodes/reload_secure_settings -{ - "secure_settings_password": "1234" -} -``` +Channel | A notifications channel to use in an action. See [notifications]({{site.url}}{{site.baseurl}}/notifications-plugin/index) for more information. --- @@ -321,7 +252,6 @@ Variable | Data Type | Description :--- | :--- | : --- `ctx.trigger.actions.id` | String | The action's ID. `ctx.trigger.actions.name` | String | The action's name. -`ctx.trigger.actions.destination_id`| String | The alert destination's ID. `ctx.trigger.actions.message_template.source` | String | The message to send in the alert. `ctx.trigger.actions.message_template.lang` | String | The scripting language used to define the message. Must be Mustache. `ctx.trigger.actions.throttle_enabled` | Boolean | Whether throttling is enabled for this trigger. See [adding actions](#add-actions) for more information about throttling. @@ -356,7 +286,7 @@ If you don't want to receive notifications for alerts, you don't have to add act {: .tip } 1. Specify a name for the action. -1. Choose a destination. +1. Choose a [notification channel]({{site.url}}{{site.baseurl}}/notifications-plugin/index). 1. Add a subject and body for the message. You can add variables to your messages using [Mustache templates](https://mustache.github.io/mustache.5.html). You have access to `ctx.action.name`, the name of the current action, as well as all [trigger variables](#available-variables). @@ -367,7 +297,7 @@ If you don't want to receive notifications for alerts, you don't have to add act {% raw %}{ "text": "Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}}" }{% endraw %} ``` - In this case, the message content must conform to the `Content-Type` header in the [custom webhook](#create-destinations). + In this case, the message content must conform to the `Content-Type` header in the [custom webhook]({{site.url}}{{site.baseurl}}/notifcations-plugin/index). 1. If you're using a bucket-level monitor, you can choose whether the monitor should perform an action for each execution or for each alert. 1. (Optional) Use action throttling to limit the number of notifications you receive within a given span of time. diff --git a/_notifications-plugin/api.md b/_notifications-plugin/api.md index f1102b9e9d..3b13f9c8a2 100644 --- a/_notifications-plugin/api.md +++ b/_notifications-plugin/api.md @@ -8,9 +8,7 @@ redirect_from: # Notifications API -If you don’t want to use OpenSearch Dashboards, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages. - -If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the REST API to create, configure, and delete notification channels, email senders, and email recipient groups, as well as send test messages. +If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the REST API to define, configure, and delete notification channels, as well as send test messages. --- @@ -20,9 +18,9 @@ If you want to programmatically define your notifications channels and sources f --- -## List supported features +## List supported channel types -Lists supported channel types and email limitations, such as accepted file sizes and connect timeouts. +Lists supported channel types. #### Sample Request @@ -34,28 +32,106 @@ GET /_plugins/_notifications/features ```json { - "config_type_list" : [ - "slack", - "chime", - "webhook", - "email", - "sns", - "smtp_account", - "email_group" + "allowed_config_type_list" : [ + "slack", + "chime", + "webhook", + "email", + "sns", + "ses_account", + "smtp_account", + "email_group" ], "plugin_features" : { - "opensearch.notifications.spi.email.sizeLimit" : "10000000", - "opensearch.notifications.spi.email.minimumHeaderLength" : "160", - "opensearch.notifications.spi.http.maxConnections" : "60", - "opensearch.notifications.spi.http.maxConnectionPerRoute" : "20", - "opensearch.notifications.spi.http.connectionTimeout" : "5000", - "opensearch.notifications.spi.http.socketTimeout" : "50000", - "opensearch.notifications.spi.tooltip_support" : "false" + "tooltip_support" : "true" } } ``` -## Create channel +## List all configurations + +Lists all configurations. + +#### Sample Request + +```json +GET _plugins/_notifications/configs +``` + +#### Sample Response + +```json +{ + "start_index" : 0, + "total_hits" : 2, + "total_hit_relation" : "eq", + "config_list" : [ + { + "config_id" : "sample-id", + "last_updated_time_ms" : 1652760532774, + "created_time_ms" : 1652760532774, + "config" : { + "name" : "Sample Slack Channel", + "description" : "This is a Slack channel", + "config_type" : "slack", + "is_enabled" : true, + "slack" : { + "url" : "https://sample-slack-webhook" + } + } + }, + { + "config_id" : "sample-id2", + "last_updated_time_ms" : 1652760735380, + "created_time_ms" : 1652760735380, + "config" : { + "name" : "Test chime channel", + "description" : "A test chime channel", + "config_type" : "chime", + "is_enabled" : true, + "chime" : { + "url" : "https://sample-chime-webhook" + } + } + } + ] +} +``` + +You can include query parameters in your request path to filter the notification channels this request returns. All parameters are optional. + +Parameter | Description +:--- | :--- +config_id | identifier of a channel. +config_id_list | Comma-separated list of channel IDs. +from_index | The starting index to search from. +max_items | The maximum amount of items to return in your request. +sort_order | Specifies the direction to sort results in. Valid options are asc and desc. +sort_field | Field to sort results with. +last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. +created_time_ms | The unix time in milliseconds of when the channel was created. +is_enabled | Whether the channel is enabled. +config_type | The channel type. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. +name | The channel's name. +description | The channel's description. +email.email_account_id | The sender emails the channel uses. +email.email_group_id_list | The email groups the channel uses. +email.recipient_list | The channel's recipient list. +email_group.recipient_list | The channel's list of email recipient groups. +smtp_account.method | The email encryption method. +slack.url | The Slack channel's URL. +chime.url | The Amazon Chime connection's URL. +webhook.url | The webhook's URL. +smtp_account.host | The domain of the smtp account. +smtp_account.from_address | The email account's sender address. +smtp_account.method | The smtp account's encryption method. +sns.topic_arn | The Amazon SNS topic's ARN. +sns.role_arn | The Amazon SNS topic's role ARN. +ses_account.region | The Amazon SES account's region. +ses_account.role_arn | The Amazon SES account's role ARN. +ses_account.from_address | The Amazon SES account's sender email address. + +## Create channel configuration Creates a notification channel. @@ -64,15 +140,12 @@ Creates a notification channel. ```json POST /_plugins/_notifications/configs/ { - "id": "sample-id", + "config_id": "sample-id", "name": "sample-name", "config": { "name": "Sample Slack Channel", "description": "This is a Slack channel", "config_type": "slack", - "feature_list": [ - "reports" - ], "is_enabled": true, "slack": { "url": "https://sample-slack-webhook" @@ -83,17 +156,16 @@ POST /_plugins/_notifications/configs/ The create channel API operation accepts the following fields in its request body: - Field | Data Type | Description | Required :--- | :--- | :--- | :--- +config_id | String | The config's custom ID. | No config | Object | Contains all of relevant information such as channel name, configuration type, and plugin source. | Yes name | String | Name of the channel. | Yes description | String | The channel's description. | No -config_type | String | The destination of your notification. Valid options are `chime`, `sns`, `slack`, `email`, and `webhook`. | Yes -feature_list | Array of strings | The OpenSearch plugins you want to associate with the channel. Valid options are `alerting`, `reports`, and `index_management`. | Yes -is_enabled | Boolean | Whether to enable to channel to receive and send notifications. Default is true. | No +config_type | String | The destination of your notification. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. | Yes +is_enabled | Boolean | Whether to enable to channel for sending and receiving notifications. Default is true. | No -The create channel operation accepts multiple `config_types` as possible notification destinations, so just follow the format for your preferred `config_type`. +The create channel operation accepts multiple `config_types` as possible notification destinations, so follow the format for your preferred `config_type`. ```json "sns": { @@ -106,22 +178,39 @@ The create channel operation accepts multiple `config_types` as possible notific "chime": { "url": "https://sample-amazon-chime-webhoook" } -"webhook" : { - "url" : "https://sample-webhook", - "header_params" : { - "Content-Type" : "application/json" - }, - "method" : "POST" +"webhook": { + "url": "https://custom-webhook-test-url.com:8888/test-path?params1=value1¶ms2=value2" } -"email" : { - "email_account_id" : "", - "recipient_list" : [ - "sample@email.com" - ], - "email_group_id_list" : [ - "" +"smtp_account": { + "host": "test-host.com", + "port": 123, + "method": "start_tls", + "from_address": "test@email.com" +} +"ses_account": { + "region": "us-east-1", + "role_arn": "arn:aws:iam::012345678912:role/NotificationsSESRole", + "from_address": "test@email.com" +} +"email_group": { //Email recipient group + "recipient_list": [ + { + "recipient": "test-email1@test.com" + }, + { + "recipient": "test-email2@test.com" + } ] } +"email": { //The channel that sends emails + "email_account_id": "", + "recipient_list": [ + { + "recipient": "custom.email@test.com" + } + ], + "email_group_id_list": [] +} ``` The following example demonstrates how to create a channel using email as a `config_type`: @@ -135,9 +224,6 @@ POST /_plugins/_notifications/configs/ "name": "Sample Email Channel", "description": "Sample email description", "config_type": "email", - "feature_list": [ - "reports" - ], "is_enabled" : true, "email" : { "email_account_id" : "", @@ -157,259 +243,6 @@ POST /_plugins/_notifications/configs/ } ``` -## Send test notification - -Sends a test notification. - -#### Sample Request - -```json -GET _plugins/_notifications/events -``` - -#### Sample Response - -```json -{ - "event_id" : "" -} -``` - -## List all sent notifications - -Lists all sent notifications. - -#### Sample Request - -```json -GET _plugins/_notifications/events -``` - -#### Sample Response - -```json -{ - "start_index" : 0, - "total_hits" : 10, - "total_hit_relation" : "eq", - "event_list" : [ - { - "event_id" : "", - "last_updated_time_ms" : 1629226098683, - "created_time_ms" : 1629226098222, - "tenant" : "__user__", - "event" : { - "event_source" : { - "title" : "Sample notification event", - "reference_id" : "", - "feature" : "reporting", - "severity" : "info", - "tags" : [ ] - }, - "status_list" : [ - { - "config_id" : "", - "config_type" : "webhook", - "config_name" : "This is a config name", - "email_recipient_status" : [ ], - "delivery_status" : { - "status_code" : "200", - "status_text" : "Example status text" - } - } - ] - } - } - ] -} -``` - -To filter down your results, specify the following parameters in your request path. All parameters are optional. - -Parameter | Description -:--- | :--- -event_id_list | Comma-separated list of notification event IDs to retrieve. -from_index | The starting index to search from. -max_items | The maximum number of items the request should return. -sort_order | Specifies the direction to sort results in. Valid options are asc and desc. -sort_field | Field to sort results with. -last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. -created_time_ms | The unix time in milliseconds of when the channel was created. -event_source.reference_id | The notification event's reference ID. -event_source.feature | The OpenSearch plugin that triggered the notification event. -event_source.severity | The severity of the of the notification event. Valid options are info and high. -event_source.tags | Any tags associated with the notification event. -event_source.title | The notification event's title. -status_list.config_id | The channel's config ID. -status_list.config_type | The channel's notification type. Valid options are slack, chime, sns, email, and webhook. -status_list.config_name | The channel's name. -status_list.delivery_status.status_code | The notification event's delivery status code. -status_list.delivery_status.status_text | Status text related to the notification's delivery status. -status_list.email_recipient_status.recipient | Any statuses associated with email recipients. -status_list.email_recipient_status.delivery_status.status_code | Any status codes associated with email recipients. -status_list.email_recipient_status.delivery_status.status_text | Status text related to email recipients' delivery statuses. - -For example, the following request returns a notification sent to Slack that was triggered by the Alerting plugin. - -#### Sample Request - -```json -GET _plugins/_notifications/events?status_list.config_type=slack&event_source.feature=alerting -``` - -#### Sample Response - -```json -{ - "start_index" : 0, - "total_hits" : 1, - "total_hit_relation" : "eq", - "event_list" : [ - { - "event_id" : "", - "last_updated_time_ms" : 1630354617088, - "created_time_ms" : 1630354617082, - "tenant" : "__user__", - "event" : { - "event_source" : { - "title" : "Sample notification event", - "reference_id" : "", - "feature" : "alerting", - "severity" : "info", - "tags" : [ ] - }, - "status_list" : [ - { - "config_id" : "", - "config_type" : "slack", - "config_name" : "Sample Slack Channel", - "email_recipient_status" : [ ], - "delivery_status" : { - "status_code" : "200", - "status_text" : "Example status text" - } - } - ] - } - } - ] -} -``` - -## List all channels - -Lists all notification channels. - -#### Sample Request - -```json -GET _plugins/_notifications/configs -``` - -#### Sample Response* - -```json -{ - "start_index" : 0, - "total_hits" : 3, - "total_hit_relation" : "eq", - "config_list" : [ - { - "config_id" : "f8gxMnsBgleqOc4sp278", - "last_updated_time_ms" : 1628634720251, - "created_time_ms" : 1628634720251, - "tenant" : "__user__", - "config" : { - "name" : "Testing Gmail Channel", - "description" : "", - "config_type" : "smtp_account", - "feature_list" : [ - "alerting", - "index_management", - "reports" - ], - "is_enabled" : true, - "smtp_account" : { - "host" : "smtp.gmail.com", - "port" : 80, - "method" : "ssl", - "from_address" : "example@gmail.com" - } - } - }, - { - "config_id" : "g20bN3sBUeso9oKNgb8C", - "last_updated_time_ms" : 1628717154562, - "created_time_ms" : 1628717154562, - "tenant" : "__user__", - "config" : { - "name" : "Slack Channel 1", - "description" : "This is an optional description", - "config_type" : "slack", - "feature_list" : [ - "reports" - ], - "is_enabled" : true, - "slack" : { - "url" : "https://hooks.slack.com/a-sample-url" - } - } - }, - { - "config_id" : "0W0kN3sBUeso9oKNur-_", - "last_updated_time_ms" : 1628717759167, - "created_time_ms" : 1628717759167, - "tenant" : "__user__", - "config" : { - "name" : "Another Sample Slack Channel", - "description" : "Sample description", - "config_type" : "slack", - "feature_list" : [ - "reports" - ], - "is_enabled" : true, - "slack" : { - "url" : "https://hooks.slack.com/another-sample-url" - } - } - } - ] -} -``` - -You can include query parameters in your request path to filter the notification channels this request returns. All parameters are optional. - -Parameter | Description -:--- | :--- -config_id Unique | identifier of a channel. -config_id_list | Comma-separated list of channel IDs. -from_index | The starting index to search from. -max_items | The maximum amount of items to return in your request. -sort_order | Specifies the direction to sort results in. Valid options are asc and desc. -sort_field | Field to sort results with. -last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. -created_time_ms | The unix time in milliseconds of when the channel was created. -is_enabled | Whether the channel is enabled. -config_type | The channel type. Valid options are slack, chime, sns, email, and webhook. -feature_list | The OpenSearch plugin associated with the channel. -name | The channel's name. -description | The channel's description. -email.email_account_id | The sender emails the channel uses. -email.email_group_id_list | The email groups the channel uses. -smtp_account.method | The email encryption method. -slack.url | The Slack channel's URL. -chime.url | The Amazon Chime connection's URL. -webhook.url | The webhook's URL. -email.recipient_list | The channel's recipient list. -email_group.recipient_list | The channel's list of email recipient groups. -smtp_account.host | The domain of the smtp account. -smtp_account.from_address | The email account's sender address. -smtp_account.recipient_list | The channel's recipient list. -sns.topic_arn | The Amazon SNS topic's ARN. -sns.role_arn | The Amazon SNS topic's role ARN. -ses_account.region | The Amazon SES account's region. -ses_account.role_arn | The Amazon SES account's role ARN. -ses_account.from_address | The Amazon SES account's sender email address. ## Get channel configuration @@ -420,6 +253,7 @@ Get a channel’s configuration by config_id. ```json GET _plugins/_notifications/configs/ ``` + #### Sample Response ```json @@ -428,33 +262,25 @@ GET _plugins/_notifications/configs/ "total_hits" : 1, "total_hit_relation" : "eq", "config_list" : [ - { - "config_id" : "", - "last_updated_time_ms" : 1628634720251, - "created_time_ms" : 1628634720251, - "tenant" : "__user__", - "config" : { - "name" : "Testing Gmail Channel", - "description" : "", - "config_type" : "smtp_account", - "feature_list" : [ - "alerting", - "index_management", - "reports" - ], - "is_enabled" : true, - "smtp_account" : { - "host" : "smtp.gmail.com", - "port" : 80, - "method" : "ssl", - "from_address" : "example@gmail.com" - } + { + "config_id" : "sample-id", + "last_updated_time_ms" : 1652760532774, + "created_time_ms" : 1652760532774, + "config" : { + "name" : "Sample Slack Channel", + "description" : "This is a Slack channel", + "config_type" : "slack", + "is_enabled" : true, + "slack" : { + "url" : "https://sample-slack-webhook" + } + } } - } ] } ``` + ## Update channel configuration Updates a channel’s configuration. @@ -468,9 +294,6 @@ PUT _plugins/_notifications/configs/ "name": "Slack Channel", "description": "This is an updated channel configuration", "config_type": "slack", - "feature_list": [ - "index_management" - ], "is_enabled": true, "slack": { "url": "https://hooks.slack.com/sample-url" @@ -487,7 +310,8 @@ PUT _plugins/_notifications/configs/ } ``` -#### Delete channel + +## Delete channel configuration Deletes a channel. @@ -527,303 +351,51 @@ DELETE /_plugins/_notifications/configs/?config_id_list=," -} -``` - -## Get email sender - -Retrieves an email sender. - -#### Sample Request - -```json -GET _plugins/_notifications/configs/ -``` - -#### Sample Response -```json -{ - "start_index" : 0, - "total_hits" : 1, - "total_hit_relation" : "eq", - "config_list" : [ - { - "config_id" : "6j2jZXsBnB7tlos71NNu", - "last_updated_time_ms" : 1629497886595, - "created_time_ms" : 1629497840749, - "tenant" : "__user__", - "config" : { - "name" : "Sample_Email_2021", - "description" : "", - "config_type" : "smtp_account", - "feature_list" : [ - "alerting" - ], - "is_enabled" : true, - "smtp_account" : { - "host" : "smtp.gmail.com", - "port" : 465, - "method" : "ssl", - "from_address" : "address@gmail.com" - } - } - } - ] -} -``` - -## Update email sender - -Updates an email sender with new fields. - -#### Sample Request - -```json -PUT _plugins/_notifications/configs/ -{ - "config": { - "name": "This is a new name", - "config_type": "smtp_account", - "feature_list" : [ - "alerting" - ], - "is_enabled" : false, - "smtp_account": { - "host": "smtp.gmail.com", - "port": 587, - "method": "ssl", - "from_address": "new_address@gmail.com" - } - } -} -``` - -#### Sample Response - -```json -{ - "config_id" : "" -} -``` - -## Delete email sender - -Deletes an email sender. - -#### Sample Request - -```json -DELETE _plugins/_notifications/configs/ -``` - -#### Sample Response - -```json -{ - "delete_response_list" : { - "" : "OK" - } -} -``` - -To delete multiple email senders, specify all of the necessary IDs in a comma-separated list. - -#### Sample Request - -```json -DELETE _plugins/_notifications/configs/?config_id_list=,, -``` - -#### Sample Response - -```json -{ - "delete_response_list" : { - "" : "OK", - "" : "OK", - "" : "OK", - "" : "OK" - } -} -``` - -## Create email recipient group - -Creates an email recipient group - -#### Sample Request - -```json -POST _plugins/_notifications/configs/ -{ - "config": { - "name": "Sample Email Group Name", - "description": "This is an email group", - "config_type": "email_group", - "feature_list": [ - "alerting" - ], - "is_enabled": true, - "email_group": { - "recipient_list": [ - "some_address@email.com" - ] - } - } -} -``` - -#### Sample Response - -```json -{ - "config_id" : "" -} -``` - -## Get email recipient group +## Send test notification -Returns an email recipient group +Sends a test notification to a channel. #### Sample Request ```json -GET _plugins/_notifications/configs/ +GET _plugins/_notifications/feature/test/ ``` #### Sample Response ```json { - "start_index" : 0, - "total_hits" : 1, - "total_hit_relation" : "eq", - "config_list" : [ - { - "config_id" : "", - "last_updated_time_ms" : 1630106022155, - "created_time_ms" : 1630106022155, - "tenant" : "__user__", - "config" : { - "name" : "Sample Email Group Name", - "description" : "This is an email group", - "config_type" : "email_group", - "feature_list" : [ - "alerting" - ], - "is_enabled" : true, - "email_group" : { - "recipient_list" : [ - "some_address@email.com" - ] - } + "event_source" : { + "title" : "Test Message Title-0Jnlh4ABa4TCWn5C5H2G", + "reference_id" : "0Jnlh4ABa4TCWn5C5H2G", + "severity" : "info", + "tags" : [ ] + }, + "status_list" : [ + { + "config_id" : "0Jnlh4ABa4TCWn5C5H2G", + "config_type" : "slack", + "config_name" : "sample-id", + "email_recipient_status" : [ ], + "delivery_status" : { + "status_code" : "200", + "status_text" : """ + + + + +
+

Example Domain

+

Sample paragraph.

+

TO BE OR NOT TO BE, THAT IS THE QUESTION

+
+ + +""" + } } - } ] } -``` - -## Update email recipient group - -Updates an email recipient group - -#### Sample Request - -```json -PUT _plugins/_notifications/configs/ -{ - "config": { - "name": "This is an updated email group", - "description": "This is an updated description", - "config_type": "email_group", - "feature_list": [ - "alerting" - ], - "is_enabled": true, - "email_group": { - "recipient_list": [ - "some_address@email.com" - ] - } - } -} -``` - -#### Sample Response - -```json -{ - "config_id" : "" -} -``` - -## Delete email recipient group - -Deletes an email recipient group - -#### Sample Request - -```json -DELETE _plugins/_notifications/configs/ -``` -#### Sample Response - -```json -{ - "delete_response_list" : { - "" : "OK" - } -} -``` - -The delete email group operation also supports deleting multiple email groups with one request. - -#### Sample Request - -```json -DELETE _plugins/_notifications/configs/?config_id_list=, -``` - -#### Sample Response - -```json -{ - "delete_response_list" : { - "" : "OK", - "" : "OK" - } -} ``` diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md index 73b7d30726..c81737291a 100644 --- a/_notifications-plugin/index.md +++ b/_notifications-plugin/index.md @@ -9,7 +9,7 @@ redirect_from: # Notifications -The notifications plugin provides a central location for all of your notifications from OpenSearch plugins. Using the plugin, you can configure which communication service you want to use as well as see relevant statistics and troubleshooting information. Currently, the plugin supports sending notifications from the Alerting, Index State Management (ISM), and Reporting plugins. +The notifications plugin provides a central location for all of your notifications from OpenSearch plugins. Using the plugin, you can configure which communication service you want to use as well as see relevant statistics and troubleshooting information. Currently, the plugin supports sending notifications from the Alerting and Index State Management (ISM) plugins. You can use either OpenSearch Dashboards or the REST API to configure notifications. Dashboards offers a more organized way of selecting a channel type and selecting which OpenSearch plugin sources you want to use, whereas the REST API lets you programmatically define your notification channels for better versioning and reuse later on. @@ -18,7 +18,7 @@ You can use either OpenSearch Dashboards or the REST API to configure notificati ## Create a channel -In OpenSearch Dashboards, choose **Notifications**, **Channels**, and then **Create channel**. +In OpenSearch Dashboards, choose **Notifications**, **Channels**, and **Create channel**. 1. In the **Name and description** section, specify a name and optional description for your channel. 2. In the **Configurations** section, select the channel type and enter the necessary information for each type. For more information about configuring a channel that uses Amazon SNS or emails, refer to the sections below. If you want to use Amazon Chime or Slack, you need to specify the webhook URL. For more information about using webhooks, see the documentation for [Slack](https://api.slack.com/messaging/webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html). @@ -101,16 +101,16 @@ Then add this policy into the IAM user’s trust relationship to actually assume ## Email as a channel type -To send or receive notifications with emails, choose **Email** as the channel type. Next, select at least one sender and default recipient. If you want to send notifications to more than a few people at a time, select a recipient group. If the Notifications plugin doesn’t currently have the necessary senders or groups, you can add them by choosing **Create sender** or **Create recipient group**. +To send or receive notifications with emails, choose **Email** as the channel type. Next, select at least one sender and default recipient. To send notifications to more than a few people at a time, select a recipient group. If the Notifications plugin doesn’t currently have the necessary senders or groups, you can add them by first selecting **SMTP sender**, then choose **Create SMTP sender** or **Create recipient group**. Choose **SES sender** to use Amazon Simple Email Service (SES). -### Create a sender +### Create email sender 1. Specify a unique name to associate with the sender. -2. Enter an email address, its host (for example, smtp.gmail.com), and the port. -3. Choose an encryption method, or use the default value of None. However, most email providers require SSL or TLS, which requires a username and password in the OpenSearch keystore. Refer to Authenticate sender account to learn more. -4. Choose **Create** to save the configuration and create the sender. You can create a sender even before you add your credentials to the OpenSearch keystore. However, you must authenticate each sender account before you use the the sender in your channel configuration. +2. Enter an email address, and, if applicable, its host (for example, smtp.gmail.com), and the port. If you're using SES, enter the IAM role ARN of the AWS account to send notifications from, along with the region. +3. Choose an encryption method. Most email providers require SSL or TLS, which requires a username and password in the OpenSearch keystore. See [Authenticate sender account](#authenticate-sender-account) to learn more. Selecting an encryption method is only applicable if you're creating an SMTP sender. +4. Choose **Create** to save the configuration and create the sender. You can create a sender before you add your credentials to the OpenSearch keystore; however, you must [authenticate each sender account](#authenticate-sender-account) before you use the sender in your channel configuration. -### Create a recipient group +### Create email recipient group 1. After choosing **Create recipient group**, enter a unique name to associate with the email group and an optional description. 2. Select or enter the emails you want to add to the recipient group. From f30555ca65623305b656a94ddcc0c187a35be67b Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 18 May 2022 11:55:25 -0700 Subject: [PATCH 3/9] Extra tick Signed-off-by: keithhc2 --- _im-plugin/ism/policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/ism/policies.md b/_im-plugin/ism/policies.md index d36ccf287f..fa05586213 100644 --- a/_im-plugin/ism/policies.md +++ b/_im-plugin/ism/policies.md @@ -460,7 +460,7 @@ Set up error notifications at the policy level: Parameter | Description | Type | Required :--- | :--- |:--- |:--- | `destination` | The destination URL. | `Slack, Amazon Chime, or webhook URL` | Yes if `channel` isn't specified -`channel` | A notification channel's ID | `string` | Yes if `destination` isn't specified` +`channel` | A notification channel's ID | `string` | Yes if `destination` isn't specified `message_template` | The text of the message. You can add variables to your messages using [Mustache templates](https://mustache.github.io/mustache.5.html). | `object` | Yes The destination system **must** return a response otherwise the `error_notification` operation throws an error. From 8529563bab8330007cd3aa9c5514f4c88809da81 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 18 May 2022 17:21:52 -0700 Subject: [PATCH 4/9] Comments Signed-off-by: keithhc2 --- _notifications-plugin/api.md | 14 +++++++------- _notifications-plugin/index.md | 6 +++--- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/_notifications-plugin/api.md b/_notifications-plugin/api.md index 3b13f9c8a2..53662c0aa1 100644 --- a/_notifications-plugin/api.md +++ b/_notifications-plugin/api.md @@ -8,7 +8,7 @@ redirect_from: # Notifications API -If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the REST API to define, configure, and delete notification channels, as well as send test messages. +If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the Notifications REST API to define, configure, and delete notification channels, as well as send test messages. --- @@ -20,7 +20,7 @@ If you want to programmatically define your notifications channels and sources f ## List supported channel types -Lists supported channel types. +Returns a list of supported channel types. #### Sample Request @@ -102,15 +102,15 @@ You can include query parameters in your request path to filter the notification Parameter | Description :--- | :--- -config_id | identifier of a channel. -config_id_list | Comma-separated list of channel IDs. +config_id | Specifies the channel identifier. +config_id_list | Specifies a comma-separated list of channel IDs. from_index | The starting index to search from. max_items | The maximum amount of items to return in your request. -sort_order | Specifies the direction to sort results in. Valid options are asc and desc. +sort_order | Specifies the direction to sort results in. Valid options are `asc` and `desc`. sort_field | Field to sort results with. last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. created_time_ms | The unix time in milliseconds of when the channel was created. -is_enabled | Whether the channel is enabled. +is_enabled | Indicates whether the channel is enabled. config_type | The channel type. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. name | The channel's name. description | The channel's description. @@ -163,7 +163,7 @@ config | Object | Contains all of relevant information such as channel name, con name | String | Name of the channel. | Yes description | String | The channel's description. | No config_type | String | The destination of your notification. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. | Yes -is_enabled | Boolean | Whether to enable to channel for sending and receiving notifications. Default is true. | No +is_enabled | Boolean | Whether the channel is enabled for sending and receiving notifications. Default is true. | No The create channel operation accepts multiple `config_types` as possible notification destinations, so follow the format for your preferred `config_type`. diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md index c81737291a..d743a2dc76 100644 --- a/_notifications-plugin/index.md +++ b/_notifications-plugin/index.md @@ -14,7 +14,7 @@ The notifications plugin provides a central location for all of your notificatio You can use either OpenSearch Dashboards or the REST API to configure notifications. Dashboards offers a more organized way of selecting a channel type and selecting which OpenSearch plugin sources you want to use, whereas the REST API lets you programmatically define your notification channels for better versioning and reuse later on. 1. Use the Dashboards UI to first create a channel that receives notifications from other plugins. Supported communication channels include Amazon Chime, Amazon SNS, Email, Slack, and custom webhooks when selecting how you want the plugin to send notifications. After you’ve configured your channel and plugin sources, send messages and start tracking your notifications from the notifications plugin’s Dashboard. -2. Use the Notifications REST API to configure all of the settings of your channel. To use the API, you must prepare your notification’s details beforehand, which contains the notification’s name, description, channel type, which OpenSearch plugins to use as sources, and other associated URLs or groups. +2. Use the Notifications REST API to configure all of the settings of your channel. To use the API, you must have your notification’s details that contain the notification’s name, description, channel type, which OpenSearch plugins to use as sources, and other associated URLs or groups. ## Create a channel @@ -36,8 +36,8 @@ OpenSearch supports Amazon SNS for notifications. This integration with Amazon S The notifications plugin currently supports two ways of user authentication: -1. Providing the user with full access to Amazon SNS. -2. Letting the user assume an IAM role that has permissions to Amazon SNS. Once you configure the notification channel to use the right Amazon SNS permissions, select the OpenSearch plugins that can trigger notifications. +1. Provide the user with full access to Amazon SNS. +2. Let the user assume an IAM role that has permissions to access Amazon SNS. Once you configure the notification channel to use the right Amazon SNS permissions, select the OpenSearch plugins that can trigger notifications. ### Provide full Amazon SNS access permissions From 32bf7947a84c99179a79547437fb5bba5ad4744f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 23 May 2022 23:46:35 -0700 Subject: [PATCH 5/9] Addressed comments Signed-off-by: keithhc2 --- _monitoring-plugins/alerting/monitors.md | 22 ++++++++++- _notifications-plugin/api.md | 48 ++++++++++++------------ _notifications-plugin/index.md | 39 +++++++++---------- 3 files changed, 64 insertions(+), 45 deletions(-) diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 9ddc2ab2db..67d3478b05 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -23,7 +23,7 @@ Monitor | A job that runs on a defined schedule and queries OpenSearch indices. Trigger | Conditions that, if met, generate *alerts*. Alert | An event associated with a trigger. When an alert is created, the trigger performs *actions*, which can include sending a notification. Action | The information that you want the monitor to send out after being triggered. Actions have a *destination*, a message subject, and a message body. -Channel | A notifications channel to use in an action. See [notifications]({{site.url}}{{site.baseurl}}/notifications-plugin/index) for more information. +Channel | A notification channel to use in an action. See [notifications]({{site.url}}{{site.baseurl}}/notifications-plugin/index) for more information. --- @@ -280,7 +280,7 @@ Variable | Data Type | Description ## Add actions -The final step in creating a monitor is to add one or more actions. Actions send notifications when trigger conditions are met and support [Slack](https://slack.com/), [Amazon Chime](https://aws.amazon.com/chime/), and webhooks. +The final step in creating a monitor is to add one or more actions. Actions send notifications when trigger conditions are met. See the [Notifications plugin]({{site.url}}{{site.baseurl}}/notifications-plugin/index) to see what communication channels are supported. If you don't want to receive notifications for alerts, you don't have to add actions to your triggers. Instead, you can periodically check OpenSearch Dashboards. {: .tip } @@ -322,6 +322,24 @@ After an action sends a message, the content of that message has left the purvie If you want to use the `ctx.results` variable in a message, use `{% raw %}{{ctx.results.0}}{% endraw %}` rather than `{% raw %}{{ctx.results[0]}}{% endraw %}`. This difference is due to how Mustache handles bracket notation. {: .note } +### Questions about destinations + +Q: What plugins do I need installed besides Alerting? + +A: To continue using the notification action in the Alerting plugin, you need to install the backend plugins `notifications-core` and `notifications`. You can also install the Notifications Dashboards plugin to manage Notification channels via OpenSearch Dasboards. + +Q: Can I still create destinations? +A: No, destinations have been deprecated and can no longer be created/edited. + +Q: Will I need to move my destinations to the Notifications plugin? +A: No. To upgrade users, a background process will automatically move destinations to notification channels. These channels will have the same ID as the destinations, and monitor execution will choose the correct ID, so you don't have to make any changes to the monitor's definition. The migrated destinations will be deleted. + +Q: What happens if any destinations fail to migrate? +A: If a destination failed to migrate, the monitor will continue using it until the monitor is migrated to a notification channel. You don't need to do anything in this case. + +Q: Do I need to install the Notifications plugins if monitors can still use destinations? +A: Yes. The fallback on destination is to prevent failures in sending messages if migration fails; however, the Notification plugin is what actually sends the message. Not having the Notification plugin installed will lead to the action failing. + --- diff --git a/_notifications-plugin/api.md b/_notifications-plugin/api.md index 53662c0aa1..b5fd28be23 100644 --- a/_notifications-plugin/api.md +++ b/_notifications-plugin/api.md @@ -8,7 +8,7 @@ redirect_from: # Notifications API -If you want to programmatically define your notifications channels and sources for versioning and reuse, you can use the Notifications REST API to define, configure, and delete notification channels, as well as send test messages. +If you want to programmatically define your notification channels and sources for versioning and reuse, you can use the Notifications REST API to define, configure, and delete notification channels and send test messages. --- @@ -18,9 +18,9 @@ If you want to programmatically define your notifications channels and sources f --- -## List supported channel types +## List supported channel configurations -Returns a list of supported channel types. +To retrieve a list of all supported notification configuration types, send a GET request to the `features` resource. #### Sample Request @@ -48,9 +48,9 @@ GET /_plugins/_notifications/features } ``` -## List all configurations +## List all notification configurations -Lists all configurations. +To retrieve a list of all notification configurations, send a GET request to the `configs` resource. #### Sample Request @@ -98,7 +98,7 @@ GET _plugins/_notifications/configs } ``` -You can include query parameters in your request path to filter the notification channels this request returns. All parameters are optional. +To filter the notification configuration types this request returns, you can refine your query with the following optional path parameters. Parameter | Description :--- | :--- @@ -108,13 +108,13 @@ from_index | The starting index to search from. max_items | The maximum amount of items to return in your request. sort_order | Specifies the direction to sort results in. Valid options are `asc` and `desc`. sort_field | Field to sort results with. -last_updated_time_ms | The unix time in milliseconds of when the channel was last updated. -created_time_ms | The unix time in milliseconds of when the channel was created. +last_updated_time_ms | The Unix time in milliseconds of when the channel was last updated. +created_time_ms | The Unix time in milliseconds of when the channel was created. is_enabled | Indicates whether the channel is enabled. -config_type | The channel type. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. +config_type | The channel type. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, and `email`. name | The channel's name. description | The channel's description. -email.email_account_id | The sender emails the channel uses. +email.email_account_id | The sender email addresses the channel uses. email.email_group_id_list | The email groups the channel uses. email.recipient_list | The channel's recipient list. email_group.recipient_list | The channel's list of email recipient groups. @@ -122,18 +122,18 @@ smtp_account.method | The email encryption method. slack.url | The Slack channel's URL. chime.url | The Amazon Chime connection's URL. webhook.url | The webhook's URL. -smtp_account.host | The domain of the smtp account. +smtp_account.host | The domain of the SMTP account. smtp_account.from_address | The email account's sender address. -smtp_account.method | The smtp account's encryption method. -sns.topic_arn | The Amazon SNS topic's ARN. +smtp_account.method | The SMTP account's encryption method. +sns.topic_arn | The Amazon Simple Notification Service (SNS) topic's ARN. sns.role_arn | The Amazon SNS topic's role ARN. -ses_account.region | The Amazon SES account's region. +ses_account.region | The Amazon Simple Email Service (SES) account's AWS Region. ses_account.role_arn | The Amazon SES account's role ARN. ses_account.from_address | The Amazon SES account's sender email address. ## Create channel configuration -Creates a notification channel. +To create a notification channel configuration, send a POST request to the `configs` resource. #### Sample Request @@ -158,12 +158,12 @@ The create channel API operation accepts the following fields in its request bod Field | Data Type | Description | Required :--- | :--- | :--- | :--- -config_id | String | The config's custom ID. | No -config | Object | Contains all of relevant information such as channel name, configuration type, and plugin source. | Yes +config_id | String | The configuration's custom ID. | No +config | Object | Contains all relevant information, such as channel name, configuration type, and plugin source. | Yes name | String | Name of the channel. | Yes description | String | The channel's description. | No -config_type | String | The destination of your notification. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, `email`. | Yes -is_enabled | Boolean | Whether the channel is enabled for sending and receiving notifications. Default is true. | No +config_type | String | The destination of your notification. Valid options are `sns`, `slack`, `chime`, `webhook`, `smtp_account`, `ses_account`, `email_group`, and `email`. | Yes +is_enabled | Boolean | Indicates whether the channel is enabled for sending and receiving notifications. Default is true. | No The create channel operation accepts multiple `config_types` as possible notification destinations, so follow the format for your preferred `config_type`. @@ -246,7 +246,7 @@ POST /_plugins/_notifications/configs/ ## Get channel configuration -Get a channel’s configuration by config_id. +To get a channel configuration by `config_id`, send a GET request and specify the `config_id` as a path parameter. #### Sample Request @@ -283,7 +283,7 @@ GET _plugins/_notifications/configs/ ## Update channel configuration -Updates a channel’s configuration. +To update a channel configuration, send a POST request to the `configs` resource and specify the channel's `config_id` as a path parameter. Specify the new configuration details in the request body. #### Sample Request @@ -313,7 +313,7 @@ PUT _plugins/_notifications/configs/ ## Delete channel configuration -Deletes a channel. +To delete a channel configuration, send a DELETE request to the `configs` resource and specify the `config_id` as a path parameter. #### Sample Request @@ -321,7 +321,7 @@ Deletes a channel. DELETE /_plugins/_notifications/configs/ ``` -#### Sample Response* +#### Sample Response ```json { @@ -354,7 +354,7 @@ DELETE /_plugins/_notifications/configs/?config_id_list=,`. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`. +If you want to use custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with an authorization key and a value of `Basic `. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`. This information is stored in plain text in the OpenSearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other OpenSearch users. @@ -32,16 +33,16 @@ This information is stored in plain text in the OpenSearch cluster. We will impr ### Amazon SNS as a channel type -OpenSearch supports Amazon SNS for notifications. This integration with Amazon SNS means that, in addition to the other channel types, the notifications plugin can send emails, text messages, and even run AWS Lambda functions using SNS topics. For more information about Amazon SNS, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). +OpenSearch supports Amazon SNS for notifications. This integration with Amazon SNS means that, in addition to the other channel types, the Notifications plugin can send email messages, text messages, and even run AWS Lambda functions using SNS topics. For more information about Amazon SNS, see the [Amazon Simple Notification Service Developer Guide](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). -The notifications plugin currently supports two ways of user authentication: +The Notifications plugin currently supports two ways to authenticate users: 1. Provide the user with full access to Amazon SNS. -2. Let the user assume an IAM role that has permissions to access Amazon SNS. Once you configure the notification channel to use the right Amazon SNS permissions, select the OpenSearch plugins that can trigger notifications. +2. Let the user assume an AWS Identity and Access Management (IAM) role that has permissions to access Amazon SNS. Once you configure the notification channel to use the right Amazon SNS permissions, select the OpenSearch plugins that can trigger notifications. ### Provide full Amazon SNS access permissions -If you want to provide full Amazon SNS access to the IAM user, ensure that the user has the following permissions. +If you want to provide full Amazon SNS access to the IAM user, ensure that the user has the following permissions: ```json { @@ -62,7 +63,7 @@ If you want to provide full Amazon SNS access to the IAM user, ensure that the u If you want to let the user send notifications without directly having full permissions to Amazon SNS, let the user assume a role that does have the necessary permissions. -The IAM user must have the following permissions to assume a role. +The IAM user must have the following permissions to assume a role: ```json { @@ -81,7 +82,7 @@ The IAM user must have the following permissions to assume a role. } ``` -Then add this policy into the IAM user’s trust relationship to actually assume the role. +Then add this policy into the IAM user’s trust relationship to actually assume the role: ```json { @@ -101,31 +102,31 @@ Then add this policy into the IAM user’s trust relationship to actually assume ## Email as a channel type -To send or receive notifications with emails, choose **Email** as the channel type. Next, select at least one sender and default recipient. To send notifications to more than a few people at a time, select a recipient group. If the Notifications plugin doesn’t currently have the necessary senders or groups, you can add them by first selecting **SMTP sender**, then choose **Create SMTP sender** or **Create recipient group**. Choose **SES sender** to use Amazon Simple Email Service (SES). +To send or receive notifications with email, choose **Email** as the channel type. Next, select at least one sender and default recipient. To send notifications to more than a few people at a time, specify multiple email addresses or select a recipient group. If the Notifications plugin doesn’t currently have the necessary senders or groups, you can add them by first selecting **SMTP sender** and then choosing **Create SMTP sender** or **Create recipient group**. Choose **SES sender** to use Amazon Simple Email Service (Amazon SES). ### Create email sender 1. Specify a unique name to associate with the sender. -2. Enter an email address, and, if applicable, its host (for example, smtp.gmail.com), and the port. If you're using SES, enter the IAM role ARN of the AWS account to send notifications from, along with the region. -3. Choose an encryption method. Most email providers require SSL or TLS, which requires a username and password in the OpenSearch keystore. See [Authenticate sender account](#authenticate-sender-account) to learn more. Selecting an encryption method is only applicable if you're creating an SMTP sender. +2. Enter an email address and, if applicable its host (for example, smtp.gmail.com), and the port. If you're using Amazon SES, enter the IAM role Amazon Resource Name (ARN) of the AWS account to send notifications from, along with the AWS Region. +3. Choose an encryption method. Most email providers require Secure Sockets Layer (SSL) or Transport Layer Security (TLS), which require a user name and password in the OpenSearch keystore. See [Authenticate sender account](#authenticate-sender-account) to learn more. Selecting an encryption method is only applicable if you're creating an SMTP sender. 4. Choose **Create** to save the configuration and create the sender. You can create a sender before you add your credentials to the OpenSearch keystore; however, you must [authenticate each sender account](#authenticate-sender-account) before you use the sender in your channel configuration. ### Create email recipient group 1. After choosing **Create recipient group**, enter a unique name to associate with the email group and an optional description. -2. Select or enter the emails you want to add to the recipient group. +2. Select or enter the email addresses you want to add to the recipient group. 3. Choose **Create**. ### Authenticate sender account -If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the CLI. Run the following commands (in your OpenSearch directory) to enter your username and password. The <sender_name> is the name you entered for **Sender** earlier. +If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the command line interface (CLI). Run the following commands (in your OpenSearch directory) to enter your user name and password. The <sender_name> is the name you entered for **Sender** earlier. ```json -./bin/opensearch-keystore add plugins.alerting.destination.email..username -./bin/opensearch-keystore add plugins.alerting.destination.email..password +opensearch.notifications.core.email..username +opensearch.notifications.core.email..password ``` -To change or update your credentials (after you’ve added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch: +To change or update your credentials (after you’ve added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch. ```json POST _nodes/reload_secure_settings From 105ad2448f9e54e3e835c77c4e9967bd3fe61691 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Tue, 24 May 2022 09:10:29 -0700 Subject: [PATCH 6/9] Typo Signed-off-by: keithhc2 --- _monitoring-plugins/alerting/monitors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index 67d3478b05..42722de5a4 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -326,7 +326,7 @@ If you want to use the `ctx.results` variable in a message, use `{% raw %}{{ctx. Q: What plugins do I need installed besides Alerting? -A: To continue using the notification action in the Alerting plugin, you need to install the backend plugins `notifications-core` and `notifications`. You can also install the Notifications Dashboards plugin to manage Notification channels via OpenSearch Dasboards. +A: To continue using the notification action in the Alerting plugin, you need to install the backend plugins `notifications-core` and `notifications`. You can also install the Notifications Dashboards plugin to manage Notification channels via OpenSearch Dashboards. Q: Can I still create destinations? A: No, destinations have been deprecated and can no longer be created/edited. From 7d3a880d748a5b38e51b72b167618dfed7a6b47d Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Tue, 24 May 2022 16:34:47 -0700 Subject: [PATCH 7/9] Addressed some more comments Signed-off-by: keithhc2 --- _notifications-plugin/api.md | 14 +++++++------- _notifications-plugin/index.md | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_notifications-plugin/api.md b/_notifications-plugin/api.md index b5fd28be23..e9263ad020 100644 --- a/_notifications-plugin/api.md +++ b/_notifications-plugin/api.md @@ -224,13 +224,13 @@ POST /_plugins/_notifications/configs/ "name": "Sample Email Channel", "description": "Sample email description", "config_type": "email", - "is_enabled" : true, - "email" : { - "email_account_id" : "", - "recipient_list" : [ - "sample@email.com" - ] - } + "is_enabled": true, + "email": { + "email_account_id": "", + "recipient_list": [ + "sample@email.com" + ] + } } } ``` diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md index 81f5a29a78..6a2484f119 100644 --- a/_notifications-plugin/index.md +++ b/_notifications-plugin/index.md @@ -119,7 +119,7 @@ To send or receive notifications with email, choose **Email** as the channel typ ### Authenticate sender account -If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter these credentials in the OpenSearch keystore using the command line interface (CLI). Run the following commands (in your OpenSearch directory) to enter your user name and password. The <sender_name> is the name you entered for **Sender** earlier. +If your email provider requires SSL or TLS, you must authenticate each sender account before you can send an email. Enter the sender account credentials in the OpenSearch keystore using the command line interface (CLI). Run the following commands (in your OpenSearch directory) to enter your user name and password. The <sender_name> is the name you entered for **Sender** earlier. ```json opensearch.notifications.core.email..username From 3a39c484e752ec22763aaf81de50350244d02e20 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 25 May 2022 08:55:00 -0700 Subject: [PATCH 8/9] Even more comments Signed-off-by: keithhc2 --- _monitoring-plugins/alerting/monitors.md | 2 +- _notifications-plugin/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_monitoring-plugins/alerting/monitors.md b/_monitoring-plugins/alerting/monitors.md index a1f2673777..91730d6b5f 100644 --- a/_monitoring-plugins/alerting/monitors.md +++ b/_monitoring-plugins/alerting/monitors.md @@ -40,7 +40,7 @@ Term | Definition :--- | :--- Monitor | A job that runs on a defined schedule and queries OpenSearch indexes. The results of these queries are then used as input for one or more *triggers*. Trigger | Conditions that, if met, generate *alerts*. -Tag | A label that can be applied to multiple queries to combine them with the logical OR operation in a per document monitor. You can't use tags with other monitor types. +Tag | A label that can be applied to multiple queries to combine them with the logical OR operation in a per document monitor. You cannot use tags with other monitor types. Alert | An event associated with a trigger. When an alert is created, the trigger performs *actions*, which can include sending a notification. Action | The information that you want the monitor to send out after being triggered. Actions have a *destination*, a message subject, and a message body. Channel | A notification channel to use in an action. See [notifications]({{site.url}}{{site.baseurl}}/notifications-plugin/index) for more information. diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md index 6a2484f119..fa98f22254 100644 --- a/_notifications-plugin/index.md +++ b/_notifications-plugin/index.md @@ -107,7 +107,7 @@ To send or receive notifications with email, choose **Email** as the channel typ ### Create email sender 1. Specify a unique name to associate with the sender. -2. Enter an email address and, if applicable its host (for example, smtp.gmail.com), and the port. If you're using Amazon SES, enter the IAM role Amazon Resource Name (ARN) of the AWS account to send notifications from, along with the AWS Region. +2. Enter an email address and, if applicable, its host (for example, smtp.gmail.com) and the port. If you're using Amazon SES, enter the IAM role Amazon Resource Name (ARN) of the AWS account to send notifications from, along with the AWS Region. 3. Choose an encryption method. Most email providers require Secure Sockets Layer (SSL) or Transport Layer Security (TLS), which require a user name and password in the OpenSearch keystore. See [Authenticate sender account](#authenticate-sender-account) to learn more. Selecting an encryption method is only applicable if you're creating an SMTP sender. 4. Choose **Create** to save the configuration and create the sender. You can create a sender before you add your credentials to the OpenSearch keystore; however, you must [authenticate each sender account](#authenticate-sender-account) before you use the sender in your channel configuration. From 822777253d4bd5055d5a1737590d78689be166d6 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Wed, 25 May 2022 09:45:29 -0700 Subject: [PATCH 9/9] Deleted a sentence Signed-off-by: keithhc2 --- _notifications-plugin/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_notifications-plugin/index.md b/_notifications-plugin/index.md index fa98f22254..521d438441 100644 --- a/_notifications-plugin/index.md +++ b/_notifications-plugin/index.md @@ -13,7 +13,7 @@ The Notifications plugin provides a central location for all of your notificatio You can use either OpenSearch Dashboards or the REST API to configure notifications. Dashboards offers a more organized way of selecting a channel type and selecting which OpenSearch plugin sources you want to use, whereas the REST API lets you programmatically define your notification channels for better versioning and reuse later on. -1. Use the Dashboards UI to first create a channel that receives notifications from other plugins. Supported communication channels include Amazon Chime, Amazon Simple Notification Service (Amazon SNS), Amazon Simple Email Service (Amazon SES), email through SMTP, Slack, and custom webhooks when selecting how you want the plugin to send notifications. After you’ve configured your channel and plugin sources, send messages and start tracking your notifications from the Notifications plugin's dashboard. +1. Use the Dashboards UI to first create a channel that receives notifications from other plugins. Supported communication channels include Amazon Chime, Amazon Simple Notification Service (Amazon SNS), Amazon Simple Email Service (Amazon SES), email through SMTP, Slack, and custom webhooks. After you’ve configured your channel and plugin sources, send messages and start tracking your notifications from the Notifications plugin's dashboard. 2. Use the Notifications REST API to configure all of your channel's settings. To use the API, you must have your notification's name, description, channel type, which OpenSearch plugins to use as sources, and other associated URLs or groups.