AWS CDK Starterkit

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

Towards the Cloud eliminates AWS complexity so you ship faster with confidence, cut costs by 30%, and become compliant.

Sounds too good to be true? We'll assess your AWS account for free and report exactly where you stand. You'll receive a report with security findings and cost optimization opportunities. After that you can decide whether to fix these findings yourself or let us handle it. No strings attached.

☁️ Discover how we cut AWS costs by 30% and accelerate SOC 2 compliance...

AWS complexity builds faster than you realize

What starts as a simple deployment quickly spirals into inefficient architectures that cost 40-60% more than needed, security blind spots that risk customer data, and teams that burnout from managing operations on AWS instead of building product.

Traditional consultancies prioritize billable hours over outcomes, then disappear after setup. We do the opposite...

We provide a complete package, so you deploy faster with confidence on AWS Cloud

✅ Compliant multi-account Landing Zone:
- Provisions AWS accounts with security guardrails out of the box - 100% CIS benchmark compliant
- Secure Single Sign-On (SSO) for clean user access management
- Everything is built using AWS CDK ensuring consistency, version control, and repeatable deployments
- See what features are already included in our landing zone on our public roadmap
✅ Off-the-shelf compliant CDK components: Develop secure infra quicker without reinventing the wheel
✅ Complete CI/CD with easy rollbacks: Deploy more frequently because of IaC safety
✅ Quarterly checks: Proactively receive Cost Optimization assessments + Security Reviews
✅ Fractional Cloud Engineer: On-demand access to a decade of AWS Cloud experience to help you use best practices

What results can you expect when you partner with us:

30% Lower AWS Bill: Proactive quarterly reviews catch overspending before it happens (30-60% documented savings)
Accelerate SOC 2/HIPAA compliance: Our Landing Zone automatically sets up security guardrails on your AWS accounts with 100% CIS compliance from day one
Easily stay compliant: Our automated monitoring and proactive quarterly security reviews give you control so yearly audits are smooth, not stressful
Your Team Ships Faster: Our Pre-built secure infrastructure components let your team focus on product, not AWS
Save on hiring costs: Access expert Cloud knowledge through our flexible retainer instead of committing to a full-time Cloud Engineer

Proof: Y Combinator startup Accolade's founder on how our Landing Zone accelerated their SOC 2 certification:

"Danny's solution and AWS expertise stood out with comprehensive accelerators, documentation, and clearly articulated design principles. We achieved a perfect security score in days, not months." — Galen Simmons, CEO

Features

⚡ Rapid Setup: Jumpstart your project within minutes by tweaking a single configuration file. Spend less time on boilerplate and more on building.
🤹‍♂️ Multi-Account Flexibility: Ready for enterprises, this starter kit supports multi-account setups right from the start, enabling scalable and segregated cloud environments.
🤖 Automated Deploy Pipelines: Embrace CI/CD with out-of-the-box GitHub Actions workflows, automating your deployment processes for efficiency and reliability.
🏗️ Project structure: The project is structured in a clean and intuitive way that allows you to easily manage your constructs and stacks for this CDK App.
🛡️ Seamless Security: Leverage OpenID Connect for secure AWS deployments. Authenticate your GitHub Actions workflows directly with AWS, eliminating the need for stored credentials or long-lived secrets.
🧹 Preconfigured TypeScript Excellence: Hit the ground running with pre-set compiler options in tsconfig.json, ensuring your code is clean, efficient, and error-free from the start.
📏 Best Practice Linting & Formatting: Adopt coding best practices effortlessly with a pre-configured Biome setup biome.jsonc, maintaining high code quality and consistency.
💻 Branch-based Deployments: Deploy 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.
📦 Automated Dependency Management: Dependabot creates grouped PRs, with auto-approval for passing checks using hmarr/auto-approve-action@v4, streamlining updates while maintaining project stability.

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:

Fork / clone this repo
Add a Personal Access Token to the repository settings on GitHub, follow these instructions for setting up a fine-grained personal access token.
Install the projects dependencies using: npm ci
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 },
};

Run npx projen to generate the github actions workflow files.
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)
Deploy the CDK toolkit stack to your AWS environment with cdk bootstrap if it's not already set up.
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.
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:

.
├── cdk.context.json
├── cdk.json
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
├── src
│   ├── assets
│   │   ├── ecs
│   │   │   └── example-container
│   │   └── lambda
│   │       └── example-lambda-function
│   ├── bin
│   │   ├── cicd-helper.ts
│   │   ├── env-helper.ts
│   │   └── git-helper.ts
│   ├── constructs
│   │   ├── base-construct.ts
│   │   ├── index.ts
│   │   ├── network-construct.ts
│   │   └── README.md
│   ├── main.ts
│   └── stacks
│       ├── foundation-stack.ts
│       ├── index.ts
│       ├── README.md
│       └── starter-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:

src/assets: Organizes the assets for your Lambda functions and ECS services, ensuring that the application code is neatly encapsulated with the infrastructure code.
src/bin: Contains utility scripts (e.g., cicd-helper.ts, env-helper.ts, git-helper.ts) that streamline environment setup and integration with CI/CD pipelines.
src/constructs: Houses the core building blocks of your infrastructure. These constructs can be composed into higher-level abstractions, promoting reusability across different parts of your infrastructure. Check out the README in the constructs folder to read how you can utilize environment-aware configurations.
src/stacks: Dedicated to defining stacks that represent collections of AWS resources (constructs). This allows for logical grouping of related resources, making it simpler to manage deployments and resource dependencies. Check out the README in the stacks folder to read how you can instantiate new stacks.
src/lib/main.ts: This is where the CDK app is instantiated.
test: Is the location to store your unit or integration tests (powered by jest)

Branch-based Deployments (Ephemeral Environments)

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.