Infrastructure Documentation

Overview

High-Level Architecture

Infrastructure Modules

The infrastructure is composed of 12 specialized Terraform modules, each handling a specific aspect of the system:

AWS Resources Summary

S3 Buckets Overview

Deployment Guide

Initial Deployment

# 1. Initialize OpenTofu
cd ../infra.sprkzdoc.com
tofu init

# 2. Review the plan
tofu plan -out=infrastructure.tfplan

# 3. Apply the infrastructure
tofu apply infrastructure.tfplan

# 4. Build and push Docker image
cd hello-world-app
docker build -t sprkzdoc-app:latest .

# 5. Login to ECR
aws ecr get-login-password --region us-west-2 | \
  docker login --username AWS --password-stdin \
  ${ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com

# 6. Tag and push image
docker tag sprkzdoc-app:latest \
  ${ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/sprkzdoc-application-dev:latest
docker push \
  ${ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/sprkzdoc-application-dev:latest

# 7. Deploy ECS service
./scripts/deploy-ecs-tasks.sh

Deployment Scripts

State Management

Cost Breakdown

Security Features

Data Protection

• Encryption at Rest: AES256 on all S3 buckets, RDS, and ElastiCache
• Encryption in Transit: TLS 1.2+ enforced on ALB, CloudFront, ElastiCache, RDS
• Secrets Management: All passwords and tokens stored in AWS Secrets Manager
• Password Generation: Auto-generated strong passwords (32+ characters)

Network Security

• VPC Isolation: Private subnets for database and cache layers
• Security Groups: Least privilege ingress/egress rules
• NAT Gateway: Masks private IP addresses for outbound traffic
• S3 Gateway Endpoint: Direct S3 access without internet routing
• CloudFront OAC: Origin Access Control for S3 bucket security

Identity & Access Management

• Separate IAM Roles: Task execution role vs. task runtime role
• Least Privilege: Task role only has required S3, SES, Secrets permissions
• Service-to-Service: VPC security group rules control inter-service communication
• No Hardcoded Credentials: All secrets retrieved from Secrets Manager at runtime

Audit & Compliance

• CloudTrail: All API calls logged to S3 with 7-day retention
• CloudWatch Logs: Centralized logging for ECS, RDS, SES, API Gateway
• X-Ray Tracing: Distributed tracing for performance and error analysis
• PHI Data: Restricted to private storage bucket with versioning and encryption

Monitoring & Observability

CloudWatch Log Groups

CloudWatch Alarms

Health Checks

• ALB Target Group: Health check on /health endpoint every 30 seconds
• ECS Service: Rolling deployment with circuit breaker protection
• RDS: Multi-AZ failover capability (manually managed in dev)
• ElastiCache: Automatic failure detection and recovery

Distributed Tracing

Troubleshooting Quick Reference

ECS Tasks Not Starting

# Check service events
aws ecs describe-services --cluster sprkzdoc-cluster-dev \
  --services sprkzdoc-application-service-dev

# View CloudWatch logs
aws logs tail /ecs/sprkzdoc-application-dev --follow

# Check task failures
aws ecs list-tasks --cluster sprkzdoc-cluster-dev \
  --desired-status STOPPED

Database Connection Issues

# Verify security group rules
aws ec2 describe-security-groups \
  --group-ids sg-034f3d950be0ee440

# Check RDS logs
aws logs tail /aws/rds/instance/sprkzdoc-mysql-dev/error \
  --follow

# Test database connectivity from ECS task
aws ecs execute-command --cluster sprkzdoc-cluster-dev \
  --task <task-id> --interactive --command "/bin/bash"

ACM Certificate Issues

# Verify CNAME records created
aws route53 list-resource-record-sets \
  --hosted-zone-id Z10449081GN434OHGYWP7 \
  --query "ResourceRecordSets[?Type=='CNAME']"

# Check certificate status
aws acm describe-certificate \
  --certificate-arn <arn> \
  --region us-east-1

CloudFront Deployment Issues

# Check distribution status
aws cloudfront get-distribution \
  --id E27W1P6D1AJLGE \
  --query 'Distribution.Status'

# Invalidate cache
aws cloudfront create-invalidation \
  --distribution-id E27W1P6D1AJLGE \
  --paths "/*"