From 32bf7947a84c99179a79547437fb5bba5ad4744f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 23 May 2022 23:46:35 -0700 Subject: [PATCH] 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 9ddc2ab2..67d3478b 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 53662c0a..b5fd28be 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