Introduction

1. What’s AWS CDK? ​

AWS CDK is an Infrastructure as Code solution, similar to AWS CloudFormation and HashiCorp’s Terraform, Where you can have your infrastructure defined as Code in a project which you can deploy easily, keep track of its changes (Assuming you use a Version Control system like Git for that) and acts as a documentation for your simple or complex solution design. ​

2. How does it compare to the others? ​

​

​ ​ 3. CDK project lifecycle ​

When you create a project you define your infrastructure in one of the supported languages. Your CDK project gets parsed and a CloudFormation template is generated. The CloudFormation template gets executed in aws Cloudformation’s service and all infrastructure is set up for you.

Let’s get our hands dirty

Here’s what we’re trying to create in this tutorial, we’re going to make any action in our CodeCommit Repository triggers a notification in Slack. ​ Under the hood a Cloudwatch Rule will listen to any actions happening in the repository and triggers a Lambda with the action’s details (commit message, pull request title, etc).

1. Installation ​

Assuming you have NPM installed.

npm install -g cdk

• Bootstrapping your account ​

AWS CDK creates a stack of resources it needs in your aws account to insure it can deploy your projects later, like an S3 bucket to upload assets.

cdk bootstrap

2. Creating a project ​

In our case we’re going to use python as our language of choice

mkdir codecommit-slack-bot
cd codecommit-slack-bot
cdk init --language=python

A boilerplate project gets created alongside a virtualenv.

.
├── .env
├── README.md
├── app.py
├── cdk.json
├── requirements.txt
├── setup.py
└── tuto_cdk    
	├── __init__.py    
	└── tuto_cdk_stack.py

To activate the virtualenv and install the requirements.

source .env/bin/activatepip install -r requirements.txt

3. Understanding the boilerplate

• app.py file ​

app.py is the project starting point and it looks like this:

#!/usr/bin/env python3

​from aws_cdk import core
​from codecommit_slack_bot.codecommit_slack_bot_stack import CodecommitSlackBotStack

​​app = core.App()
CodecommitSlackBotStack(app, "codecommit-slack-bot")​
app.synth()

app = core.App() initializes the CDK.

CodecommitSlackBotStack(app, "codecommit-slack-bot") creates our only stack, but we can have multiple ones.

app.synth() this method is what transforms the stacks we defined into cloudformation templates.

• codecommit_slack_bot_stack.py file ​

Now let’s have a look at the only stack created for us.

from aws_cdk import core
​​class CodecommitSlackBotStack(core.Stack):
​    def __init__(self, scope: core.Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)
        # The code that defines your stack goes here

​ There’s already a comment in the boilerplate which gives us a hint on where to put our code that defines our stack of resources, all should be in the constructor of our class.

This class gets instantiated in the app.py into an object, that’s all what CDK needs to understand that you want to create a stack with all the resources you define in it. ​

4. Writing our own code ​

In our stack file called codecommit_slack_bot_stack.py we are going to define the resources we want to add. ​ We started by modifying the constructor of our stack to accept 3 more parameters which are the lambda_path , slack_webhook_url and codecommit_repo_arn.

def __init__(self, scope: core.Construct, id: str, lambda_path: str,
                 slack_webhook_url: str, codecommit_repo_arn: str,
                 **kwargs) -> None:

Our goal is to achieve the workflow below:

• IAM Role for our Lambda Function ​

We start by importing aws_iam from cdk

from aws_cdk import core, aws_iam

​This role should allow us to access codecommit to retrieve details about the repository and the more details about the actions triggered. It also allows our Lambda function to store Logs in Cloudwatch. For That we start by creating our Policy document.

lambda_role_policy = aws_iam.PolicyDocument(
    statements=[
        aws_iam.PolicyStatement(
            effect=aws_iam.Effect.ALLOW,
            actions=['codecommit:*'],
            resources=[codecommit_repo_arn]
        ),
        aws_iam.PolicyStatement(
            effect=aws_iam.Effect.ALLOW,
            actions=[
                'logs:CreateLogGroup',
                'logs:CreateLogStream',
                'logs:PutLogEvents'
            ],
            resources=['*']
        )
    ]
)

​ Now that the policy is ready, we can create our role that can be assumed by aws lambda service and attach the policy document to it. ​

lambda_role = aws_iam.Role(
    self,
    id='role',
    assumed_by=aws_iam.ServicePrincipal('lambda.amazonaws.com'),
    inline_policies={
        'policy': lambda_role_policy
    }
)

• AWS Lambda function ​

It’s time to create our Lambda function, for that we’re going to add aws_lambda to the import statement.

from aws_cdk import core, aws_iam, aws_lambda

​ Our Lambda function will get the source code from the lambda_path argument and also will set an environment variable called SLACK_WEBHOOK_URL with the value of the argument slack_webhook_url . We’re also going to attach the role we created earlier to it. ​ ​

lambda_function = aws_lambda.Function(
    self,
    id='handler',
    code=aws_lambda.Code.from_asset(lambda_path),
    handler='lambda_function.lambda_handler',
    timeout=core.Duration.seconds(300),
    runtime=aws_lambda.Runtime.PYTHON_3_7,
    role=lambda_role,
    environment={
        'SLACK_WEBHOOK_URL': slack_webhook_url
    }
)

​

• Cloudwatch Rule ​

Now that we have our lambda defined, the missing part is creating the CloudWatch event rule which will listen to all events in our repository and triggers a lambda every time an event occurs. For that we are going to add both aws_events and aws_events_targets to the import statement.

from aws_cdk import core, aws_iam, aws_lambda, aws_events, aws_events_targets

​ Then we define the rule by defining the pattern first, then the actual rule ​

pattern = aws_events.EventPattern(
    resources=[codecommit_repo_arn],
    source=['aws.codecommit']
)​
aws_events.Rule(
    self,
    id='cloudwatch-rule',
    event_pattern=pattern,
    targets=[aws_events_targets.LambdaFunction(lambda_function)]
)

Now that our stack is fully defined, we can start working on the other files. ​

First of all, we’re going to put some configuration in the cdk.json file, notably the repository arn and the slack webhook url using the context mechanism offered by CDK

{
    "app": "python3 app.py",
    "context": {
        "codecommit_repo_arn": "arn:aws:codecommit:<region>:<account>:<repository_name>",
        "slack_webhook_url": "<slack_webhook_url>"
    }
}

Then we’re going to try to access those from the app.py and extract information in there

codecommit_repo_arn = app.node.try_get_context('codecommit_repo_arn')
slack_webhook_url = app.node.try_get_context('slack_webhook_url')
​repository_details = core.Arn.parse(codecommit_repo_arn)
account = repository_details.account
region = repository_details.region
repository_name = repository_details.resource

​ And we’re also going to define the path of our aws lambda’s source code

import osproject_root_path = path.dirname(path.realpath(__file__))
lambda_source_code_path = path.join(project_root_path, 'lambda_handler')

The source code of our lambda function can be found here.​

Finally, we’re going to modify the instantiation of our stack to pass all new arguments needed for it. ​

env = core.Environment(account=account, region=region)
​CodecommitSlackBotStack(
    app,
    id=f'codecommit-slack-bot-{repository_name}',
    lambda_path=lambda_source_code_path,
    slack_webhook_url=slack_webhook_url,
    codecommit_repo_arn=codecommit_repo_arn,
    env=env
)
​app.synth()

The source code for the project can be found here

Conclusion

Infrastructure as Code (IaC) is powerful, it is capable of keeping track of your infrastructure. With more than one single language, CDK gives developers the ability to define their stacks of infrastructure using their preferred programming language, saving time invested for learning purposes required for using other solutions.