Build Your First AWS CDK Stack: A Beginner-Friendly Tutorial

Working With CDK Constructs

AWS CDK apps rely on constructs as their essential structural elements. Your infrastructure code will become more modular, maintainable, and readable when you master constructs, whether you use built-in service constructs or create your reusable patterns.

This section teaches you about using L2 (high-level) constructs and how to develop custom constructs that reduce repetitive patterns.

Using L2 constructs

L2 constructs are CDK-native abstractions that are easier to use than raw CloudFormation  (L1). They have sensible defaults and type safety, often requiring fewer lines of code to set up an AWS resource.

Why use L2 constructs?

• Less boilerplate — fewer required fields compared to L1
• More readable and idiomatic Python code
• Includes utility methods like .add_to_role_policy() or .add_event_notification()
• Automatically manages dependencies between resources

Example: Creating an S3 bucket using L2

from aws_cdk import aws_s3 as s3
# Create a versioned and encrypted S3 bucket
bucket = s3.Bucket(
    self,
    "MyBucket",
    versioned=True,
    encryption=s3.BucketEncryption.S3_MANAGED
)

The equivalent L1 construct, s3.CfnBucket, would need all properties manually set up and configuration defined as raw dicts—much less intuitive.

Other common L2 constructs include:

• lambda_.Function() for AWS Lambda
• dynamodb.Table() for DynamoDB
• sqs.Queue() for SQS
• sns.Topic() for SNS

Creating custom constructs

Your infrastructure will expand with recurring patterns, such as creating Lambda functions with particular permissions and S3  buckets. Custom constructs serve as the ideal solution for this specific scenario.

Custom constructs enable you to combine related resources into a single logical unit, which can be reused across stacks or projects.

When to create a custom construct:

• When you have 3+ resources that are always provisioned together
• When you want to encapsulate reusable logic
• When you want to reduce code duplication across stacks

Example: A reusable S3 + Lambda pattern

from constructs import Construct
from aws_cdk import aws_s3 as s3, aws_lambda as lambda_
class StorageWithLambda(Construct):
    def __init__(self, scope: Construct, id: str) -> None:
        super().__init__(scope, id)
        # S3 bucket
        self.bucket = s3.Bucket(self, "MyBucket")

        # Lambda function
        self.function = lambda_.Function(
            self,
            "MyFunction",
            runtime=lambda_.Runtime.PYTHON_3_9,
            handler="index.handler",
            code=lambda_.Code.from_asset("lambda")
        )
        # Grant Lambda access to the S3 bucket
        self.bucket.grant_read_write(self.function)

You can now use this construct inside any stack like this:

from my_project.storage_with_lambda import StorageWithLambda
storage = StorageWithLambda(self, "ReusableComponent")

Before running the above, create a folder named lambda in the project root and create a file index.py with the following content:

def handler(event, context):
    return {
        "statusCode": 200,
        "body": "Hello from Lambda!"
    }

Reusability tips

• Prefix files with construct_ or place inside a constructs/ folder
• Expose outputs like self.bucket or self.function for flexibility
• Keep each construct focused on one responsibility

Testing and Synthesizing CDK Apps

After writing your infrastructure code, it is essential to check what the CDK will deploy and ideally test that your stacks behave as expected. The AWS CDK provides tools to synthesize CloudFormation templates and write automated tests to catch misconfigurations before deployment.

Synthesizing templates

The cdk synth command generates the CloudFormation template from your CDK code.

cdk synth

When you run this, the CDK:

• Loads your app (via app.py)
• Resolves all constructs and stacks
• Outputs raw YAML/JSON CloudFormation templates

Synthesized CloudFormation template 

By default, the output goes to your terminal, but you can also output to a file if needed:

cdk synth > template.yaml

This is useful when:

• You want to inspect the actual template before deploying
• You're debugging a stack’s structure
• You're sharing the template with teams who aren’t using CDK

Testing infrastructure

Although testing infrastructure as code might sound unusual, it is beneficial, especially when your stacks get large or include conditional logic, loops, or reusable constructs.

The AWS CDK offers the assertions module to test synthesized stacks.

Writing a simple test with pytest

Here's an example test that checks if a specific resource (like an S3 bucket) is included in the stack:

# test/test_cdk_datacamp_stack.py
import aws_cdk as cdk
from aws_cdk.assertions import Template
from cdk_datacamp.cdk_datacamp_stack import CdkDatacampStack
def test_s3_bucket_created():
    app = cdk.App()
    stack = CdkDatacampStack(app, "TestStack")
    template = Template.from_stack(stack)
    # Assert that an S3 bucket exists
    template.resource_count_is("AWS::S3::Bucket", 1)

To run the tests, make sure pytest is installed:

pip install -U pytest

Then run:

pytest

If everything passes, you’ll see a green checkmark. If not, the test output will tell you what's missing.

Pytest output showing successful execution of all test cases for the AWS CDK stack

You can also include validation in your CDK stack. Validation tests are runtime checks inside your construct or stack code that validate inputs before deployment happens. They help catch misconfigurations or enforce constraints early in the development lifecycle.

Let’s say we want to pass the bucket_name as a context variable, but we want to validate that:

• The bucket name is not empty
• It meets S3 naming rules (e.g., lowercase only)

Create a file named test/test_storage_with_lambda.py and add the following:

import pytest
from aws_cdk import App, Stack
from cdk_datacamp.storage_with_lambda import StorageWithLambda

def test_missing_bucket_name():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="bucket_name is required"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name=None)

def test_bucket_name_uppercase():
    app = App()
    stack = Stack(app, "TestStack")

    with pytest.raises(ValueError, match="must be lowercase"):
        StorageWithLambda(stack, "FailingConstruct", bucket_name="InvalidName")

 To test the validation, run the below command:

test/test_storage_with_lambda.py

Pytest output showing successful execution of all test cases for the AWS CDK stack

When to use testing:

• You're creating reusable constructs or patterns.
• The implementation of testing serves to establish standard technical requirements among team members.
• You want to catch regressions or unintended changes during CI/CD.

Want to reinforce your CDK knowledge in an interview setting? These top AWS DevOps interview questions can help you prepare.

Best Practices and Tips for Working with the AWS CDK

After mastering CDK stack creation and deployment, you should follow best practices to keep your infrastructure code clean, secure, and scalable. This section will discuss how to structure large projects, handle security correctly, and integrate CDK into CI/CD pipelines.

Organizing large projects

As your CDK app grows, organizing code into manageable units becomes essential.

Use multiple stacks

Split your infrastructure by concern. For example:

• NetworkingStack: VPCs, subnets, security groups
• ComputeStack: EC2, Lambda
• StorageStack: S3, DynamoDB

This allows you to deploy, test, or destroy parts of your infrastructure independently. Here’s how it can be included in app.py:

network_stack = NetworkingStack(app, "NetworkingStack")
compute_stack = ComputeStack(app, "ComputeStack")

You can also pass resources between stacks using outputs or references.

Create reusable nested constructs

Encapsulate related resources (like a Lambda and its permissions) into a custom construct, as you did with StorageWithLambda. This improves readability and reusability across stacks or apps.

Use environment-specific configuration

Support multiple environments (dev, staging, prod) using:

• cdk.json with context values
• CLI overrides: cdk deploy -c env=prod
• Conditional logic in your stacks

env = app.node.try_get_context("env")
if env == "prod":
    bucket_name = "mycompany-prod-logs"

Security and permissions

Any infrastructure project must prioritize security during AWS CDK automated deployment processes. The following section demonstrates secure IAM resource management through least privilege principles.

Define IAM roles instead of using defaults

CDK constructs, which include Lambda or ECS tasks, will automatically create IAM roles. Although convenient, it can limit your control over permissions and naming.

Instead, define roles explicitly:

from aws_cdk import aws_iam as iam

execution_role = iam.Role(
    self,
    "LambdaExecutionRole",
    assumed_by=iam.ServicePrincipal("lambda.amazonaws.com"),
    description="Custom role for Lambda with least privilege",
    managed_policies=[
        iam.ManagedPolicy.from_aws_managed_policy_name("service-role/AWSLambdaBasicExecutionRole")
    ]
)

This role only allows logging and nothing else by default.

Apply the principle of least privilege

Avoid using "*" in actions or resources unless absolutely necessary.

Example:

lambda_fn.add_to_role_policy(
    iam.PolicyStatement(
        actions=["*"],
        resources=["*"]
    )
)

You can also use resource-specific grants when available:

bucket.grant_read(lambda_fn)

This automatically generates the necessary policy with scoped access to the S3 bucket.

Use managed policies when possible

AWS-managed policies simplify maintenance and reduce the chance of errors.

iam.ManagedPolicy.from_aws_managed_policy_name("AmazonSQSReadOnlyAccess")

You can attach these to custom roles for services like ECS, Batch, or Step Functions.

CI/CD integration

The AWS CDK delivers exceptional power through its ability to integrate with contemporary CI/CD pipelines. CDK supports automated infrastructure delivery through version-controlled code deployment, which works with GitHub, GitLab, and AWS-native services, including CodePipeline. The system decreases human mistakes while shortening feedback cycles and enables deployment across multiple environments.

GitHub Actions: Automating CDK deployments

You can use GitHub Actions to synthesize, diff, test, and deploy CDK stacks on every push or pull request.

Take a look at this .github/workflows/deploy.yml:

name: Deploy CDK App

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - uses: actions/setup-python@v4
        with:
          python-version: 3.11

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          npm install -g aws-cdk

      - name: Run unit tests
        run: pytest

      - name: CDK Synth
        run: cdk synth -c environment=prod

      - name: Deploy to AWS
        run: cdk deploy --require-approval never
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Use cdk diff in PRs to preview infra changes before merging.

CDK pipelines: Native CDK CI/CD with CodePipeline

For fully-managed deployments within AWS, CDK provides a module called aws_cdk.pipelines, which lets you define your entire CI/CD pipeline as code, just like infrastructure.

Here’s a simplified example:

from aws_cdk import pipelines, SecretValue, Stack
from constructs import Construct
from my_app_stage import MyAppStage  # replace with your actual stage import

class PipelineStack(Stack):
    def __init__(
        self,
        scope: Construct,
        construct_id: str,
        **kwargs
    ) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Define the source of the pipeline from a GitHub repository
        source = pipelines.CodePipelineSource.git_hub(
            repo_string="your-org/your-repo",  # GitHub org/repo
            branch="main",
            authentication=SecretValue.secrets_manager("GITHUB_TOKEN")
        )

        # Define the CodePipeline and its synthesis step
        pipeline = pipelines.CodePipeline(
            self,
            "MyAppPipeline",
            synth=pipelines.ShellStep(
                "Synth",
                input=source,
                commands=[
                    "pip install -r requirements.txt",
                    "npm install -g aws-cdk",
                    "cdk synth"
                ]
            )
        )

        # Add an application stage (e.g., production deployment)
        pipeline.add_stage(
            MyAppStage(self, "ProdStage")
        )

In the above code:

• SecretValue.secrets_manager("GITHUB_TOKEN") securely pulls your GitHub token from Secrets Manager.
• MyAppStage should be a class that extends Stage and wraps your actual CDK stacks.

If you're deploying machine learning systems, integrating CDK with continuous deployment practices is covered in our CI/CD for Machine Learning course.

Conclusion

This tutorial showed you how to construct and deploy cloud infrastructure in Python through AWS Cloud Development Kit (CDK) operations. You learned how to:

• Create your first CDK stack.
• Define and validate S3 buckets and Lambda functions as resources.
• Organize a project through custom constructs and multi-stack patterns.
• Apply security best practices through the principle of least privilege.
• Automate deployments by combining GitHub Actions with CDK Pipelines.
• Write tests to validate your infrastructure logic.

Now that you’ve deployed your first CDK app, here are a few ways to level up:

• Use parameterized environments for dev/staging/prod
• Add CloudWatch alarms, API Gateway, or Step Functions
• Explore CDK constructs like aws_s3_deployment, aws_ecs_patterns, and cdk.pipelines
• Convert your constructs into an internal Python library for reusability

To keep learning and building, check out the Introduction to AWS Boto in Python course!