cdk-common

Enterprise-grade AWS CDK constructs library providing reusable infrastructure components for the Fastish platform.

---

Overview

This library provides a comprehensive set of AWS CDK constructs that power the Fastish infrastructure platform. It implements a configuration-driven approach using Mustache templating to transform YAML configurations into type-safe Java objects during CDK synthesis. The library follows CDK Best Practices and AWS Well-Architected Framework principles.

Key Features

Feature	Description	Reference
Reusable Constructs	Production-ready CDK constructs for common AWS patterns	AWS CDK Constructs
Template Processing	Mustache-based configuration templating	Mustache
Type Safety	YAML to Java POJO serialization via Jackson	Jackson YAML
Environment Support	Multi-environment configuration resolution	CDK Context

---

Requirements

Requirement	Version	Reference
Java	21+	OpenJDK 21
Maven	3.8+	Maven
AWS CDK	2.221.0+	AWS CDK

---

Installation

Add the dependency to your Maven pom.xml:

<dependency>
    <groupId>io.tinstafl</groupId>
    <artifactId>cdk-common</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Build from source:

git clone https://github.com/fast-ish/cdk-common.git
cd cdk-common
mvn clean install

---

AWS Service Coverage

The library provides constructs for the following AWS services:

Compute

Service	Construct	Reference
Lambda	Function, Layer, EventSourceMapping	AWS Lambda
EKS	Cluster, NodeGroup, Addon, HelmChart	Amazon EKS

Storage

Service	Construct	Reference
S3	Bucket, BucketPolicy, LifecycleRule	Amazon S3
EBS	Volume, Snapshot	Amazon EBS

Database

Service	Construct	Reference
DynamoDB	Table, GlobalSecondaryIndex, Stream	Amazon DynamoDB
RDS	Instance, Cluster, ParameterGroup	Amazon RDS

Networking

Service	Construct	Reference
VPC	Vpc, Subnet, SecurityGroup, NatGateway	Amazon VPC
API Gateway	RestApi, Resource, Method, Authorizer	Amazon API Gateway
Load Balancers	ALB, NLB, TargetGroup, Listener	Elastic Load Balancing

Security

Service	Construct	Reference
IAM	Role, Policy, ManagedPolicy	AWS IAM
Cognito	UserPool, UserPoolClient, IdentityPool	Amazon Cognito
KMS	Key, Alias	AWS KMS
Secrets Manager	Secret, SecretRotation	AWS Secrets Manager

Messaging

Service	Construct	Reference
SQS	Queue, DeadLetterQueue	Amazon SQS
SNS	Topic, Subscription	Amazon SNS
SES	EmailIdentity, ConfigurationSet	Amazon SES

Analytics

Service	Construct	Reference
Athena	WorkGroup, DataCatalog	Amazon Athena
Kinesis	Stream, FirehoseDeliveryStream	Amazon Kinesis
MSK	Cluster, Configuration	Amazon MSK

Monitoring

Service	Construct	Reference
CloudWatch	Alarm, Dashboard, LogGroup	Amazon CloudWatch
BCM	DataExport, CostAllocationTag	AWS Billing

DevOps

Service	Construct	Reference
CodeBuild	Project, BuildSpec	AWS CodeBuild
ECR	Repository, LifecyclePolicy	Amazon ECR

---

Build Process

The cdk-common library implements a four-stage build process during CDK synthesis:

CDK Context → Template Resolution → Mustache Processing → POJO Mapping

Stage 1: CDK Context Injection

Context variables from cdk.context.json are extracted and made available as template variables:

{
  ":account": "123456789012",
  ":region": "us-west-2",
  ":environment": "prototype",
  ":version": "v1"
}

See: CDK Context

Stage 2: Template Resolution

Templates are loaded from the environment/version directory structure:

src/main/resources/
└── {environment}/
    └── {version}/
        ├── conf.mustache
        └── {component}/
            └── *.mustache

Example: prototype/v1/conf.mustache

Stage 3: Mustache Processing

Mustache templating engine processes variables:

# Input template
vpc:
  name: {{hosted:id}}-vpc
  cidr: 10.0.0.0/16
  region: {{region}}

# After processing
vpc:
  name: abc123-vpc
  cidr: 10.0.0.0/16
  region: us-west-2

Stage 4: POJO Mapping

Processed YAML is deserialized into Java configuration objects via Jackson:

@Data
public class VpcConfig {
    private String name;
    private String cidr;
    private String region;
}

---

Platform Integration

This library is used by all Fastish infrastructure projects:

Project	Description	Integration
aws-webapp-infra	Serverless web application stack	VPC, Cognito, DynamoDB, API Gateway, Lambda, SES
aws-eks-infra	EKS Kubernetes cluster	VPC, EKS, IAM, SQS
aws-druid-infra	Apache Druid analytics platform	VPC, EKS, RDS, S3, MSK

When deployed through the Fastish platform, additional internal services coordinate deployment automation:

Component	Purpose
Orchestrator	Release pipeline automation via CodePipeline
Portal	Multi-tenant subscriber management
Network	Shared VPC infrastructure
Reporting	Usage metering and cost attribution

---

Documentation

Build Process

Document	Description
Build Process Flow	Complete CDK synthesis flow
Template System	Template resolution and processing
Context Variables	Available template variables
Template Structure	Organization patterns

Architecture Decisions

Document	Description
ADR-001: Template Resolution	Environment/version path structure
ADR-002: Mustache Processing	Template engine choice
ADR-003: Context Injection	CDK context system

Developer Workflow

Document	Description
Developer Guide	How to use the library
Build Internals	What happens during synthesis
Troubleshooting	Common issues and solutions

Technical Deep Dive

Document	Description
Template Engine	Processing implementation
Context System	CDK context integration
Serialization	Jackson YAML mapping
Quick Reference	Template variables and patterns

---

Quick Reference

Context Variables

Variable	Type	Description
{{account}}	String	AWS account ID
{{region}}	String	AWS region
{{environment}}	String	Environment name (e.g., prototype)
{{version}}	String	Resource version (e.g., v1)
{{hosted:id}}	String	Unique deployment identifier
{{domain}}	String	Route 53 domain name

Template Patterns

# Simple substitution
name: {{hosted:id}}-resource

# Conditional sections
{{#enabled}}
feature:
  active: true
{{/enabled}}

# Iteration
subnets:
{{#subnets}}
  - id: {{id}}
    cidr: {{cidr}}
{{/subnets}}

# Inverted sections (if not)
{{^production}}
debug: true
{{/production}}

See: Mustache Manual

---

Troubleshooting

Quick Diagnostics

# Verify Maven build
mvn clean install -DskipTests

# Check for dependency conflicts
mvn dependency:tree | grep -i conflict

# Validate Mustache template syntax
mvn test -Dtest=TemplateProcessorTest

# Debug template resolution
mvn -X cdk synth 2>&1 | grep -i "template\|mustache"

# Verify context injection
cat cdk.context.json | jq '.'

Common Issues

Issue	Symptom	Resolution
Template not found	FileNotFoundException during synthesis	Verify environment/version path exists in src/main/resources/
Mustache syntax error	MustacheException with template location	Check for unclosed tags {{#section}}...{{/section}}
YAML parsing failure	JsonMappingException during deserialization	Validate YAML syntax and ensure fields match POJO properties
Context variable missing	null values in generated resources	Add missing variable to cdk.context.json
Version mismatch	CDK synthesis errors	Ensure cdk-common version matches infrastructure project

For detailed troubleshooting procedures, see the Troubleshooting Guide.

---

Related Links

Platform Documentation

Resource	Description
Fastish Documentation	Platform documentation home
aws-webapp-infra	Serverless web application stack
aws-eks-infra	EKS Kubernetes cluster
aws-druid-infra	Apache Druid analytics platform
Troubleshooting Guide	Common issues and solutions
Validation Guide	Deployment validation procedures
Upgrade Guide	Upgrade and rollback procedures
Glossary	Platform terminology
Changelog	Version history

AWS Documentation

Resource	Description
AWS CDK Documentation	Official CDK documentation
AWS CDK API Reference	CDK API reference
AWS CDK Workshop	Interactive CDK tutorial
CDK Best Practices	CDK application patterns
CDK Patterns	Community CDK patterns
AWS Well-Architected Framework	Architecture best practices
CloudFormation User Guide	CloudFormation documentation

Template Processing

Resource	Description
Mustache Templates	Mustache templating documentation
Mustache Manual	Mustache syntax reference
Jackson YAML	YAML processing library
Jackson Data Binding	Jackson object mapping

---

License

MIT License

For your convenience, you can find the full MIT license text at:

• https://opensource.org/license/mit/ (Official OSI website)
• https://choosealicense.com/licenses/mit/ (Choose a License website)