With AWS CodePipeline Notifications, developers and others can receive notifications on events that occur in your pipelines?—?including pipeline, stage, and action changes. For example, you can receive email notifications on pipeline failures.
Because CodePipeline notifications leverage Amazon CloudWatch Events, you can also integrate it with AWS resources such as SNS, Lambda, SQS, SSM, EC2, Inspector, Kinesis Stream, ECS, Step Functions, and many more. One simple example is that you can use a Lambda function as a CloudWatch Event Rule Target and every time it gets notified, it runs a Lambda function and this Lambda function triggers a Slack notification. With this configuration, you can get CodePipeline notifications while you’re in Slack. In this post, I will focus on getting notified via Amazon SNS.
Because CodePipeline notifications leverage Amazon CloudWatch Events, you can integrate it with AWS resources such as SNS, Lambda, SQS, SSM, EC2, Inspector, Kinesis Streams, ECS, Step Functions, and many more.
At the conclusion of this post, you can provision all of the AWS resources by clicking a “Launch Stack” button and going through the AWS CloudFormation steps to launch the solution stack. As part of this configuration, it will automatically provision a CloudWatch Event Rule for CodePipeline notifications via SNS using an email endpoint. The example builds on an existing deployment pipeline for EC2 solution. You will also get access to a solution that only establishes the necessary CloudWatch and SNS resources rather than embedding with another solution.
The provisioning of all of the AWS resources is defined in a CloudFormation template. You can find the source examples in GitHub.
Figure 1 shows the failure of a CodeBuild test action in CodePipeline when a failure occurs.
Figure 1?—?CodePipeline Failure when one of the actions fail
In Figure 2, you can see the type of email you will receive when your CodePipeline pipeline fails. In the example, developers can click on the link to directly access the pipeline that just failed.
Figure 2?—?Email Notification when a CodePipeline Failure Occurs
The remainder of this post describes how to configure the solution in your AWS account.
Prerequisites
Here are the prerequisites for this solution:
- AWS Account?—?Follow these instructions to create an AWS Account: Creating an AWS Account and grant IAM privileges to access at least CodeCommit, CloudWatch, CodeBuild, CodePipeline, EC2, IAM, SNS, and S3.
- Fork GitHub Repo?—?Fork and clone your own stelligent/devops-essentials GitHub repository
- OAuth Token?—?Create an OAuth token in GitHub and provide access to the admin:repo_hook and repo scopes.
To see these steps in more detail, go to the Prerequisites.
Architecture and Implementation
The components of this solution are:
- AWS CloudFormation?—?All of the resource generation of this solution is described in CloudFormation which is a declarative code language that can be written in JSON or YAML (or generated by more expressive domain-specific languages)
- Amazon CloudWatch Event Rule— The resources, such as Lambda functions or SNS Topics, that CloudWatch Events routes events to and invokes when the rule is triggered
- AWS CodePipeline?—?The CodePipeline stages and actions are defined in a CloudFormation template. This includes CodePipeline’s integration with CodeCommit, CodeBuild, and CodeDeploy (For more information, see Action Structure Requirements in AWS CodePipeline).
- CodeCommit?—?CloudFormation creates a new CodeCommit repository that is used as the Source action in CodePipeline.
- AWS CodeBuild?—?Creates a CodeBuild project using the AWS::CodeBuild::Project
- AWS IAM?—?An Identity and Access Management (IAM) Role is provisioned using the AWS::IAM::Role resource which defines the resources that the pipeline, CloudFormation, and other resources can access.
CloudFormation Template
In this section, I’ll highlight a few of the most relevant code snippets from the CloudFormation template that automates the provisioning of the AWS resources in this solution.
SNS Topic
The CloudFormation snippet below creates an SNS Topic. Amazon Simple Notification (SNS) is a fully-managed service for sending messages to subscribing endpoints. In this case, I’m creating a subscription with an email endpoint. As part of launching the CloudFormation stack, the user is prompted to enter an email address for receiving these notifications.
MySNSTopic:
Type: AWS::SNS::Topic
Properties:
Subscription:
- Endpoint:
Ref: EmailAddress
Protocol: email
CloudWatch Event Rule
The CloudWatch Event Rule defines the conditions under which a CloudWatch Event is triggered. In the snippet below, it triggers the SNS Topic as a target when the CodePipeline source is in a FAILED state. In addition, it provides the text that’s displayed in the SNS Topic so that the user knows which action to take.
EventRule:
Type: "AWS::Events::Rule"
Properties:
Description: "EventRule"
EventPattern:
source:
- aws.codepipeline
detail-type:
- CodePipeline Pipeline Execution State Change
detail:
state:
- FAILED
State: "ENABLED"
Targets:
-
Arn:
Ref: "MySNSTopic"
Id: "OpsTopic"
InputTransformer:
InputTemplate: '"The Pipeline has failed. Go to https://console.aws.amazon.com/codepipeline/home?region=us-east-1#/view/" '
InputPathsMap:
pipeline: "$.detail.pipeline"
The combination of this event rule and the SNS Topic causes an email to be sent to an email address – provided by the user – when CodePipeline fails (as shown in Figure 2).
Costs
Since costs can vary as you use certain AWS services and other tools, you can see a cost breakdown and some sample scenarios to give you an idea of what your monthly spend might look like. Note this will be dependent on your unique environment and deployment, and the AWS Cost Calculator can assist in establishing cost projections.
- CloudFormation?—?No additional cost.
- CloudWatch Events?—?$1 per million custom events generated. See CloudWatch Pricing.
- CodeBuild?—?CodeBuild charges per minute used. It comes with 100 minutes per month at no charge. For a simple execution of this demo, you can stay within the limits of the AWS Free Tier?—?please read about the Free Tier here. For more information, see AWS CodeBuild pricing.
- CodePipeline?—?Customers can create new pipelines without incurring any charges on that pipeline for the first 30 calendar days. After that period, the new pipelines will be charged at the existing rate of $1 per active pipeline per month. For more information, see AWS CodePipeline pricing.
- GitHub?—?No charge for public repositories
- IAM?—?No additional cost.
- S3?—?If you launch the solution and delete the S3 bucket, it’ll be pennies (if that). See S3 Pricing.
The bottom line on pricing for this particular example is that you will charged no more than a few pennies if you launch the solution run through a few changes and then terminate the CloudFormation stack and associated AWS resources.
Deployment Steps
This particular solution defines the CloudWatch Event Rule in the context of a full solution that deploys an application onto EC2 using the AWS Developer Tools. The relevant part of this solution is here.
There are three main steps in launching this solution: preparing an AWS account, launching the stack, and testing the deployment. Each is described in more detail in this section. Please note that you are responsible for any charges incurred while creating and launching your solution.
Step 1. Prepare an AWS Account
If you don’t already have an AWS account, create one at http://aws.amazon.com by following the on-screen instructions. Part of the sign-up process involves receiving a phone call and entering a PIN using the phone keypad. Be sure you’ve signed up for the CloudFormation service. Use the region selector in the navigation bar of the console to choose the Northern Virginia (us-east-1) region
Step 2. Launch the Stack
Click on the “Launch Stack” button below to launch the CloudFormation stack. Before you launch the stack, review the architecture, configuration, and other considerations discussed in this post. To download the template, click here.
Time to deploy: Approximately 7 minutes
The template includes default settings that you can customize by following the instructions in this post.
Step 3. Test the Deployment
Here are the steps to test the deployment:
- Once the CloudFormation stack is in the CREATE_COMPLETE state, you should receive an email from Amazon SNS. When you do, click the Confirm Subscription link
- Then, select the checkbox next to the CloudFormation stack and click the Outputs tab.
- From Outputs, click on the PipelineUrl output. The Source action will be in a failed state.
- From the CodePipeline Source action, click on the CodeCommit provider and copy the git clone statement provided by CodeCommit
- Paste the command in your Terminal
- Copy all of the contents from this folder to your locally cloned CodeCommit Git repo
- From your Terminal, type
git add . - From your Terminal, type
git commit -am "add new files" - From your Terminal, type
git push - Go back to your pipeline in CodePipeline and see the changes flow through the pipeline. It should fail at the cfn_nag action and you should receive an email notification from SNS.
Alternative Solution: Separate Stack
Alternatively, you can launch a stack that only provisions the CloudWatch Event Rules and SNS Target by clicking the “Launch Stack” button below. You might want to enable Termination Protection in the Advanced section of the Options page when launching the stack as part of the CloudFormation console. This makes it less simple to delete the stack if you want notifications to enabled for all CodePipeline invocations.
Time to deploy: Approximately 1 minute
Troubleshooting
For some AWS accounts, you might receive need to edit the text of the CloudWatch Event. If this happens to you, perform the following steps:
- Go to the Amazon CloudWatch Console and select the correct region.
- Select Rules
- Select the rule that the stack generated by the CloudFormation stack
- Select Edit from the Actions drop down
- Modify some of the text in the Input Transformer of the SNS topic Target
- Click Configure details
- Click Update rule
- Rerun the pipeline to get notified when a failure occurs
Additional Resources
Here are some of the supporting resources discussed in this post:
- Source code for this post
- GitHub: Open Source Examples from the DevOps Essentials on AWS Course
- CloudFormation Template that provisions CloudWatch Event Rule for SNS only
Did you find this post interesting? Are you passionate about working with the latest AWS technologies? If so, Stelligent is hiring and we would love to hear from you!
|
Stelligent Amazon Pollycast
 |
