Home

Awesome

AWS CDK Starterkit header

AWS CDK Starterkit

The perfect starter kit to create and deploy an AWS CDK App using TypeScript on your AWS account in less than 5 minutes using GitHub actions!

Build Status ESLint Code Formatting Latest release

Intro

Welcome to the starting line of your next AWS CDK project. This repository is crafted to supercharge your project's setup with AWS CDK TypeScript, projen, and GitHub actions, ensuring a smooth and efficient deployment to your AWS account.

[!TIP] Unlock the full potention of your infrastructure - Partner with Us!

Features

Setup Guide

This project requires a atleast Node.js version 20.

All the config that is needed to personalise the CDK App to your environment is defined in the .projenrc.ts file.

To get started, follow these steps:

  1. Fork / clone this repo

  2. Add a Personal Access Token to the repository settings on GitHub, follow these instructions for setting up a fine-grained personal access token.

  3. Install the projects dependencies using: npm ci

  4. Customize the AWS Region and Account IDs in the .projenrc.ts file to match your AWS setup:

/* Define the AWS region for the CDK app and github workflows
Default to us-east-1 if AWS_REGION is not set in your environment variables */
const awsRegion = process.env.AWS_REGION || 'us-east-1';

// Define the target AWS accounts for the different environments
type Environment = 'test' | 'production';

interface EnvironmentConfig {
  accountId: string;
  enableBranchDeploy: boolean;
}

const environmentConfigs: Record<Environment, EnvironmentConfig> = {
  test: { accountId: '987654321012', enableBranchDeploy: true },
  production: { accountId: '123456789012', enableBranchDeploy: false },
};

  1. Run npx projen to generate the github actions workflow files.

  2. AWS CLI Authentication: Ensure you're logged into an AWS Account (one of the ones you configured in step 4) via the AWS CLI. If you haven't set up the AWS CLI, then follow this guide)

  3. Deploy the CDK toolkit stack to your AWS environment with cdk bootstrap if it's not already set up.

  4. Deploy the GitHub OIDC Stack to enable GitHub Actions workflow permissions for AWS deployments. For instance, if you set up a dev environment, execute npm run dev:deploy.

  5. Commit and push your changes to the main branch to trigger the CDK deploy pipeline in GitHub.

Congratulations 🎉! You've successfully set up your project.

Project Structure

When working on smaller projects using infrastructure as code, where you deploy single applications that don’t demand extensive maintenance or collaboration from multiple teams, it’s recommended to structure your AWS CDK project in a way that enables you to deploy both the application and infrastructure using a single stack.

However, as projects evolve to encompass multiple microservices and a variety of stateful resources (e.g., databases), the complexity inherently increases.

In such cases, adopting a more sophisticated AWS CDK project organization becomes critical. This ensures not only the ease of extensibility but also the smooth deployment of each component, thereby supporting a more robust development lifecycle and facilitating greater operational efficiency.

To cater to these advanced needs, your AWS CDK project should adopt a modular structure. This is where the AWS CDK starterkit shines ✨.

Here’s a closer look at how this structure enhances maintainability and scalability:

.
├── .eslintrc.json
├── .gitattributes
├── .github
│  ├── dependabot.yml
│  └── workflows
│     ├── auto-approve.yml
│     ├── cdk-deploy-production.yml
│     ├── cdk-deploy-test-branch.yml
│     ├── cdk-deploy-test.yml
│     ├── cdk-destroy-test-branch.yml
│     ├── pull-request-lint.yml
│     └── release.yml
├── .gitignore
├── .npmignore
├── .projen
│  ├── deps.json
│  ├── files.json
│  └── tasks.json
├── .projenrc.ts
├── cdk.context.json
├── cdk.json
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── src
│  ├── assets
│  │  ├── ecs
│  │  │  └── example-container
│  │  │     └── Dockerfile
│  │  └── lambda
│  │     └── example-lambda-function
│  │        └── lambda_function.py
│  ├── bin
│  │  ├── cicd-helper.ts
│  │  ├── env-helper.ts
│  │  └── git-helper.ts
│  ├── constructs
│  │  ├── base-construct.ts
│  │  ├── index.ts
│  │  ├── network-construct.ts
│  │  └── README.md
│  ├── main.ts
│  └── stacks
│     ├── base-stack.ts
│     ├── github-oidc-stack.ts
│     ├── index.ts
│     ├── README.md
│     └── toolkit-cleaner-stack.ts
├── test
│  ├── __snapshots__
│  │  └── main.test.ts.snap
│  └── main.test.ts
├── tsconfig.dev.json
└── tsconfig.json

As you can see in the above tree diagram, the way this project is setup it tries to segment it into logical units, such as constructs for reusable infrastructure patterns, stacks for deploying groups of resources and assets for managing source code of containers and lambda functions.

Here is a brief explanation of what each section does:

Branch-based Deployments

This starter kit supports deploying multiple CDK stacks to the same AWS environments based on the Git branch. This enables you to easily test changes when multiple developers work on the same code base.

When you create a new feature branch and push it to the repository, the GitHub Actions workflow will automatically deploy the CDK stacks to the corresponding AWS environment (e.g., dev, test, staging) based on the branch name.

Additionally, the workflow includes a separate task to destroy the CDK stacks for the feature branch when the branch is deleted or the pull request is closed, ensuring that the resources are cleaned up after the testing is complete.

Unlock the full potention of your infrastructure - Partner with us!

[!TIP] Supercharge Your AWS Infrastructure with Towards the Cloud. We ship well-architected, resilient, and cost-optimized AWS solutions designed to scale using Infrastructure as Code (IaC), tailoring cloud-native systems for businesses of all sizes.

Our Approach:

Why Choose Us:

Ready to elevate your AWS CDK Infrastructure?

<a href="https://towardsthecloud.com/contact"><img alt="Schedule your call" src="https://img.shields.io/badge/schedule%20your%20call-success.svg?style=for-the-badge"/></a>

<details><summary>☁️ <strong>Discover more about my one-person business: Towards the Cloud</strong></summary> <br/>

Hi, I'm Danny – AWS expert and founder of Towards the Cloud. With over a decade of hands-on experience, I specialized myself in deploying well-architected, highly scalable and cost-effective AWS Solutions using Infrastructure as Code (IaC).

When you work with me, you're getting a package deal of expertise and personalized service:

My mission is simple: I'll free you from infrastructure headaches so you can focus on what truly matters – your core business.

Ready to unlock the full potential of AWS Cloud?

<a href="https://towardsthecloud.com/contact"><img alt="Schedule your call" src="https://img.shields.io/badge/schedule%20your%20call-success.svg?style=for-the-badge"/></a>

</details>

AWS CDK Starterkit for Python Users

Looking for the Python version of this AWS CDK starter kit? Check out the AWS CDK Python Starterkit for a tailored experience that leverages the full power of AWS CDK with Python.

Acknowledgements

A heartfelt thank you to the creators of projen. This starter kit stands on the shoulders of giants, made possible by their pioneering work in simplifying cloud infrastructure projects!

Author

Danny Steenman