AWS Architecture Base

A comprehensive AWS infrastructure framework built with CDKTF (Cloud Development Kit for Terraform) and Python, providing standardized deployment patterns for AWS Lightsail container services with automated SSL certificate management and domain attachment.

🏗️ Overview

The AWS Architecture Base provides a standardized foundation for deploying containerized applications on AWS Lightsail with enterprise-grade features including:

• Infrastructure as Code: Built on CDKTF with Python for type-safe infrastructure definitions
• Container Deployment: Automated Docker image building, tagging, and deployment to AWS Lightsail
• SSL/TLS Management: Automated SSL certificate creation and domain attachment
• Secret Management: Integration with AWS Secrets Manager for secure configuration
• Architecture Flags: Configurable deployment options for different environments
• Post-Deployment Automation: Customizable scripts for additional setup tasks

🚀 Features

Core Infrastructure

• Base Class Architecture: Extensible AWSArchitectureBase class for common AWS patterns
• Provider Management: Automatic setup of AWS, Random, and Null Terraform providers
• S3 Backend: Automated S3 bucket creation and Terraform state management
• Resource Registry: Centralized resource tracking and management

Container Deployment

• Lightsail Integration: Specialized BBAWSLightsailMiniV1aDeploy class for container services
• Docker Automation: Build, tag, and push workflows with caching support
• Environment Management: Configurable environment variables and secrets injection
• Health Checks: Automated health check configuration for container endpoints

Domain & SSL Management

• Custom Domains: LightSailDomainAttachWrapper for domain attachment automation
• SSL Certificates: Automatic certificate creation and validation
• DNS Integration: Route53 integration for domain management
• Fallback Guidance: Manual command generation for troubleshooting

Configuration Management

• Architecture Flags: Feature toggles for optional components
  • SKIP_DATABASE: Skip database creation
  • SKIP_DOMAIN: Skip domain and DNS configuration
  • SKIP_SSL_CERT: Skip SSL certificate creation
  • SKIP_DEFAULT_POST_APPLY_SCRIPTS: Skip default post-apply scripts
• Environment Profiles: Support for multiple AWS profiles and regions
• Archetype Integration: Integration with Buzzerboy archetype patterns

📦 Installation

Prerequisites

• Python 3.8 or higher
• AWS CLI configured with appropriate credentials
• Docker (for container deployments)
• Node.js (for CDKTF)

Install from Package Registry

# Install from Buzzerboy's private registry
pip install AWSArchitectureBase

Development Installation

# Clone the repository
git clone <repository-url>
cd AWSArchitectureBase

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

🔧 Quick Start

Basic Container Service Deployment

from AWSArchitectureBase.AWSArchitectureBaseStack import AWSArchitectureBase, ArchitectureFlags
from cdktf import App

app = App()

# Get archetype configuration
archetype = AWSArchitectureBase.get_archetype(
    product='myapp', 
    app='api',  
    tier='dev', 
    organization='myorg', 
    region='ca-central-1'
)

# Configuration flags
ArchitectureFlags = AWSArchitectureBase.get_architecture_flags()
flags = [
    ArchitectureFlags.SKIP_DATABASE.value,
    ArchitectureFlags.SKIP_SSL_CERT.value,
]

# Custom domains
domains = [
    f"{archetype.get_tier()}.api.example.com"
]

# Post-deployment scripts
post_apply_scripts = [
    "echo '📋 Deployment verification complete'",
    "echo '📋 Container service is ready'",
]

# Create the stack
stack = AWSArchitectureBase(
    app, 
    "my-lightsail-service",
    project_name=archetype.get_project_name(),
    environment=archetype.get_tier(),
    region=archetype.get_region(),
    secret_name=archetype.get_secret_name(),
    profile="default",
    flags=flags,
    domains=domains,
    state_bucket_name="my-tfstate-bucket",
    postApplyScripts=post_apply_scripts,
)

archetype.set_stack(stack)
app.synth()

Container Deployment Automation

from AWSArchitectureBase.AWSArchitectureBaseStack import AWSArchitectureDeploy

# Initialize deployment helper
deployer = AWSArchitectureDeploy(
    product='myapp',
    app='api',
    tier='dev',
    organization='myorg',
    region='ca-central-1',
    debug=True,
    version='1.0.0'
)

# Execute deployment pipeline
deployer.app_deploy()

Domain Attachment with SSL

from AWSArchitectureBase.AWSArchitectureBaseStack.LightSailDomainAttachWrapper import LightSailDomainAttachWrapper

# Initialize domain wrapper
domain_wrapper = LightSailDomainAttachWrapper(
    domains=["api.example.com", "app.example.com"],
    region="ca-central-1",
    container_service_name="my-app-service"
)

# Get attachment script
attach_script = domain_wrapper.get_attach_command()
print(attach_script)

🏛️ Architecture

Project Structure

AWSArchitectureBase/
├── AWSArchitectureBaseStack/
│   ├── __init__.py
│   ├── AWSArchitectureBase.py          # Main base class
│   ├── ArchitectureFlags.py            # Configuration flags
│   ├── BBAWSLightsailMiniV1aDeploy.py  # Container deployment
│   └── LightSailDomainAttachWrapper.py # Domain management
├── pyproject.toml                      # Package configuration
├── requirements.txt                    # Python dependencies
└── Makefile                           # Build automation

Key Components

AWSArchitectureBase Class

The core infrastructure class providing:

• Terraform provider initialization
• S3 backend configuration
• Resource registry management
• Architecture flag handling
• Utility methods for AWS naming conventions

BBAWSLightsailMiniV1aDeploy Class

Container deployment automation including:

• Docker image building and caching
• AWS Lightsail container service management
• Secret management integration
• Environment variable configuration
• Deployment pipeline orchestration

LightSailDomainAttachWrapper Class

Domain and SSL management featuring:

• SSL certificate creation and validation
• Custom domain attachment automation
• DNS integration support
• Manual fallback command generation

🔐 Configuration

Environment Variables

export AWS_PROFILE=your-profile
export AWS_REGION=ca-central-1
export VERBOSE=true  # Enable verbose logging

Architecture Flags

Control deployment features using architecture flags:

from AWSArchitectureBase.AWSArchitectureBaseStack import ArchitectureFlags

flags = [
    ArchitectureFlags.SKIP_DATABASE.value,      # Skip RDS/database setup
    ArchitectureFlags.SKIP_SSL_CERT.value,      # Skip SSL certificate creation
    ArchitectureFlags.SKIP_DOMAIN.value,        # Skip domain configuration
    ArchitectureFlags.SKIP_DEFAULT_POST_APPLY_SCRIPTS.value,  # Skip default scripts
]

AWS Secrets Manager

Store application secrets in AWS Secrets Manager:

{
  "database_url": "postgresql://...",
  "api_keys": "...",
  "jwt_secret": "..."
}

Secret path format: {organization}/{tier}/{product}-{app}-{tier}

🚀 Deployment

Using CDKTF

# Initialize and plan
cdktf init
cdktf plan

# Deploy infrastructure
cdktf deploy

# Destroy when needed
cdktf destroy

Using Make (for package development)

# Clean and build
make clean build

# Publish to registry
make publish TYPE=patch  # or minor, major

📋 Examples

Multi-Environment Deployment

# Development environment
dev_stack = AWSArchitectureBase(
    app, "my-app-dev",
    environment="dev",
    region="ca-central-1",
    flags=[ArchitectureFlags.SKIP_SSL_CERT.value]
)

# Production environment
prod_stack = AWSArchitectureBase(
    app, "my-app-prod",
    environment="prod",
    region="us-east-1",
    flags=[]  # All features enabled
)

Custom Post-Deploy Scripts

post_apply_scripts = [
    "echo '📋 Running database migrations'",
    "python manage.py migrate",
    "echo '📋 Warming up application cache'",
    "curl -X POST https://api.example.com/warmup",
    "echo '📋 Notifying monitoring systems'",
    "curl -X POST https://monitoring.example.com/deploy-complete"
]

🧪 Testing

Unit Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=AWSArchitectureBase

Integration Tests

# Test infrastructure deployment
cdktf plan --var-file=test.tfvars

# Test container deployment
python test_deployment.py

🔧 Development

Setup Development Environment

# Clone repository
git clone <repository-url>
cd AWSArchitectureBase

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

# Install development dependencies
pip install -r requirements.txt
pip install -e .

# Install pre-commit hooks
pre-commit install

Building and Publishing

# Version bump and build
make publish TYPE=patch

# Manual build
python -m build
twine upload dist/*

📖 API Reference

AWSArchitectureBase Methods

• get_architecture_flags(): Get available configuration flags
• get_archetype(): Get archetype configuration
• has_flag(): Check if architecture flag is set
• get_extra_secret_env(): Parse extra secrets from environment
• execute_post_apply_scripts(): Run post-deployment scripts

Utils Module

• properize_string(string): Convert string to valid AWS resource name
• clean_hyphens(string): Convert string for database naming
• parse_secrets_from_env(env_var_name): Parse JSON secrets from environment

BBAWSLightsailMiniV1aDeploy Methods

• app_deploy(): Execute complete deployment pipeline
• build_docker_image(): Build Docker image for deployment
• push_docker_image(): Push image to Lightsail registry
• deploy_docker_image(): Deploy container service
• get_container_fqdn(): Get container service URL

LightSailDomainAttachWrapper Methods

• get_attach_command(): Generate domain attachment script
• get_certificate_creation_command(): Generate SSL cert creation command
• get_domain_attachment_command(): Generate domain attachment command

🐛 Troubleshooting

Common Issues

SSL Certificate Validation Timeout

# Check certificate status
aws lightsail get-certificates --region ca-central-1 --include-certificate-details

# Manual domain attachment after validation
aws lightsail update-container-service \
  --service-name my-service \
  --region ca-central-1 \
  --public-domain-names '{"example.com": ["example.com"]}'

Docker Build Failures

# Clear Docker cache
docker system prune -a

# Rebuild without cache
docker build --no-cache -t my-service .

Terraform State Issues

# Refresh state
cdktf refresh

# Import existing resources
cdktf import aws_lightsail_container_service.example my-service

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to your branch (git push origin feature/amazing-feature)
8. Create a Pull Request

Code Standards

• Follow PEP 8 style guidelines
• Add type hints for all public methods
• Include docstrings for classes and methods
• Write unit tests for new functionality
• Update documentation for API changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏢 About Buzzerboy

AWS Architecture Base is developed and maintained by Buzzerboy Inc. For enterprise support and consulting services, contact us at info@buzzerboy.com.

🔗 Related Projects

• BuzzerboyArchetype - Enterprise archetype patterns
• CDKTF Documentation - Cloud Development Kit for Terraform
• AWS Lightsail - AWS Lightsail container services

---

Made with ❤️ by the Buzzerboy Team