From 25e6d2780b08a8abce1af9eb1e924649d8ceb1a4 Mon Sep 17 00:00:00 2001 From: "grafana-delivery-bot[bot]" <132647405+grafana-delivery-bot[bot]@users.noreply.github.com> Date: Tue, 18 Feb 2025 23:05:26 +0100 Subject: [PATCH] [release-11.5.2] Alerting docs: Update `Amazon SNS` integration (#100921) Alerting docs: Update `Amazon SNS` integration (#100754) * Update `Configure Amazon SNS notifications` * Clarify templateable fields * correct prop description (cherry picked from commit e1c1cc34af160178392762b7274d46659478afd2) Co-authored-by: Pepe Cano <825430+ppcano@users.noreply.github.com> --- .../integrations/configure-amazon-sns.md | 186 +++++++----------- 1 file changed, 76 insertions(+), 110 deletions(-) diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md index 84274e64043..9c449640511 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-amazon-sns.md @@ -14,11 +14,32 @@ labels: menuTitle: Amazon SNS title: Configure Amazon SNS for Alerting weight: 100 +refs: + notification-templates: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/template-notifications/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/ + configure-contact-points: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/ + test-contact-point: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/#test-a-contact-point + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/#test-a-contact-point + enable-contact-point-notifications: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/#enable-notifications-for-a-contact-point + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/#enable-notifications-for-a-contact-point --- -# Configure Amazon SNS for Alerting +# Configure Amazon SNS notifications -Use the Grafana Alerting - Amazon SNS integration to send notifications to Amazon SNS when your alerts are firing. You can receive notifications via the various subscriber channels supported by SNS. +Use the Amazon SNS integration in a contact point to send alert notifications to a SNS topic. Then, configure the SNS topic to forward notifications to distinct subscriber channels used in your SNS account. ## Before you begin @@ -27,71 +48,51 @@ Before you begin, ensure you have the following: - **AWS SNS Topic**: An SNS topic to send notifications to. - **AWS IAM Identity with necessary access**: An IAM identity (e.g. user, role) with the necessary permissions to publish messages to the SNS topic. -For an example setup, see [Example Minimal Setup Using Assumed IAM Role]({{< relref "#example-minimal-setup-using-assumed-iam-role" >}}). +For a minimal setup, refer to [Example using an Access Key](#example-using-an-access-key). -## Adding the SNS Contact Point in Grafana +## Configure Amazon SNS for a contact point -With AWS resources configured, proceed to add SNS as a contact point in Grafana. +To create a contact point with a SNS integration, complete the following steps. -- Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. -- Click on **"Add contact point"**. -- **Name**: Enter a descriptive name (e.g., `AWS SNS`). -- Choose **"AWS SNS"** from the list of contact point types. +1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. +1. Click **+ Add contact point**. +1. Enter a name for the contact point. +1. From the **Integration** list, select **AWS SNS**. +1. Set up the required [settings](#sns-settings) for your SNS configuration. +1. Click **Save contact point**. -### 2. Configure SNS Settings +For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points). -#### SNS Settings +## SNS Settings - **The Amazon SNS API URL**: (Optional) The SNS API URL, e.g., `https://sns.us-east-2.amazonaws.com`. If not specified, the SNS API URL from the SNS SDK will be used. - **Signature Version (sigv4)**: Configures AWS's Signature Verification 4 signing process to sign requests. - **Region**: (Optional) The AWS region. If blank, the region from the default credentials chain is used. - - **Access Key**: The AWS API access key. - - **Secret Key**: The AWS API secret key. + - **Access Key** : (Optional) The AWS API access key. + - **Secret Key**: (Optional) The AWS API secret key. + > Both `Access Key` and `Secret Key` must be provided together or left blank together. + > + > If left blank, Grafana searches for credentials using the default credentials chain, including environment variables (`AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`), the shared credential file, and EC2 instance roles. - **Profile**: (Optional) Named AWS profile used to authenticate. - **Role ARN**: (Optional) The ARN of an AWS IAM role to assume for authentication, serving as an alternative to using AWS API keys. - **SNS topic ARN**: (Optional) If you don't specify this value, you must specify a value for the `Phone number` or `Target ARN`. If you are using a FIFO SNS topic you should set a message group interval longer than 5 minutes to prevent messages with the same group key being deduplicated by the SNS default deduplication window. - **Phone number**: (Optional) Phone number if message is delivered via SMS in E.164 format. If you don't specify this value, you must specify a value for the `SNS topic ARN` or `Target ARN`. - **Target ARN**: (Optional) The mobile platform endpoint ARN if message is delivered via mobile notifications. If you don't specify this value, you must specify a value for the `SNS topic ARN` or `Phone number`. -- **Subject**: (Optional) Customize the subject line or use the default template. This field is templateable. -- **Message**: (Optional) Customize the message content or use the default template. This field is templateable. +- **Subject**: (Optional) Customize the subject. This field supports [notification templates](ref:notification-templates) and, by default, uses the default title template (`default.title`). It **cannot be an empty string**. +- **Message**: (Optional) Customize the message. This field supports [notification templates](ref:notification-templates) and, by default, uses the default message template (`default.message`). - **Attributes**: (Optional) Add any SNS message attributes. -{{< admonition type="note" >}} -Both `Access Key` and `Secret Key` must be provided together or left blank together. If blank it defaults to a chain of credential -providers to search for credentials in environment variables, shared credential file, and EC2 Instance Roles. +## Example using an Access Key -Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. -{{< /admonition >}} +This section outlines a minimal setup to configure Amazon SNS with Alerting. -### 3. Test & Save the Contact Point - -- Click **"Test"** to verify that the SNS configuration is working correctly. -- After the test is successful, click **"Save contact point"** to add the SNS contact point. - -### 4. Next steps - -The SNS contact point is ready to receive alert notifications. - -To add this contact point to your alert, complete the following steps. - -1. In Grafana, navigate to **Alerting** > **Alert rules**. -1. Edit or create a new alert rule. -1. Scroll down to the **Configure labels and notifications** section. -1. Under Notifications click **Select contact point**. -1. From the drop-down menu, select the previously created contact point. -1. **Click Save rule and exit**. - -## Example Minimal Setup Using Assumed IAM Role - -This section outlines a minimal setup to configure SNS with Grafana using an assumed IAM Role. - -### 1. Create an SNS Topic +### 1. Create an SNS Topic and Email Subscriber 1. **Navigate to SNS in AWS Console**: - Go to the [Amazon SNS Console](https://console.aws.amazon.com/sns/v3/home). -2. **Create a new topic** [[AWS Documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html)]: +2. **Create a new topic**: - On the **Topics** page, choose **"Create topic"**. - Select **"Standard"** as the type. @@ -99,105 +100,70 @@ This section outlines a minimal setup to configure SNS with Grafana using an ass - **Encryption**: Leave disabled for this minimal setup. - Click **"Create topic"**. -3. (Optional) **Add an email subscriber to help test** [[AWS Documentation](https://docs.aws.amazon.com/sns/latest/dg/sns-email-notifications.html)]: +3. (Optional) **Add an email subscriber to help test**: - Within your newly created topic, click on **"Create subscription"**. - **Protocol**: Choose `Email`. - **Endpoint**: Enter your email address to receive test notifications. - Click **"Create subscription"**. - **Confirm Subscription**: Check your email and confirm the subscription by clicking the provided link. -### 2. Create an IAM Role +### 2. Create an IAM Policy, User, and Access Key 1. **Navigate to IAM in AWS Console**: - Go to the [IAM Console](https://console.aws.amazon.com/iam/home). -2. **Create a new role** [[AWS Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)]: +2. **Create a new policy**: - - On the **Roles** page, choose **"Create role"**. - - **Trusted Entity**: Select **"This account"**. - - Click **"Next"** until the end, name it (e.g., `GrafanaSNSRole`), and click **"Create role"**. - -3. **Attach Inline Policy**: - - - After creating the role, select it and navigate to the **"Permissions"** tab. - - Click on **"Add permission"** > **"Create inline policy"**. + - On the **Policies** page, choose **"Create policy"**. - Switch to the **"JSON"** tab and paste the following policy, replacing `Resource` with your SNS topic ARN: - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": ["sns:Publish", "sns:GetTopicAttributes"], - "Resource": "arn:aws:sns:::" - } - ] - } - ``` + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["sns:Publish", "sns:GetTopicAttributes"], + "Resource": "arn:aws:sns:::" + } + ] + } + ``` - Click **"Next"**, name it (e.g., `SNSPublishPolicy`), and click **"Create policy"**. -### 3. Create an IAM Policy - -1. **Create a new policy to allow assuming the above IAM role** [[AWS Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)]: - - - In the IAM Console, on the **Policies** page, choose **"Create policy"**. - - Switch to the **"JSON"** tab and paste the following policy, replacing `Resource` with the ARN of the role you created earlier: - - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam:::role/GrafanaSNSRole" - } - ] - } - ``` - -2. **Review and Create**: - - Click **"Next"**, name it (e.g., `AssumeSNSRolePolicy`), and click **"Create policy"**. - -### 4. Create an IAM User - -1. **Create a new IAM user to assume the above role** [[AWS Documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)]: +3. **Create a new IAM user and assign the policy** - In the IAM Console, on the **Users** page, choose **"Create user"**. - - Enter a **User name**, e.g., `grafana-sns-user`. + - Enter a **User name**, e.g., `alerting-sns-user`. - Click **"Next"**. - - Select **"Attach policies directly"**. - - Search for the policy you created earlier (`AssumeSNSRolePolicy`) and select it. + - In **Set permissions**, select **"Attach policies directly"**. + - Search for the policy you created earlier (`SNSPublishPolicy`) and select it. - Click **"Next"** , and click **"Create user"**. -2. **Generate credentials**: +4. **Create an Access Key**: - Within your newly created user, click on **"Create access key"**. - Select an appropriate use-case, e.g., `Application running outside AWS`. - Click **"Next"** , and click **"Create access key"**. - - **Save Credentials**: Note the **Access key ID** and **Secret access key**. You'll need these for Grafana's configuration. + - **Save Credentials**: Note the **Access key ID** and **Secret access key** that are required in the next step. -### 5. Add the SNS Contact Point in Grafana +### 3. Configure the SNS Contact Point in Grafana -After creating the IAM user and obtaining the necessary credentials, proceed to [configure the SNS contact point in Grafana]({{< relref "#adding-the-sns-contact-point-in-grafana" >}}) using the following details: +Follow the steps in [configure Amazon SNS for a contact point](#configure-amazon-sns-for-a-contact-point), using the settings below and replacing the placeholders with the SNS and IAM values created in the previous steps. -- **The Amazon SNS API URL**: `https://sns.us-east-1.amazonaws.com` +- **The Amazon SNS API URL**: `https://sns..amazonaws.com` - **Signature Version (sigv4)**: - - **Region**: `us-east-1` + - **Region**: `` - **Access Key**: ``. - **Secret Key**: `` - - **Role ARN**: `arn:aws:iam:::role/GrafanaSNSRole` -- **SNS topic ARN**: `arn:aws:sns:::My-Topic` +- **SNS topic ARN**: `arn:aws:sns:::` -{{< admonition type="note" >}} -Replace the placeholder values (`https://sns.us-east-1.amazonaws.com`, `us-east-1`, ``, ``, `arn:aws:iam:::role/GrafanaSNSRole`, `arn:aws:sns:::My-Topic`) with your actual AWS credentials and ARNs. -{{< /admonition >}} +[Test the contact point](ref:test-contact-point) to ensure it's working, or [enable notifications](ref:enable-contact-point-notifications) for it. ## Additional Resources +- [Configure contact points](ref:configure-contact-points) - [Amazon SNS Documentation](https://docs.aws.amazon.com/sns/index.html) -- [AWS IAM Documentation](https://docs.aws.amazon.com/iam/index.html) -- [Prometheus Alertmanager SNS Integration](https://prometheus.io/docs/alerting/configuration/#sns_config) -- [Cloudwatch AWS Authentication]({{< relref "../../../../datasources/aws-cloudwatch/aws-authentication" >}}) +- [Amazon IAM Documentation](https://docs.aws.amazon.com/iam/index.html) +- [Prometheus Alertmanager SNS Configuration](https://prometheus.io/docs/alerting/configuration/#sns_config)