Skip to main content

intro

sdlcs-aws-cdk-lib

AWS CDK library with extended constructs, Blue-Green/Canary deployment patterns, and context-aware environment management.

npm version License: MIT

📚 Documentation​

Full Documentation →

🚀 Features​

  • Extended AWS CDK Constructs: Custom wrappers with automatic naming and tagging
  • Blue-Green Lambda Deployments: Zero-downtime deployments with automatic rollback
  • Context Strategy: Environment-aware configuration (dev, staging, prod, test, qa, preprod)
  • Package Metadata Integration: Automatic resource tagging from package.json
  • Canary Traffic Shifting: Gradual rollout with CodeDeploy integration
  • Type-Safe: Full TypeScript support with strict mode enabled

⚡ Quick Start​

# Install
npm install sdlcs-aws-cdk-lib aws-cdk-lib constructs

# Use in your CDK app
import { App, Stack } from 'sdlcs-aws-cdk-lib';

const app = new App();
const stack = new Stack(app, 'MyStack');

// Deploy
cdk deploy --context stage=dev

See the Quick Start Guide for a complete example.

📋 Prerequisites​

  • Node.js >= 22.0.0
  • npm >= 10.9.2
  • AWS CLI configured with appropriate credentials
  • AWS CDK v2.160.0 or later

🛠️ Development​

# Clone and install
git clone https://github.com/akfdev-com/sdlcs-aws-cdk-lib.git
cd sdlcs-aws-cdk-lib
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

📦 Project Structure​

sdlcs-aws-cdk-lib/
├── bin/                        # CDK app entry point
├── lib/                        # Example stacks
│   ├── SimpleStack.ts          # Blue-Green Lambda example
│   ├── GithubOidcStack.ts      # GitHub OIDC authentication
│   └── lambda/                 # Construct definitions
│       └── BlueGreenLambda.ts
├── src/                        # Core library code
│   └── contextStrategy/        # Context management
│       ├── ContextStrategy.ts
│       └── PackageJsonDetails.ts
├── src-extends-aws-cdk-lib/    # Extended CDK constructs
│   ├── App.ts                  # Extended App with ContextStrategy
│   ├── Stack.ts                # Extended Stack with auto-naming
│   ├── aws-lambda/             # Lambda extensions
│   ├── aws-lambda-nodejs/      # NodeJS Lambda extensions
│   └── ...                     # Other AWS service extensions
├── src-types/                  # TypeScript type definitions
├── lib-src/lambda/             # Lambda function source code
├── scripts/                    # Deployment utilities
└── docs/                       # Docusaurus documentation

🌐 Environments​

The library supports six SDLC environments mapped to three core environments:

SDLC EnvCore EnvDeploymentDescription
devdevAll-at-onceDevelopment
testdevAll-at-onceTesting
stagingstagingCanary 10% 5minPre-production
qastagingCanary 10% 5minQA testing
preprodstagingCanary 10% 15minFinal validation
prodprodLinear 10% 10minProduction

See Context Strategy Guide for details.

🏛️ Architecture​

Blue-Green Deployment Pattern​

Learn more in the Blue-Green Deployments Guide.

📖 Core Concepts​

Context Strategy​

Automatically manages environment configuration and naming:

import { App } from 'sdlcs-aws-cdk-lib';

const app = new App();
console.log(app.contextStrategy.sdlc);      // 'dev', 'staging', 'prod'
console.log(app.contextStrategy.sdlcCore);  // 'dev', 'staging', 'prod'

→ Context Strategy Guide

Extended Stack​

Automatic stack naming and resource tagging:

import { Stack } from 'sdlcs-aws-cdk-lib';

// Stack name automatically becomes: MyStack-dev (or MyStack-dev-feature-123)
const stack = new Stack(app, 'MyStack');

// Access context and package details
console.log(stack.contextStrategy.sdlc);
console.log(stack.packageDetails.version);

Blue-Green Lambda​

Zero-downtime Lambda deployments:

import { BlueGreenLambda } from './lib/lambda/BlueGreenLambda';

const lambda = new BlueGreenLambda(stack, 'API', {
  sdlc: stack.contextStrategy.sdlc,
  functionName: 'my-api',
  entry: './src/lambda/api/index.ts',
});

→ Lambda Patterns Guide

🔧 NPM Scripts​

Deployment​

npm run deploy              # Deploy all stacks (requires --context stage=<env>)
npm run deploy:dev          # Deploy to dev
npm run deploy:staging      # Deploy to staging
npm run deploy:prod         # Deploy to production
npm run diff                # Show pending changes
npm run synth               # Synthesize CloudFormation

Development​

npm run build               # Compile TypeScript
npm run watch               # Watch mode
npm test                    # Run tests  
npm run lint                # Lint code

Deployment Management​

npm run deployment:status   # Check deployment status
npm run deployment:rollback # Rollback deployment

Documentation​

npm run docs:dev            # Start documentation dev server
npm run docs:build          # Build documentation
npm run docs:serve          # Serve built documentation

🧪 Testing​

# Run all tests
npm test

# Test specific Lambda function
cd lib-src/lambda/exampleApi
npm test

See Lambda Patterns Guide for testing strategies.

🔐 Security​

  • Lambda functions follow least-privilege IAM principles
  • GitHub Actions uses OIDC (no long-lived credentials)
  • Automatic security tagging via PackageJsonDetails
  • CloudWatch Logs for comprehensive audit trails

See GitHub OIDC Setup for CI/CD configuration.

🤝 Contributing​

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit using Conventional Commits
  4. Push to your branch
  5. Open a Pull Request

Commit Convention​

feat(lambda): add new API endpoint
fix(stack): correct IAM permissions
docs: update deployment guide
chore(deps): update aws-cdk-lib to 2.160.0

See Commit Convention for guidelines.

📄 License​

MIT License - see LICENSE file

🆘 Support​

🔗 Additional Resources​