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.

codepipeline-failure

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.

codepipeline-fail-email

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:

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!

Leave a Reply