This post is contributed by Daniele Stroppa, Sr. Solutions Architect
In October 2019, AWS released an improvement to the getting started experience in the AWS Lambda console. This enables you to create applications that follow common best practices, using infrastructure as code (IaC). It also provides a continuous integration and continuous deployment (CI/CD) pipeline for deployment.
Today, we are releasing a new set of ready-to-use examples that use the AWS Cloud Development Kit (AWS CDK) to model application resources. The AWS CDK is an open-source software development framework for defining your cloud infrastructure in code and provisioning it through AWS CloudFormation.
In this post, I walk through creating a serverless application with the AWS CDK.
Create an application
An AWS Lambda application is a combination of Lambda functions, event sources, and other resources that work together to perform tasks. Create a new application in the AWS Lambda console:
- On the left menu, choose Applications.
- Choose Create application and then choose Serverless API backend from the list of examples.
- Review the setup and configuration of the application and then choose Next.
- Configure application settings:
- Application name – serverless-api-cdk.
- Application description – A simple serverless API application.
- Runtime – Node.js 10.x.
- Template format – AWS CDK (TypeScript).
- Repository provider – CodeCommit. (Note: If you choose GitHub, you must connect to your GitHub account for authorization).
- Repository name – serverless-api-cdk.
- Permissions – Check Create roles and permissions boundary.
- Choose Create.
This creates a new serverless application from the Lambda console. The console creates the pipeline and related resources. It also commits the sample application code to the Git repository. Resources appear in the overview page as they are created. Next, I explore the CDK models used to create the application resources.
Clone the application repository
When you create the application, the Lambda console creates a Git repository that contains the sample application. Clone the project repository in your local development environment:
- Find your application in the Lambda console.
- Choose the Code tab.
- Copy the HTTP or SSH repository URI, depending on the authentication mode that you configured during setup.
- Clone the repository on your local machine.
$ git clone ssh://git-codecommit.us-east-1.amazonaws.com/v1/repos/serverless-api-cdk
NOTE: your repository URL might differ from the one above if you are running in a different Region.
The repository contains the CDK models for the application, a build specification, and the application code.
Install the AWS CDK in your local environment
If you haven’t already, install the AWS CDK in your local environment using the following command:
$ npm install -g [email protected]
Run the following command to verify the version number of the CDK:
$ cdk --version
You should see the following output:
$ 1.42.0 (build 3b64241)
Explore the CDK application
A CDK application is composed of building blocks called constructs. These are cloud components that can represent architectures of any complexity. For example, a single resource, such as an Amazon S3 bucket or an Amazon SNS topic, a static website, or even a complex, multi-stack application that spans multiple AWS accounts and Regions.
To enable reusability, constructs can include other constructs. You compose constructs together into stacks that you can deploy into an AWS environment, and apps, a collection of one of more stacks. Learn more about AWS CDK concepts in the AWS documentation.
The sample application defines a CDK app in the serverless-api-cdk/cdk/bin/cdk.ts file:
The CDK app is composed of a single CDK stack, defined in the cdk/lib/cdk-stack.ts:
The CDK stack first declares an Amazon DynamoDB table used by the API, specifying the partition key and the provisioned read and write capacity units:
Then, it declares a set of common configuration options for the application’s Lambda functions. These includes an environment variable referencing the DynamoDB table and the S3 location for the function’s code artifact.
Each Lambda function is declared individually, specifying the function code and configuration. There is a reference to the DynamoDB table resource, passed as an environment variable:
The last line in the code is the short form to declare what IAM permissions the function requires. When the CDK app is synthesized, the CDK CLI generates the required IAM role and policy, following the principle of least privilege.
Lastly, the CDK stack declares the APIs:
View the synthesized CloudFormation template
A CloudFormation template is created based on the code. Before you can generate the CloudFormation template, you must install the required npm packages. Execute the following command from the serverless-api-cdk/cdk/ directory:
$ cd serverless-api-cdk/cdk/ $ npm install
The Lambda function’s configuration uses two environment variables that are defined during the build process, S3_BUCKET and CODEBUILD_BUILD_ID. To synthesize the CloudFormation template, you must define these two variables locally:
$ export S3_BUCKET="my_artifact_bucket" $ export CODEBUILD_BUILD_ID="1234567"
NOTE: actual values of the variables do not matter until you provision resources. The correct values are injected during the build and deploy phase.
From the serverless-api-cdk/cdk/ folder, run the
cdk synth command. A CloudFormation template that is generated based on the sample application code is displayed in the console and also available in the serverless-api-cdk/cdk/cdk.out directory.
In this post, I show how to create a serverless application with the AWS Cloud Development Kit (AWS CDK). I also show how to create a pipeline to automatically deploy your changes. We also explore some of the CDK constructs you can use to model our cloud resources.
To learn more, see the CDK examples available in the Lambda console.