CloudFormation Concepts

CloudFormation is AWS’s infrastructure-as-code execution engine.
CDK uses it under the hood — understanding CloudFormation helps you debug deployment failures and understand what CDK is actually doing.

1. What Is CloudFormation?

CloudFormation is an AWS service that provisions and manages infrastructure from declarative templates.

You describe what you want (resources and their configuration), and CloudFormation figures out how to create, update, or delete them in the correct order.

Core idea:

Template (JSON/YAML) → CloudFormation Stack → AWS Resources

In the CDK context:

Python CDK Code → cdk synth → CloudFormation Template → cdk deploy → AWS Resources

2. Templates

A CloudFormation template is a JSON or YAML document that declares the resources to create.

Key Sections

Section	Required	Purpose
`AWSTemplateFormatVersion`	No	Template version (always `2010-09-09`)
`Description`	No	Human-readable description
`Parameters`	No	Input values at deploy time
`Resources`	Yes	The AWS resources to provision
`Outputs`	No	Values to export from the stack

Minimal Example

AWSTemplateFormatVersion: "2010-09-09"
Resources:
  MyBucket:
    Type: AWS::S3::Bucket
    Properties:
      VersioningConfiguration:
        Status: Enabled

CDK generates these templates for you in the cdk.out/ directory after cdk synth.

3. Stacks

A stack is the deployed instance of a template. It is CloudFormation’s unit of management.

One template → one stack
A stack owns all the resources it creates
You create, update, and delete stacks as a unit

In this assignment:

StorageStack → one CloudFormation stack (S3 buckets + DynamoDB)
LambdaStack → one CloudFormation stack (Lambdas + API Gateway + EventBridge)

Stack Naming

CDK uses the class name (e.g., StorageStack) as the CloudFormation stack name by default.

4. Stack Lifecycle States

Every stack has a status that reflects where it is in its lifecycle.

Normal States

State	Meaning
`CREATE_IN_PROGRESS`	Resources are being created
`CREATE_COMPLETE`	All resources created successfully
`UPDATE_IN_PROGRESS`	Resources are being updated
`UPDATE_COMPLETE`	All updates applied successfully
`DELETE_IN_PROGRESS`	Resources are being deleted
`DELETE_COMPLETE`	Stack fully deleted

Failure States

State	Meaning
`CREATE_FAILED`	Stack creation failed; CloudFormation may auto-rollback
`ROLLBACK_IN_PROGRESS`	Reversing a failed create
`ROLLBACK_COMPLETE`	Create failed and rolled back; stack exists but is empty
`UPDATE_ROLLBACK_IN_PROGRESS`	Reversing a failed update
`UPDATE_ROLLBACK_COMPLETE`	Update failed and rolled back to previous state
`UPDATE_ROLLBACK_FAILED`	Rollback itself failed; stack is stuck
`DELETE_FAILED`	Delete failed; stack is stuck

UPDATE_ROLLBACK_FAILED and DELETE_FAILED are the “stuck” states where normal CDK commands no longer work and you need to intervene directly through the CloudFormation console or CLI.

5. How CloudFormation Updates Work

When you run cdk deploy on an existing stack, CloudFormation computes a changeset — the diff between the current template and the new one.

Three possible outcomes per resource:

Action	Meaning
No change	Resource is unchanged; CloudFormation leaves it alone
Modify (in place)	Resource can be updated without replacement
Replace	The change requires creating a new resource and deleting the old one

Why Replacement Is Dangerous for Stateful Resources

Replacement means:

New resource is created (e.g., new S3 bucket)
Dependencies are re-wired to the new resource
Old resource is deleted

If the old resource holds data (S3 bucket with objects, DynamoDB table with records), that data is gone.

In this project, RemovalPolicy.DESTROY + auto_delete_objects=True makes this especially aggressive — CloudFormation will delete all bucket contents on resource deletion.

6. Logical IDs vs Physical Names

Every resource in a CloudFormation template has two identifiers:

Identifier	What It Is	Example
Logical ID	Name in the template; unique within the stack	`DataBucket`
Physical Name	Actual AWS resource name/ARN; may be auto-generated	`lambdastack-databucket12345-abc`

CDK generates logical IDs automatically from the construct tree path.

Best practice (and assignment requirement): do not hardcode physical names for deployable resources. Let CloudFormation generate them. This avoids naming conflicts when deploying to multiple accounts or regions.

Acceptable exception: DynamoDB GSI names are part of the table schema and are passed to Lambda code via environment variables.

7. Outputs and Cross-Stack References

Outputs

You can export values from one stack so other stacks or tools can use them.

Outputs:
  BucketName:
    Value: !Ref MyBucket
    Export:
      Name: MyStack-BucketName

Cross-Stack References in CDK

In CDK, passing a resource from one stack to another (e.g., passing the S3 bucket from StorageStack to LambdaStack) automatically creates CloudFormation outputs and imports.

# In app.py
storage = StorageStack(app, "StorageStack")
LambdaStack(app, "LambdaStack", data_bucket=storage.data_bucket)

This creates a hard dependency between the stacks. CloudFormation will:

Always deploy StorageStack before LambdaStack
Refuse to delete StorageStack while LambdaStack still imports its outputs

8. Custom Resources

Custom resources let CloudFormation invoke a Lambda to handle provisioning steps that CloudFormation doesn’t natively support.

In this project, CDK automatically creates:

Custom::S3BucketNotifications — configures S3 event notifications by invoking a CDK-managed Lambda

Why This Matters for Debugging

Custom resources run during the stack update/delete, not just at create time.

Common failure pattern in this project:

You delete or replace an S3 bucket
CloudFormation tries to clean up the old BucketNotifications custom resource
The custom resource Lambda tries to remove notifications from the deleted bucket
AWS returns NoSuchBucket
The custom resource fails → stack gets stuck in DELETE_FAILED

This is why stack cleanup sometimes requires the --retain-resources or --deletion-mode FORCE_DELETE_STACK flags.

9. The Bootstrap Stack

Before deploying CDK apps, you must run cdk bootstrap.

This creates a special CloudFormation stack named CDKToolkit in your account+region. It provisions:

An S3 bucket for storing synthesized assets (Lambda zips, etc.)
An ECR repository for Docker image assets
IAM roles that CloudFormation uses to deploy on CDK’s behalf

You only need to bootstrap once per account+region combination.

cdk bootstrap --app "./.venv/bin/python app.py"

10. Useful CloudFormation CLI Commands

View stack events (to diagnose failures)

aws cloudformation describe-stack-events \
  --stack-name StorageStack \
  --region us-east-1

View all stacks

aws cloudformation list-stacks \
  --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \
  --region us-east-1

Force-delete a stuck stack

aws cloudformation delete-stack \
  --stack-name StorageStack \
  --region us-east-1 \
  --retain-resources DataBucketNotifications11EB1C2E \
  --deletion-mode FORCE_DELETE_STACK

Wait for deletion to complete

aws cloudformation wait stack-delete-complete \
  --stack-name StorageStack \
  --region us-east-1

Describe a specific stack

aws cloudformation describe-stacks \
  --stack-name StorageStack \
  --region us-east-1

11. CDK → CloudFormation Mapping

CDK Action	What CloudFormation Does
`cdk synth`	Generates templates; nothing deployed yet
`cdk deploy`	Uploads assets, creates a changeset, executes it
`cdk destroy`	Calls `DeleteStack` on each stack
`cdk diff`	Creates a changeset (preview only, does not execute)

Key insight: CDK is just a template generator. CloudFormation is always the execution engine. When something goes wrong during deployment, the root cause is always in CloudFormation events — not in CDK output.

12. Quick Reference: What To Check When Deployment Fails

Run cdk deploy and note the error message
Open the AWS Console → CloudFormation → find the failing stack
Go to the Events tab — find the first FAILED event
Read the Status Reason — it usually names the exact resource and the exact API error
If the stack is stuck in UPDATE_ROLLBACK_FAILED or DELETE_FAILED, use the AWS CLI recovery commands above

CDK error messages are often just Failed resources: with a list of logical IDs. The actual error is always in the CloudFormation events.

Notes

Explorer

CloudFormation Concepts

CloudFormation Concepts

1. What Is CloudFormation?

2. Templates

Key Sections

Minimal Example

3. Stacks

Stack Naming

4. Stack Lifecycle States

Normal States

Failure States

5. How CloudFormation Updates Work

Why Replacement Is Dangerous for Stateful Resources

6. Logical IDs vs Physical Names

7. Outputs and Cross-Stack References

Outputs

Cross-Stack References in CDK

8. Custom Resources

Why This Matters for Debugging

9. The Bootstrap Stack

10. Useful CloudFormation CLI Commands

View stack events (to diagnose failures)

View all stacks

Force-delete a stuck stack

Wait for deletion to complete

Describe a specific stack

11. CDK → CloudFormation Mapping

12. Quick Reference: What To Check When Deployment Fails

Table of Contents

Graph View

Table of Contents