How to Integrate Amazon CloudWatch Alarms with Atlassian Confluence Knowledge Articles

By Yash Bindlish, Enterprise Support Manager – AWS
By Abhishek Dey, Technical Account Manager – AWS
By Tshepo Marokana, Cloud Support Engineer – AWS

Atlassian

Atlassian Confluence is a knowledge management and project collaboration tool that lets you create, capture, and collaborate on projects or ideas while creating and sharing knowledge articles with your colleague and organization.

Confluence spaces help teams structure, organize, and share work, so that every team member has visibility into institutional knowledge and access to the information they need to do their best work.

This post describes how you can transform Amazon CloudWatch alarm notifications using AWS Lambda and send the notification to subscribers.

You can use CloudWatch to set alarms and automate actions based on predefined thresholds, and if you add an Amazon Simple Notification Service (Amazon SNS) topic in the alarm action the SNS topic sends a JSON object containing details about state change to the subscribed Lambada function.

You can transform the alarm notification using Lambda code based on the nature of alarm notification and embed a Confluence knowledge article with prescribed guidance to act upon the notifications.

In this post, we’ll share how to use a Lambda function to transform the alarm notification and embed a Confluence knowledge article in message.

Atlassian is an AWS DevOps Competency Partner that builds collaboration and productivity software to help teams organize, discuss, and complete shared work.

Architecture Overview

The following architecture diagram depicts your applications being monitored via Amazon CloudWatch, and on certain metrics a CloudWatch alarm is generated. The solution will then trigger an Amazon SNS notification, as SNS receives JSON notifications from CloudWatch and forwards the message to an AWS Lambda endpoint to parse and transform the message body.

Lambda then runs a Python runtime code to read JSON events and transforms the notification into the desired email message with an embedded Confluence knowledge base article link.

Figure 1 – Architecture overview.

Prerequisites

• AWS Management Console or AWS Command Line Interface (CLI) 2.
• You need Atlassian Confluence account access for your cloud operations and site reliability engineering (SRE) team to create and use knowledge articles. For this post, we have used the Confluence trial version to create and publish a Confluence page.

SNS Topics

• Use the following command to create an SNS topic:

aws sns create-topic —name message-transformation-sns

• You should see the following/similar output:

{
"TopicArn": "arn:aws:sns:us-west-2:37407xxxxxxx:message-transformation-sns"
}

• Use this command to create another SNS topic and subscribe an email address:

aws sns create-topic —name email-publisher-sns

• You should see the following/similar output:

{
"TopicArn": "arn:aws:sns:us-west-2:37407xxxxxxx:email-publisher-sns"
}

• Refer to the AWS documentation for more information about creating SNS topics with a unique name.

AWS Lambda Execution Role

• Create an AWS Identity and Access Management (IAM) execution role that gives your function permission to subscribe and publish message to SNS and write execution logs into an Amazon CloudWatch log group.
• To create an execution role with the AWS CLI, use the create-role command.

Once you have all of the prerequisites in place, follow the following set of instructions to deploy the solution.

Create a Confluence Knowledge Article

• You should have an Atlassian Confluence account to create, edit and publish a knowledge base.
• Log in into your Confluence account: <https://<YourNameSpace>.atlassian.net/>
• Click on the Create button.
• Add a page title and write content on the page body to draft a knowledge article, and then use edit tools to customize your page.

 Figure 2 – Page title in Atlassian Confluence.

• To publish the page within your organization, click the Publish button.
• Once the knowledge article is published, copy the published URL to be used in AWS Lambda transformation code.
  • Sample URL: https://<YourNameSpace>.atlassian.net/l/cp/<RandomCode>
• You can create multiple pages and publish knowledge articles within your organization; refer to Confluence Support for more information.

Set Up a CPU Usage Alarm

• Create a CloudWatch alarm named ec2-p70-cpu-usage-alarm that sends a notification using Amazon SNS when the alarm changes state from OK to ALARM.
• Execute following CLI command to create a CPU usage alarm for an Amazon Elastic Compute Cloud (Amazon EC2) instance:

aws cloudwatch put-metric-alarm —alarm-name ec2-70p-cpu-usage-alarm —alarm-description "alarm when CPU exceeds 70%" —metric-name CPUUtilization —namespace AWS/EC2 —statistic Average —period 300 —threshold 70 —comparison-operator GreaterThanThreshold —dimensions Name=InstanceId,Value=i-091845d0d1f3xxxxx —evaluation-periods 1 —alarm-actions arn:aws:sns:us-west-2:37407xxxxxxx:message-transformation-sns —unit Percent

• Replace the EC2 Instance ID and SNS ARN with the “original id” and “arn” in the above command; refer to the AWS documentation for more information about creating CloudWatch alarms.

Create a Lambda Function with SNS Trigger

• Amazon SNS and AWS Lambda can be integrated so you can invoke Lambda functions with SNS notifications. When a message is published to an SNS topic (message-transformation-sns) from a CloudWatch alarm (ec2-p70-cpu-usage-alarm) that has a Lambda function (TransformationLambdaFunction) subscribed to it, the Lambda function is invoked with the payload of the published message.
• For instructions on creating a Lambda function, see the AWS documentation.
• To fan out a Lambda function using SNS, see the documentation about triggering AWS Lambda with Amazon SNS.
• Before you create the Lambda function, you must create a deployment package. Your function code must include logic to transform your SNS topic’s notification messages to a customized message, and embed the Confluence article into it before publishing the message to outbound SNS (email-publisher-sns).
• See the following Python 3.8 code snippets for next steps; this code transforms the message and embeds the Confluence article. However, you can always modify the logic according to your use case and specific requirements. The code is compatible with the Python 3.8 runtime.

Step 1: Copy Lambda Code

• Copy the following code and save it in your local file system with name lambda_function.py.

import boto3
import json

def lambda_handler(event, context):
    
    AlarmPayLoad = str(json.dumps(event, indent=2))
    AlarmMessage = str(event['Records'][0]['Sns']['Message'])
    AlarmTimestamp = str(event['Records'][0]['Sns']['Timestamp'])
    MessageID = str(event['Records'][0]['Sns']['MessageId'])
    ConfluenceArticle = 'https://<YourNameSpace>.atlassian.net/l/cp/Ytnskdjyt56ys'
    EmailSubject = str(event['Records'][0]['Sns']['Subject'])
   
   #Customize the message and embed knowledge article
     
    CustomizedPayLoad = 'Hello Recipient,' + '\n' + 'This alarm is generated by transformation Lambda function, please read this message carefully and refer the Knowledge Article added in this message to take prescribed action to remediate the alarm' + '\n' + 'MessageID:' + MessageID + '\n' + '\n' + 'Message: ' + AlarmMessage + '\n' + '\n' + 'TimeStamp: ' + AlarmTimestamp + '\n' + ‘\n’ + 'Please refer this knowledge article to act: ' + '\n' + ConfluenceArticle + '\n' + '\n' + 'Raw Event: ' + '\n' + AlarmPayLoad
    
    #Publishing Message to SNS topic    
    client = boto3.client('sns')
    snsArn = 'arn:aws:sns:us-west-2:37407xxxxxxx:sns-outbound'
    
    response = client.publish(
        TopicArn = snsArn,
        Message = CustomizedPayLoad,
        Subject = 'EC2 CUP Alarm Notification' 
    )
    
    return response

Step 2: Compress and Zip Lambda Code

• Compress the code snippet into zip using the following CLI or ZIP utility:

zip transformation-lambda.zip lambda_function.py

Step 3: Create Lambda Function

• The following create-function CLI creates a Lambda function named TransformationLambdaFunction. Note that creating Lambda execution roles is covered in the prerequisites section.

aws lambda create-function \
    --function-name TransformationLambdaFunction \
    --runtime python3.8 \
    --zip-file fileb://transformation-lambda.zip \
    --handler transformation-lambda.handler \
    --role arn:aws:iam::123456789012:role/service-role/transformation-role-lambda

For more information on creating a Lambda function through AWS CLI, see the AWS documentation.

Step 4: Test Lambda Function with SNS Notification

• Add an SNS topic as the trigger for your Lambda function, and execute the following command to integrate the message-transformation-sns SNS topic which is created in the prerequisite section to add as a trigger for TransformationLambdaFunction.

aws lambda add-permission --function-name TransformationLambdaFunction --action lambda:InvokeFunction --statement-id sns --principal sns.amazonaws.com --source-arn arn:aws:sns:us-west-2:37407xxxxxxx:message-transformation-sns

• This will return the permission statement that’s added to the function policy.
• For more information, see the documentation for adding permissions to Lambda.

Test Transformation Lambda Function

• A CloudWatch condition is set to trigger an alarm when EC2 CPU reaches above 70%.
• However, to test the Lambda function you can modify the CloudWatch threshold and data point in the configuration.
• The notification email after transformation will look like this:

Figure 3 – Sample email notification.

Cleanup

To avoid incurring unwanted charges and to avoid the misuse of resources, delete the resources you have created during this exercise. Follow these CLI commands to remove the resources:

• Delete Lambda function: aws lambda delete-function --function-name <function-name>
• Delete SNS topic: aws sns delete-topic --topic-arn "arn:aws:sns:<region>:<account-id>:<topic-name>"
• Delete CloudWatch: aws cloudwatch delete-alarms --alarm-names <alarm-name>
• Delete Lambda function IAM execution role: aws iam delete-role —role-name <role-name>

Conclusion

In this post, we shared how to use an AWS Lambda function to customize Amazon CloudWatch alarm notifications and embed an Atlassian Confluence knowledge article within it.

We explored the option to build a pipeline to carry the metrics notification from source instance to CloudWatch and Amazon SNS, and how to transform the message using Lambda Python code and publish it to email subscribers.

We demonstrated a pipeline to generate and transform message notification for operations team with prescribed guidance to act on the critical alarm notification.

.

.

Atlassian – AWS Partner Spotlight

Atlassian is an AWS DevOps Competency Partner that builds collaboration and productivity software to help teams organize, discuss, and complete shared work.

Contact Atlassian | Partner Overview