Use the Grafana Alerting - Amazon SNS integration to send notifications to Amazon SNS when your alerts are firing.
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.
## Before you begin
To configure Amazon SNS to receive alert notifications, complete the following steps.
Before you begin, ensure you have the following:
1. Create a new topic in https://console.aws.amazon.com/sns.
1. Open the topic and create a new subscription.
1. Choose the protocol HTTPS.
1. Copy the URL.
- **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 more information, refer to [Amazon SNS documentation](https://docs.aws.amazon.com/sns/latest/dg/welcome.html).
For an example setup, see [Example Minimal Setup Using Assumed IAM Role]({{< relref "#example-minimal-setup-using-assumed-iam-role" >}}).
## Procedure
## Adding the SNS Contact Point in Grafana
To create your Amazon SNS integration in Grafana Alerting, complete the following steps.
With AWS resources configured, proceed to add SNS as a contact point in Grafana.
- **Name**: Enter a descriptive name (e.g., `AWS SNS`).
- Choose **"AWS SNS"** from the list of contact point types.
The Amazon SNS contact point is ready to receive alert notifications.
### 2. Configure 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.
- **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.
- **Attributes**: (Optional) Add any SNS message attributes.
{{<admonitiontype="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.
Environment variables: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
{{</admonition>}}
### 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.
@ -55,3 +82,124 @@ To add this contact point to your alert, complete the following steps.
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. **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)]:
- On the **Topics** page, choose **"Create topic"**.
- Select **"Standard"** as the type.
- Enter a **Name** for your topic, e.g., `My-Topic`.
- **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)]:
- 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
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)]:
- 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"**.
- Switch to the **"JSON"** tab and paste the following policy, replacing `Resource` with your SNS topic ARN:
- 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:
- 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)]:
- In the IAM Console, on the **Users** page, choose **"Create user"**.
- Enter a **User name**, e.g., `grafana-sns-user`.
- Click **"Next"**.
- Select **"Attach policies directly"**.
- Search for the policy you created earlier (`AssumeSNSRolePolicy`) and select it.
- Click **"Next"** , and click **"Create user"**.
2. **Generate credentials**:
- 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.
### 5. Add 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:
- **The Amazon SNS API URL**: `https://sns.us-east-1.amazonaws.com`
Replace the placeholder values (`https://sns.us-east-1.amazonaws.com`, `us-east-1`, `<YOUR_ACCESS_KEY>`, `<YOUR_SECRET_ACCESS_KEY>`, `arn:aws:iam::<account_id>:role/GrafanaSNSRole`, `arn:aws:sns:<region>:<account_id>:My-Topic`) with your actual AWS credentials and ARNs.
Matthew Jacobson
9 months ago
committed by