Terraformer 3.1 is released. Find out →
Advanced
Provision on AWS

AWS CDK Quickstart Guide

Introduction

This guide provides a comprehensive walkthrough for setting up and using AWS CDK (Cloud Development Kit) to manage your cloud infrastructure as code. AWS CDK allows you to define your cloud resources using familiar programming languages.

Prerequisites

  • Node.js and npm installed
  • AWS CLI installed and configured with your AWS credentials
  • Basic understanding of TypeScript (or your chosen CDK language)
  • AWS account with necessary permissions

Step 1: Install AWS CDK

Install the AWS CDK globally using npm:

npm install -g aws-cdk

Verify the installation:

cdk --version

Step 2: Set Up Your Project

  1. Create a new directory for your project and navigate into it:
mkdir my-cdk-project
cd my-cdk-project
  1. Initialize a new CDK project with TypeScript:
cdk init app --language typescript

This command creates a new CDK project with a basic structure and necessary configuration files.

Step 3: Configure Environment Variables

Set up the UPLOADS_BUCKET_NAME environment variable with a unique value:

export UPLOADS_BUCKET_NAME=<unique>-cruddur-uploaded-avatars
gp env UPLOADS_BUCKET_NAME=<unique>-cruddur-uploaded-avatars

Replace <unique> with a unique identifier for your project.

Step 4: Bootstrap AWS Environment

Bootstrap your AWS environment to prepare it for CDK deployments:

cdk bootstrap "aws://<AWSID>/<AWSREGION>"

Replace <AWSID> with your AWS account ID and <AWSREGION> with your desired AWS region (e.g., ca-central-1).

This command sets up the following resources:

  • An S3 bucket for storing assets (e.g., cdk-hnb659fds-assets-<AWSID>-<AWSREGION>)
  • A CloudFormation stack named CDKToolkit
  • An ECR repository for Docker images

Step 5: Develop Your CDK Stack

  1. Open the lib/<your-stack-name>-stack.ts file in your project directory.
  2. Define your AWS resources using the CDK constructs. For example:
import * as cdk from 'aws-cdk-lib';
import * as s3 from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';
 
export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);
 
    new s3.Bucket(this, 'MyBucket', {
      bucketName: process.env.UPLOADS_BUCKET_NAME,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      autoDeleteObjects: true,
    });
  }
}

Step 6: Synthesize and Deploy

  1. Synthesize your CDK app to generate the CloudFormation template:
cdk synth

This command checks for errors and outputs the resulting CloudFormation template.

  1. Deploy your stack:
cdk deploy

This command will show you a summary of the changes and prompt for confirmation before deploying.

Step 7: Verify Deployment

After deployment, verify that your resources have been created:

  1. Check if the S3 bucket was created:
aws s3api wait bucket-exists --bucket $UPLOADS_BUCKET_NAME
  1. You can also verify other resources through the AWS Management Console or appropriate AWS CLI commands.

Additional Useful Commands

  • npm run build: Compile TypeScript to JavaScript
  • npm run watch: Watch for changes and compile
  • npm run test: Perform Jest unit tests
  • cdk diff: Compare deployed stack with current state
  • cdk destroy: Delete the deployed stack and its resources

Best Practices

  1. Version Control: Always keep your CDK code in version control (e.g., Git).
  2. Use Constructs: Leverage existing CDK constructs and create custom ones for reusable components.
  3. Environment Separation: Use different stacks or accounts for different environments (dev, staging, prod).
  4. Security: Follow the principle of least privilege when defining IAM roles and policies.
  5. Cost Management: Be aware of the resources you're creating and their associated costs.

Troubleshooting

  • If you encounter permission errors, ensure your AWS CLI is configured with the correct credentials and has the necessary permissions.
  • For deployment failures, check the CloudFormation events in the AWS Console for detailed error messages.
  • If the cdk synth command fails, review your TypeScript code for syntax errors or missing dependencies.

Conclusion

AWS CDK provides a powerful way to define your cloud infrastructure as code. By following this guide, you've set up a basic CDK project, bootstrapped your AWS environment, and learned how to deploy and manage your resources. Continue exploring the AWS CDK documentation to learn about more advanced features and best practices.

Resources

Design DirectoriesVIM Master